edu.nrao.sss.model.resource
Class SkyFrequencySpecification

java.lang.Object
  edu.nrao.sss.model.resource.SkyFrequencySpecification

All Implemented Interfaces:

Cloneable

public class SkyFrequencySpecification
extends Object
implements Cloneable

A specification for observing a portion of the electromagnetic spectrum. Instances of this class are used to help choose and configure instrumentation that can obtain data that conform to the encapsulated specifications.

Version Info:

$Revision: 1709 $

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

$Author: dharland $

Since:

2006-09-12

Author:

David M. Harland

Constructor Summary

SkyFrequencySpecification()
Creates a new instance.

SkyFrequencySpecification(FrequencyRange skyFrequencyRange)
Creates a new instance using the given range.

Method Summary

SkyFrequencySpecification	clone() Returns a specification that is a copy of this one.
boolean	equals(Object o) Returns true if o is equal to this specification.
static SkyFrequencySpecification	fromXml(Reader reader) Creates a new specification based on the XML data read from reader.
static SkyFrequencySpecification	fromXml(String xmlFile) Creates a new specification from the XML data in the given file.
SortedMap<String,String>	getAdditionalSpecifications() Returns any additional specifications for this specification.
FrequencyRange	getFrequencyRange() Returns the range of sky frequencies to use for this specification.
Frequency	getFrequencyResolution() Returns the width of a single sky frequency channel.
long	getNumberOfSpectralChannels() Returns the number of whole spectral channels in this specification.
SortedSet<StokesParameter>	getPolarizationProducts() Returns the polarization products requested by this specification.
TimeDuration	getTimeResolution() Returns the time resolution of this specification.
int	hashCode() Returns a hash code value for this specification.
void	setAdditionalSpecifications(SortedMap<String,String> newMap) Sets a map of key/value pairs that hold additional specifications.
void	setFrequencyRange(FrequencyRange newRange) Sets the range of sky frequencies to use for this specification.
void	setFrequencyResolution(Frequency width) Sets the width of a single sky frequency channel.
void	setPolarizationProducts(SortedSet<StokesParameter> newSet) Sets the polarization products requested by this specification.
void	setTimeResolution(TimeDuration resolution) Sets the time resolution of this specification.
String	toString() Returns a text representation of this specification.
String	toXml() Returns an XML representation of this specification.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this specification to writer.

Methods inherited from class java.lang.Object

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

Constructor Detail

SkyFrequencySpecification

public SkyFrequencySpecification()

Creates a new instance.

SkyFrequencySpecification

public SkyFrequencySpecification(FrequencyRange skyFrequencyRange)

Creates a new instance using the given range.

Method Detail

setFrequencyRange

public void setFrequencyRange(FrequencyRange newRange)

Sets the range of sky frequencies to use for this specification.

Unless newRange is null, this object will hold a reference to the parameter, so any changes made to it will be reflected in this object. A value of null will be interpreted as a range that contains all positive frequencies.

Parameters:

newRange - the range of sky frequencies to use for this specification.

getFrequencyRange

public FrequencyRange getFrequencyRange()

Returns the range of sky frequencies to use for this specification.

Note that the returned range is the one held by this specification, so any changes made to it will be reflected in this object. This value is guaranteed to be non-null.

Returns:

the range of sky frequencies to use for this specification.

setFrequencyResolution

public void setFrequencyResolution(Frequency width)

Sets the width of a single sky frequency channel.

Unless width is null, this object will hold a reference to the parameter, so any changes made to it will be reflected in this object. A value of null will be interpreted as a frequency of zero gigahertz.

Parameters:

width - the width of a single sky frequency channel.

getFrequencyResolution

public Frequency getFrequencyResolution()

Returns the width of a single sky frequency channel.

Note that the returned width is the one held by this specification, so any changes made to it will be reflected in this object. This value is guaranteed to be non-null.

Returns:

the width of a single sky frequency channel.

getNumberOfSpectralChannels

public long getNumberOfSpectralChannels()

Returns the number of whole spectral channels in this specification. The number of channels is the bandwidth divided by frequency resolution. The amount returned is the integer portion of this division. That is, the floating point result is "floored" down to the greatest integer that is less than or equal to the floating point result.

Returns:

the number of whole spectral channels in this specification.

setTimeResolution

public void setTimeResolution(TimeDuration resolution)

Sets the time resolution of this specification.

Unless resolution is null, this object will hold a reference to the parameter, so any changes made to it will be reflected in this object. A value of null will be interpreted as a duration of zero milliseconds.

Parameters:

resolution - the time resolution of this specification.

getTimeResolution

public TimeDuration getTimeResolution()

Returns the time resolution of this specification.

Note that the returned duration is the one held by this specification, so any changes made to it will be reflected in this object. This value is guaranteed to be non-null.

Returns:

the time resolution of this specification.

setPolarizationProducts

public void setPolarizationProducts(SortedSet<StokesParameter> newSet)

Sets the polarization products requested by this specification.

Unless newSet is null, this object will hold a reference to the parameter, so any changes made to it will be reflected in this object. A value of null will be interpreted as a new empty set.

Parameters:

newSet - the polarizations requested by this specification. If this value is null, it will be interpreted as an empty set.

getPolarizationProducts

public SortedSet<StokesParameter> getPolarizationProducts()

Returns the polarization products requested by this specification.

Note that the returned set is the one held by this specification, so any changes made to it will be reflected in this object. This set is guaranteed to be non-null, but it may be empty.

Returns:

the polarizations product requested by this specification.

setAdditionalSpecifications

public void setAdditionalSpecifications(SortedMap<String,String> newMap)

Sets a map of key/value pairs that hold additional specifications.

Unless newMap is null, this object will hold a reference to the parameter, so any changes made to it will be reflected in this object. A value of null will be interpreted as a new empty map.

See getAdditionalSpecifications() for more information.

Parameters:

newMap - a map of key/value pairs that hold additional specifications.

getAdditionalSpecifications

public SortedMap<String,String> getAdditionalSpecifications()

Returns any additional specifications for this specification.

"Additional specifications" are key/value pairs that are typically targeted at particular pieces of hardware. For example, the WIDAR correlator has a concept called "recirculation", so it could define the keyword recirculationFactor that could be given a value here and passed on to the WIDAR correlator. If, however, this specification is passed to different hardware, then the fact that this specification is carrying a recirculationFactor value will be irrelevant (unless we have namespace collissions -- may want to prefix all keywords with hardware name).

Note that the returned map is the one held by this specification, so any changes made to it will be reflected in this object. This set is guaranteed to be non-null, but it may be empty.

Returns:

any additional specifications for this specification.

toString

public String toString()

Returns a text representation of this specification.

Overrides:

toString in class Object

Returns:

a text representation of this specification.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this specification.

Returns:

an XML representation of this specification.

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 specification 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 SkyFrequencySpecification fromXml(String xmlFile)
                                         throws JAXBException,
                                                XMLStreamException,
                                                FileNotFoundException

Creates a new specification 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 specification 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 SkyFrequencySpecification fromXml(Reader reader)
                                         throws JAXBException,
                                                XMLStreamException

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

Parameters:

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

Returns:

a new specification 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 SkyFrequencySpecification clone()

Returns a specification that is a copy of this one.

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 specification.

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this specification.

Overrides:

hashCode in class Object