edu.nrao.sss.model.source
Class Subsource

java.lang.Object
  edu.nrao.sss.model.source.Subsource

All Implemented Interfaces:

Identifiable, Cloneable, Comparable<Subsource>

public class Subsource
extends Object
implements Identifiable, Cloneable, Comparable<Subsource>

A portion of an extended astronomical source.

Version Info:

$Revision: 1709 $

$Date: 2008-11-14 11:22:37 -0700 (Fri, 14 Nov 2008) $

$Author: dharland $

Since:

2006-06-07

Author:

David M. Harland

Field Summary

Fields inherited from interface edu.nrao.sss.util.Identifiable

UNIDENTIFIED

Constructor Summary

Subsource()
Creates a new unnamed instance.

Subsource(String name)
Creates a new instance with the given name.

Method Summary

void	addBrightness(SourceBrightness newBrightness) Adds newBrightness to this subsource.
void	addVelocity(SourceVelocity newVelocity) Adds newVelocity to this subsource.
Frequency	calcShiftedFrequency(Frequency restFreq, EarthPosition observer, Date dateTime) Returns an observed frequency based on a rest frequency and the relative motion between this source and an earth-bound observer.
LinearVelocity	calcVelocityRelativeTo(EarthPosition observer, Date dateTime) Returns the velocity of this subsource toward or away from the observer at the given point in time.
Subsource	clone() Returns a copy of this subsource.
int	compareTo(Subsource other) Compares this subsource to other for order.
boolean	equals(Object o) Returns true if o is equal to this subsource.
SourceBrightness	getBrightness(Frequency frequency, Date time, StokesParameter polarization) Returns the source brightness that matches the given parameters, if any.
List<SourceBrightness>	getBrightnesses() Returns this subsource's collection of brightnesses.
Map<StokesParameter,SourceBrightness>	getBrightnesses(Frequency frequency, Date time) Returns a map where the key is a StokesParameter and the value is a source brightness.
SortedSet<SourceBrightness>	getBrightnesses(Frequency frequency, StokesParameter polarization) Returns a set of this subsource's brightnesses that match the given criteria.
Long	getId()
String	getName() Returns the name of this subsource.
SkyPosition	getPosition() Returns the position of this subsource.
List<SourceVelocity>	getVelocities() Returns this subsource's collection of velocities.
SourceVelocity	getVelocity(Frequency frequency) Returns the source velocity for the given frequency, if any.
int	hashCode() Returns a hash code value for this subsource.
boolean	isMoving() Returns true if the position of this subsource at time T could be different than its position at time U ≠ T.
void	removeAllBrightnesses() Removes all brightness entries from this subsource.
void	removeAllVelocities() Removes all velocity entries from this subsource.
void	removeBrightness(SourceBrightness oldBrightness) Removes oldBrightness from this subsource.
void	removeVelocity(SourceVelocity oldVelocity) Removes oldVelocity from this subsource.
void	reset() Resets this subsource to its initial state.
void	resetPosition() Resets this subsource's position information so that it looks like that of a newly created subsource.
void	setBrightnesses(List<SourceBrightness> replacementList) Replaces this subsource's collection of brightnesses with replacementList.
void	setName(String newName) Sets the name of this subsource.
void	setPosition(SkyPosition newPosition) Sets the position of this subsource.
void	setVelocities(List<SourceVelocity> replacementList) Replaces this subsource's collection of velocities with replacementList.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Subsource

public Subsource()

Creates a new unnamed instance.

Subsource

public Subsource(String name)

Creates a new instance with the given name.

Method Detail

reset

public void reset()

Resets this subsource to its initial state. A reset subsource has the same state as a new subsource.

resetPosition

public void resetPosition()

Resets this subsource's position information so that it looks like that of a newly created subsource. This means that the position type will be polynomial and that the table of polynomial positions will be empty.

isMoving

public boolean isMoving()

Returns true if the position of this subsource at time T could be different than its position at time U ≠ T.

The determination of motion will be made with respect to the coordinate system in which the position of this subsource is expressed. For example, a position that is expressed in the equatorial system, and that is holding steady at its position in that system, will said to be not moving, even though in other coordinate systems it may be moving quite rapidly.

This is a convenience method that is equivalent to calling getPosition().isMoving().

Returns:

true if this subsource is moving.

getId

public Long getId()

Specified by:

getId in interface Identifiable

setName

public void setName(String newName)

Sets the name of this subsource.

If newName is null or the empty string (""), the request to change the name will be denied and the current name will remain in place.

Parameters:

newName - the new name for this subsource.

getName

public String getName()

Returns the name of this subsource.

Returns:

the name of this subsource.

addBrightness

public void addBrightness(SourceBrightness newBrightness)

Adds newBrightness to this subsource. If newBrightness is null, no action is taken.

Parameters:

newBrightness - the new brightness to be added to this subsource.

removeBrightness

public void removeBrightness(SourceBrightness oldBrightness)

Removes oldBrightness from this subsource.

If this subsource is not holding oldBrightness, this method does nothing.

Parameters:

oldBrightness - the brightness to be removed from this subsource.

removeAllBrightnesses

public void removeAllBrightnesses()

Removes all brightness entries from this subsource.

setBrightnesses

public void setBrightnesses(List<SourceBrightness> replacementList)

Replaces this subsource's collection of brightnesses with replacementList.

Note that this subsource will hold a reference to replacementList (unless it is null); it will not store a copy. This means that any changes a client makes to replacementList after calling this method will be reflected in this subsource.

Parameters:

replacementList - a replacement list of brightnesses for this subsource. If replacementList is null, it will be interpreted as an empty list.

getBrightnesses

public List<SourceBrightness> getBrightnesses()

Returns this subsource's collection of brightnesses.

Note that returned list is the one actually held by this subsource, not a clone thereof. That means that any changes that a client makes to the list will affect this subsource.

Returns:

this subsource's collection of brightnesses. The value returned is guaranteed to be non-null, though it may be an empty list.

getBrightnesses

public SortedSet<SourceBrightness> getBrightnesses(Frequency frequency,
                                                   StokesParameter polarization)

Returns a set of this subsource's brightnesses that match the given criteria. A match is made when a source brightness contains frequency as a valid frequency and has the some polarization as polarization.

Parameters:

frequency - a valid frequency for a source brightness. The special value of null is a signal to select a brightness without respect to its valid frequency range.

polarization - the polarization that all brightnesses in the returned set will have. The special value of nullReturns:

the set of this subsource's brightnesses that match the given parameters. The return value is guaranteed to be non-null. The returned set may be empty, though.

getBrightnesses

public Map<StokesParameter,SourceBrightness> getBrightnesses(Frequency frequency,
                                                             Date time)

Returns a map where the key is a StokesParameter and the value is a source brightness. There will be zero or one brightness for each polarization.

Calling this method once is similar to calling getBrightness(Frequency, Date, StokesParameter) for every polarization parameter.

Parameters:

frequency - a valid frequency for the source brightnesses in the returned map. The use of a null value is not recommended here.

time - the time for which the source brightnesses is requested. The returned brightness will have a valid time interval that contains this time.

Returns:

a map of polarization / brightness pairs.

getBrightness

public SourceBrightness getBrightness(Frequency frequency,
                                      Date time,
                                      StokesParameter polarization)

Returns the source brightness that matches the given parameters, if any.

The search for a matching brightness is done by first filtering on frequency and polarization. (See getBrightnesses(Frequency, StokesParameter) for details.) At this point there should be only zero or one matching brightness¹. However, if there are multiple brightnesses, the first one found that has a valid time range that contains time will be returned. If there are no matches, null is returned.

¹Ideally this class would prevent clients from adding new brightnesses that have the same polarization and frequency, and a coincident or overlapping valid time range, as one already held by this subsource. At this time, this class does not have such a mechanism.

Parameters:

frequency - a valid frequency for a source brightness. The use of a null value is not recommended here.

time - the time for which a source brightness is requested. The returned brightness will have a valid time interval that contains this time.

polarization - the polarization that all brightnesses in the returned set will have. The use of a null value is not recommended here.

Returns:

the source brightness that matches the given parameters, or null if there is no match.

addVelocity

public void addVelocity(SourceVelocity newVelocity)

Adds newVelocity to this subsource. If newVelocity is null, no action is taken.

Parameters:

newVelocity - the new velocity to be added to this subsource.

removeVelocity

public void removeVelocity(SourceVelocity oldVelocity)

Removes oldVelocity from this subsource.

If this subsource is not holding oldVelocity, this method does nothing.

Parameters:

oldVelocity - the velocity to be removed from this subsource.

removeAllVelocities

public void removeAllVelocities()

Removes all velocity entries from this subsource.

setVelocities

public void setVelocities(List<SourceVelocity> replacementList)

Replaces this subsource's collection of velocities with replacementList.

Note that this subsource will hold a reference to replacementList (unless it is null); it will not store a copy. This means that any changes a client makes to replacementList after calling this method will be reflected in this subsource.

Parameters:

replacementList - a replacement list of velocities for this subsource. If replacementList is null, it will be interpreted as an empty list.

getVelocities

public List<SourceVelocity> getVelocities()

Returns this subsource's collection of velocities.

Note that returned list is the one actually held by this subsource, not a clone thereof. That means that any changes that a client makes to the list will affect this subsource.

Returns:

this subsource's collection of velocities. The value returned is guaranteed to be non-null, though it may be an empty list.

getVelocity

public SourceVelocity getVelocity(Frequency frequency)

Returns the source velocity for the given frequency, if any.

There should be only zero or one matching velocity for any single frequency¹. However, if there are multiple velocities, the first one found that has a valid frequency range that contains frequency will be returned. If there are no matches, null is returned.

¹Ideally this class would prevent clients from adding new velocities that have the frequency ranges that overlap with one already held by this subsource. At this time, this class does not have such a mechanism.

Parameters:

frequency - a valid frequency for a source velocity.

Returns:

the source velocity that contains frequency, or null if this subsource holds no such velocity.

calcVelocityRelativeTo

public LinearVelocity calcVelocityRelativeTo(EarthPosition observer,
                                             Date dateTime)
                                      throws CoordinateConversionException

Returns the velocity of this subsource toward or away from the observer at the given point in time.

Parameters:

observer - a position on earth. The radial velocity of this subsource is calculated relative to this observer.

dateTime - the point in time at which the velocity is calculated.

Returns:

the radial velocity of this subsource toward or away from a point on earth.

Throws:

CoordinateConversionException - if the position of this subsource cannot be converted to an equatorial RA / Dec position.

Since:

2008-07-29

calcShiftedFrequency

public Frequency calcShiftedFrequency(Frequency restFreq,
                                      EarthPosition observer,
                                      Date dateTime)
                               throws CoordinateConversionException

Returns an observed frequency based on a rest frequency and the relative motion between this source and an earth-bound observer.

Parameters:

restFreq - the rest frequency for which an observed frequency is requested.

observer - a position on earth. The relative radial velocity between this observer and this source determines the amount by which the restFreq is shifted into an observed frequency.

dateTime - the time for which the velocity calculation is performed.

Returns:

an observed frequency based on restFreq and the relative motion between this source and the observer.

Throws:

CoordinateConversionException - if the position of this subsource cannot be converted to an equatorial RA / Dec position.

Since:

2008-07-29

setPosition

public void setPosition(SkyPosition newPosition)

Sets the position of this subsource.

If newPosition is null, this method does nothing. Otherwise this subsource will hold a reference to newPosition.

Parameters:

newPosition - a new position for this subsource.

getPosition

public SkyPosition getPosition()

Returns the position of this subsource.

The value returned is guaranteed to be non-null. It is also a reference to the position actually held by this subsource, so any changes made to it by clients will be reflected in this object.

Returns:

the position of this subsource.

clone

public Subsource clone()

Returns a copy of this subsource.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this subsource.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this subsource.

Overrides:

hashCode in class Object

compareTo

public int compareTo(Subsource other)

Compares this subsource to other for order.

Note that this method is not consistent with equals. Only the name attribute is used for ordering. There is a special name, CENTER, that is deemend to precede all other names. Otherwise, alphabetical ordering is used.

Specified by:

compareTo in interface Comparable<Subsource>

Parameters:

other - the subsource to which this one is compared.

Returns:

a negative integer, zero, or a positive integer as this subsource is less than, equal to, or greater than the other subsource.