edu.nrao.sss.model.source
Class Source

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

All Implemented Interfaces:

CatalogItem<SourceCatalogEntry>, NameableCatalogItem<SourceCatalogEntry>, SourceCatalogEntry, UserAccountable, Identifiable, Nameable, Cloneable

public class Source
extends Object
implements SourceCatalogEntry

An astronomical emitter of radio waves.

Version Info:

$Revision: 1709 $

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

$Author: dharland $ (last person to modify)

Since:

2006-02-24

Author:

David M. Harland

Field Summary

static String

CENTER_POSITION_NAME

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

UNIDENTIFIED

Fields inherited from interface edu.nrao.sss.model.UserAccountable

NULL_USER_ID

Constructor Summary

Source()
Creates a new unnamed source.

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

Method Summary

void	addSubsource(Subsource newSubsource) Adds newSubsource to this source.
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 source toward or away from the observer at the given point in time.
void	clearId() Resets this entry's ID, and the IDs of all its components, to a value that represents the unidentified state.
Source	clone() Returns a source that is equal to this one.
boolean	equals(Object o) Returns true if o is equal to this source.
static Source	fromXml(Reader reader) Creates a new source based on the XML data read from reader.
static Source	fromXml(String xmlFile) Creates a new source from the XML data in the given file.
Source	get(Date pointInTime) Returns the source associated with this entry as of the given point in time.
List<String>	getAliases() Returns a list of other names by which this source is known.
Subsource	getCentralSubsource() Returns the subsource that represents the center position of this source.
Long	getCreatedBy() Returns the ID of the user who created this object.
Date	getCreatedOn() Returns the date on which this object was created.
List<String>	getHistoricalRecords() Returns one element of text for each historical record held by this source.
Long	getId()
List<SourceImageLink>	getImageLinks() Returns a collection of links to images of this source.
Long	getLastUpdatedBy() Returns the ID of the user who most recently updated this object.
Date	getLastUpdatedOn() Returns the most recent date on which this object was updated.
List<URL>	getLinks() Returns a list of URL links to more information about this source.
String	getName() Returns the name of this source.
List<String>	getNotes() Returns a list of notes about this source.
String	getOriginOfInformation() Returns the origin of this source's information.
SkyPosition	getPosition() Returns the position of this source.
SortedSet<Subsource>	getSubsources() Returns this source's collection of subsources.
SortedMap<String,String>	getUserDefinedValues() Returns a collection of user-defined key/value pairs.
int	hashCode() Returns a hash code value for this source.
boolean	isMoving() Returns true if the position of this source at time T could be different than its position at time U ≠ T.
static String	makeUdbKeyVlaCalibQuality(ReceiverBand band, TelescopeConfiguration cfg) Returns text that can be used as a key for the user defined values map.
static String	makeUdbKeyVlaCalibQuality(String bandCode, String teleCfgCode) Returns text that can be used as a key for the user defined values map.
static String	makeUdbKeyVlaUvMax(ReceiverBand band) Returns text that can be used as a key for the user defined values map.
static String	makeUdbKeyVlaUvMax(String bandCode) Returns text that can be used as a key for the user defined values map.
static String	makeUdbKeyVlaUvMin(ReceiverBand band) Returns text that can be used as a key for the user defined values map.
static String	makeUdbKeyVlaUvMin(String bandCode) Returns text that can be used as a key for the user defined values map.
void	removeAllSubsources() Removes all subsources from this source.
void	removeSubsource(Subsource oldSubsource) Removes oldSubsource from this source.
void	reset() Resets this source to its initial state.
void	setCreatedBy(Long userId) Sets the ID of the user who created this object.
void	setCreatedOn(Date d) Sets the date on which this object was created.
void	setId(Long id) Do not use.
void	setLastUpdatedBy(Long userId) Sets the ID of the user who most recently updated this object.
void	setLastUpdatedOn(Date d) Sets the date on which this object was most recently updated.
void	setName(String newName) Sets the name of this source.
void	setOriginOfInformation(String origin) Sets the origin of this source's information.
void	setSubsources(SortedSet<Subsource> replacementSet) Replaces this source's collection of subsources with replacementSet.
String	toString() Returns a text representation of this source.
String	toXml() Returns an XML representation of this source.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this source to writer.

Methods inherited from class java.lang.Object

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

Field Detail

CENTER_POSITION_NAME

public static final String CENTER_POSITION_NAME

See Also:

Constant Field Values

Constructor Detail

Source

public Source()

Creates a new unnamed source. The new source will have one subsource. The name of that subsource will be CENTER_POSITION_NAME.

Source

public Source(String name)

Creates a new instance with the given name. The new source will have one subsource. The name of that subsource will be CENTER_POSITION_NAME.

Method Detail

reset

public void reset()

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

get

public Source get(Date pointInTime)

Description copied from interface: SourceCatalogEntry

Returns the source associated with this entry as of the given point in time.

Specified by:

get in interface SourceCatalogEntry

Parameters:

pointInTime - the time at which a source is desired.

Returns:

the source associated with this entry as of the given point in time.

isMoving

public boolean isMoving()

Returns true if the position of this source 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 source 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 getCentralSubsource().isMoving().

Returns:

true if this source is moving.

getId

public Long getId()

Specified by:

getId in interface Identifiable

setId

public void setId(Long id)

Description copied from interface: SourceCatalogEntry

Do not use. This method is here for the persistence mechanism. Other clients should not set object identifiers.

Specified by:

setId in interface SourceCatalogEntry

clearId

public void clearId()

Description copied from interface: SourceCatalogEntry

Resets this entry's ID, and the IDs of all its components, to a value that represents the unidentified state.

This method is useful for preparing an entry for storage in a database. The ID property (as of now, though this may change in the future) is used by our persistence mechanism to identify objects. If you are persisting this entry for the first time, you may need to call this method before performing a save. This is especially true if you have created this source from XML, as the XML unmarshalling brings along the ID property.

Specified by:

clearId in interface SourceCatalogEntry

setName

public void setName(String newName)

Sets the name of this source.

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.

Specified by:

setName in interface SourceCatalogEntry

Specified by:

setName in interface Nameable

Parameters:

newName - the new name for this source.

getName

public String getName()

Returns the name of this source.

Specified by:

getName in interface SourceCatalogEntry

Specified by:

getName in interface Nameable

Returns:

the name of this source.

getUserDefinedValues

public SortedMap<String,String> getUserDefinedValues()

Returns a collection of user-defined key/value pairs. The returned map may be empty, but is guaranteed to be non-null.

Note that the returned map is the one actually held by this object. This means that any changes made to the returned map will be reflected in this source. It also means that to add, delete, or change a keyword mapping, clients call this method and then operate directly on the returned map.

Returns:

a collection of user-defined key/value pairs.

makeUdbKeyVlaCalibQuality

public static String makeUdbKeyVlaCalibQuality(ReceiverBand band,
                                               TelescopeConfiguration cfg)

Returns text that can be used as a key for the user defined values map. The returned key is used to get a VLA calibrator quality code and consists of some boiler plate text, a code for the receiver band, and a code for the telescope configuration.

Parameters:

band - the receiver band for which a key is desired.

cfg - the telescope configuration for which a key is desired.

Returns:

text that can be used as a user defined value key.

Since:

2008-07-25

makeUdbKeyVlaCalibQuality

public static String makeUdbKeyVlaCalibQuality(String bandCode,
                                               String teleCfgCode)

Returns text that can be used as a key for the user defined values map. The returned key is used to get a VLA calibrator quality code and consists of some boiler plate text, a code for the receiver band, and a code for the telescope configuration.

Parameters:

bandCode - a code for a receiver band. By convention this should be a value returned by the getDisplayName() method of ReceiverBand.

teleCfgCode - a code for a telescope configuration. By convention this should be a value returned by the getCode method of TelescopeConfiguration.

Returns:

text that can be used as a user defined value key.

Since:

2008-07-25

makeUdbKeyVlaUvMax

public static String makeUdbKeyVlaUvMax(ReceiverBand band)

Returns text that can be used as a key for the user defined values map. The returned key is used to get a UV_max value and consists of some boiler plate text and a code for the receiver band.

Parameters:

band - the receiver band for which a key is desired.

Returns:

text that can be used as a user defined value key.

Since:

2008-07-25

makeUdbKeyVlaUvMax

public static String makeUdbKeyVlaUvMax(String bandCode)

Returns text that can be used as a key for the user defined values map. The returned key is used to get a UV_max value and consists of some boiler plate text and a code for the receiver band.

Parameters:

bandCode - a code for a receiver band. By convention this should be a value returned by the getDisplayName() method of ReceiverBand.

Returns:

text that can be used as a user defined value key.

Since:

2008-07-25

makeUdbKeyVlaUvMin

public static String makeUdbKeyVlaUvMin(ReceiverBand band)

Returns text that can be used as a key for the user defined values map. The returned key is used to get a UV_min value and consists of some boiler plate text and a code for the receiver band.

Parameters:

band - the receiver band for which a key is desired.

Returns:

text that can be used as a user defined value key.

Since:

2008-07-25

makeUdbKeyVlaUvMin

public static String makeUdbKeyVlaUvMin(String bandCode)

Returns text that can be used as a key for the user defined values map. The returned key is used to get a UV_min value and consists of some boiler plate text and a code for the receiver band.

Parameters:

bandCode - a code for a receiver band. By convention this should be a value returned by the getDisplayName() method of ReceiverBand.

Returns:

text that can be used as a user defined value key.

Since:

2008-07-25

setOriginOfInformation

public void setOriginOfInformation(String origin)

Sets the origin of this source's information.

Parameters:

origin - the origin of this source's information. A value of null will be replaced by a non-null default value.

getOriginOfInformation

public String getOriginOfInformation()

Returns the origin of this source's information.

Returns:

the origin of this source's information.

getAliases

public List<String> getAliases()

Returns a list of other names by which this source is known. The returned list may be empty, but is guaranteed to be non-null.

Note that the returned list is the one actually held by this object. This means that any changes made to the returned list will be reflected in this source. It also means that to add or delete an alias, clients call this method and then operate directly on the returned list.

Returns:

a list of other names by which this source is known.

getImageLinks

public List<SourceImageLink> getImageLinks()

Returns a collection of links to images of this source. The returned list may be empty, but is guaranteed to be non-null.

Note that the returned list is the one actually held by this object. This means that any changes made to the returned list will be reflected in this source. It also means that to add, delete, or change an image link, clients call this method and then operate directly on the returned list.

Returns:

a collection of user-defined key/value pairs.

getHistoricalRecords

public List<String> getHistoricalRecords()

Returns one element of text for each historical record held by this source. Each record is free-form text, but most clients are expected to structure the text in some way, perhaps as XML or as delimited key=value pairs.

This method returns the list actually held by this Source, so any list manipulations may be performed by first fetching the list and then operating on it.

Returns:

a list of historical records for this source.

getNotes

public List<String> getNotes()

Returns a list of notes about this source. Each note is free-form text with no particular structure.

This method returns the list actually held by this Source, so any list manipulations may be performed by first fetching the list and then operating on it.

Specified by:

getNotes in interface SourceCatalogEntry

Returns:

a list of notes about this source.

getLinks

public List<URL> getLinks()

Returns a list of URL links to more information about this source.

This method returns the list actually held by this Source, so any list manipulations may be performed by first fetching the list and then operating on it.

Returns:

a list of links that refer to this source.

addSubsource

public void addSubsource(Subsource newSubsource)

Adds newSubsource to this source. If newSubsource is null, no action is taken.

Parameters:

newSubsource - the new subsource to be added to this source.

removeSubsource

public void removeSubsource(Subsource oldSubsource)

Removes oldSubsource from this source.

If this source is not holding oldSubsource, this method does nothing.

Parameters:

oldSubsource - the subsource to be removed from this source.

removeAllSubsources

public void removeAllSubsources()

Removes all subsources from this source.

setSubsources

public void setSubsources(SortedSet<Subsource> replacementSet)

Replaces this source's collection of subsources with replacementSet.

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

Parameters:

replacementSet - a replacement set of subsources for this source. If replacementSet is null, it will be interpreted as an empty set.

getSubsources

public SortedSet<Subsource> getSubsources()

Returns this source's collection of subsources.

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

Returns:

this source's collection of subsources. The value returned is guaranteed to be non-null, though it may be an empty set.

getCentralSubsource

public Subsource getCentralSubsource()

Returns the subsource that represents the center position of this source.

This method will search this source's set of subsources for one whose name is CENTER_POSITION_NAME. If no such subsource is found, an arbitrary subsource will be returned. If this source has no subsources the returned value will be null.

Returns:

the central subsource, or null.

getPosition

public SkyPosition getPosition()

Returns the position of this source. This is a convenience method that is equivalent to calling getCentralSubsource().getPosition().

Returns:

the position of this source.

calcVelocityRelativeTo

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

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

Parameters:

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

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

Returns:

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

Throws:

CoordinateConversionException - if the position of this source 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 source cannot be converted to an equatorial RA / Dec position.

Since:

2008-07-29

setCreatedBy

public void setCreatedBy(Long userId)

Description copied from interface: UserAccountable

Sets the ID of the user who created this object.

If userId is null, this object will be updated not with null but with UserAccountable.NULL_USER_ID instead.

Specified by:

setCreatedBy in interface UserAccountable

Parameters:

userId - the ID of the user who most recently updated this object.

setCreatedOn

public void setCreatedOn(Date d)

Description copied from interface: UserAccountable

Sets the date on which this object was created.

If d is null it will be ignored and this method will do nothing.

Specified by:

setCreatedOn in interface UserAccountable

Parameters:

d - the date on which this object was created.

setLastUpdatedBy

public void setLastUpdatedBy(Long userId)

Description copied from interface: UserAccountable

Sets the ID of the user who most recently updated this object.

If userId is null, this object will be updated not with null but with UserAccountable.NULL_USER_ID instead.

Specified by:

setLastUpdatedBy in interface UserAccountable

Parameters:

userId - the ID of the user who most recently updated this object.

setLastUpdatedOn

public void setLastUpdatedOn(Date d)

Description copied from interface: UserAccountable

Sets the date on which this object was most recently updated.

If d is null it will be ignored and this method will do nothing.

Specified by:

setLastUpdatedOn in interface UserAccountable

Parameters:

d - the date on which this object was most recently updated.

getCreatedBy

public Long getCreatedBy()

Description copied from interface: UserAccountable

Returns the ID of the user who created this object.

If this object does not know the identity of the user who created it, the returned ID will be UserAccountable.NULL_USER_ID.

Specified by:

getCreatedBy in interface UserAccountable

Returns:

the ID of the user who created this object.

getCreatedOn

public Date getCreatedOn()

Description copied from interface: UserAccountable

Returns the date on which this object was created.

Specified by:

getCreatedOn in interface UserAccountable

Returns:

the date on which this object was created.

getLastUpdatedBy

public Long getLastUpdatedBy()

Description copied from interface: UserAccountable

Returns the ID of the user who most recently updated this object.

If this object does not know the identity of the user who lasted updated it, the returned ID will be UserAccountable.NULL_USER_ID.

Specified by:

getLastUpdatedBy in interface UserAccountable

Returns:

the ID of the user who most recently updated this object.

getLastUpdatedOn

public Date getLastUpdatedOn()

Description copied from interface: UserAccountable

Returns the most recent date on which this object was updated.

Specified by:

getLastUpdatedOn in interface UserAccountable

Returns:

the most recent date on which this object was updated.

toString

public String toString()

Returns a text representation of this source. The default form of the text is XML. However, if anything goes wrong during the conversion to XML, an alternate, and much abbreviated, form will be returned.

Overrides:

toString in class Object

Returns:

a text representation of this source.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this source.

Returns:

an XML representation of this source.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

See Also:

writeAsXmlTo(Writer)

writeAsXmlTo

public void writeAsXmlTo(Writer writer)
                  throws JAXBException

Writes an XML representation of this source to writer.

Parameters:

writer - the device to which XML is written.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

fromXml

public static Source fromXml(String xmlFile)
                      throws JAXBException,
                             XMLStreamException,
                             FileNotFoundException

Creates a new source from the XML data in the given file.

Parameters:

xmlFile - the name of an XML file. This method will attempt to locate the file by using Class.getResource(String).

Returns:

a new source from the XML data in the given file.

Throws:

FileNotFoundException - if the XML file cannot be found.

JAXBException - if the schema file used (if any) is malformed, if the XML file cannot be read, or if the XML file is not schema-valid.

XMLStreamException - if there is a problem opening the XML file, if the XML is not well-formed, or for some other "unexpected processing conditions".

fromXml

public static Source fromXml(Reader reader)
                      throws JAXBException,
                             XMLStreamException

Creates a new source based on the XML data read from reader.

Parameters:

reader - the source of the XML data. If this value is null, null is returned.

Returns:

a new source based on the XML data read from reader.

Throws:

XMLStreamException - if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the transformation.

clone

public Source clone()

Returns a source that is equal to this one.

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

Specified by:

clone in interface CatalogItem<SourceCatalogEntry>

Overrides:

clone in class Object

equals

public boolean equals(Object o)

Returns true if o is equal to this source.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this source.

Overrides:

hashCode in class Object