edu.nrao.sss.model.resource
Class AntennaElectronicsConfiguration

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

All Implemented Interfaces:

Cloneable

public class AntennaElectronicsConfiguration
extends Object
implements Cloneable

A generalized representation of the configuration of antenna electronics. Configuring the electronics system of an antenna usually means setting switch positions, tuning local oscillators, and setting the number of bits per sample for the output signals.

This class is meant to be able to represent the configuration information for a wide variety of antenna types. Instances of this class may be obtained from the AntennaElectronics class, which can return its current configuration in this form. Clients that will merely query a configuration need have no special knowledge of the specific electronics with which they are dealing. Clients that need to alter a configuration, however, will likely need to know something about the targeted electronics and about the conventions suggested by this class.

Suggested Conventions for Users of this Class

In order to remain a fairly generic piece of code, this class makes heavy use of maps of name-value pairs. The name is always a string and is meant to be the name of a device, such as a local oscillator or switch. Concrete implementations of AntennaElectronics are expected to name all those LOs and switches that can be configured by an external user via this class. The value portion of a name-value pair varies depending on the device involved. Each device type will be covered below. First, though, we suggest a convention for embedded devices.

Convention for Naming Devices Held in Other Devices
Sometimes a device such as a switch is held in an internal component of the overall antenna electronics. An internal component might be an up-converter, a down-converter, or some other device. In order to distinguish devices held directly by AntennaElectronics from those it holds indirectly via its internal components, we suggest using dot notation. For example, if the electronics wishes to expose a switch named output in its internal component named downConverterX, the name it should use when populating this class is downConverterX.output.

Value Objects for Local Oscillator Settings
The getLoTunings() method returns a map whose keys are the names of local oscillators. The values in the maps are the tuning frequencies for those local oscillators.

Value Objects for Switch Settings
The getSwitchPositions() method returns a map whose keys are the names of switches. The values are themselves maps that give the active input and active output poles for the switch. The value map will either be empty, have one entry, or have two entries. It will never be null. The two valid keys for the value map are input and output, and the values of these keys represent the selection of a given input or output pole as the active input or output pole of that switch.

Value Objects for Transfer Switch Settings
The getTransferSwitchPositions() method returns a map whose keys are the names of transfer switches. The values in the maps are also strings and the convention is to use one of these two values: clockwise or counterclockwise. Also by convention, these values are not case sensitive.

Value Objects for Bits per Digital Samples
The getBitsPerSample() method returns a map whose keys are the names of digital samplers. The values in the maps are the number of bits per sample.

Version Info:

$Revision: 1709 $

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

$Author: dharland $ (last person to modify)

Since:

2008-01-09

Author:

David M. Harland

Constructor Summary

AntennaElectronicsConfiguration(TelescopeType telescope)
Creates a new empty configuration for the given telescope.

Method Summary

AntennaElectronicsConfiguration	clone() Returns a copy of this configuration.
boolean	equals(Object o) Returns true if o is equal to this configuration.
static AntennaElectronicsConfiguration	fromXml(Reader reader) Creates a new configuration based on the XML data read from reader.
static AntennaElectronicsConfiguration	fromXml(String xmlFile) Creates a new configuration from the XML data in the given file.
Set<ReceiverBand>	getBands() Returns the receiver bands for this configuration.
SortedMap<String,Integer>	getBitsPerSample() Returns a map of digital sampler settings.
SortedMap<String,Frequency>	getLoTunings() Returns a map of local oscillator tunings.
SortedMap<String,Map<String,String>>	getSwitchPositions() Returns a map of switch positions.
TelescopeType	getTelescope() Returns the telescope for which this configuration is intended.
SortedMap<String,String>	getTransferSwitchPositions() Returns a map of transfer switch positions.
int	hashCode() Returns a hash code value for this configuration.
String	toXml() Returns an XML representation of this configuration.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this configuration to writer.

Methods inherited from class java.lang.Object

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

Constructor Detail

AntennaElectronicsConfiguration

public AntennaElectronicsConfiguration(TelescopeType telescope)

Creates a new empty configuration for the given telescope.

Method Detail

getTelescope

public TelescopeType getTelescope()

Returns the telescope for which this configuration is intended.

Returns:

the telescope for which this configuration is intended.

getBands

public Set<ReceiverBand> getBands()

Returns the receiver bands for this configuration.

The returned set is the one held internally by this configuration, so changes made to it will have an effect on this object. The returned set is guaranteed to be non-null, but it may be empty. The most common situation is for there to be one element in the returned set.

Returns:

the receiver bands for this configuration.

getLoTunings

public SortedMap<String,Frequency> getLoTunings()

Returns a map of local oscillator tunings. The keys are the names of local oscillators and the values are their tunings.

The returned map is the one held internally by this configuration, so changes made to it will have an effect on this object. The returned map is guaranteed to be non-null, but it may be empty.

Returns:

a map of local oscillator tunings.

getSwitchPositions

public SortedMap<String,Map<String,String>> getSwitchPositions()

Returns a map of switch positions. The keys are the names of switches and the values are themselves maps. The value map will either be empty, hold one entry, or hold two entries. It will never be null. The two valid keys for the value map are input and output, and the values of these keys represent the selection of a given input or output pole as the active input or output pole of that switch.

The returned map is the one held internally by this configuration, so changes made to it will have an effect on this object. The returned map is guaranteed to be non-null, but it may be empty.

Returns:

a map of switch positions.

getTransferSwitchPositions

public SortedMap<String,String> getTransferSwitchPositions()

Returns a map of transfer switch positions. The keys are the names of switches and the values are their settings. A setting may be either the string clockwise or the string counterclockwise. Implementations of AntennaElectronics are to treat these values as case insensitive.

The returned map is the one held internally by this configuration, so changes made to it will have an effect on this object. The returned map is guaranteed to be non-null, but it may be empty.

Returns:

a map of transfer switch positions.

getBitsPerSample

public SortedMap<String,Integer> getBitsPerSample()

Returns a map of digital sampler settings. The keys are the names of digital samplers and the values are the number of bits per sample

The returned map is the one held internally by this configuration, so changes made to it will have an effect on this object. The returned map is guaranteed to be non-null, but it may be empty.

Returns:

a map of digital sampler settings

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this configuration.

Returns:

an XML representation of this configuration.

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

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

Creates a new configuration 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 configuration 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 AntennaElectronicsConfiguration clone()

Returns a copy of this configuration.

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

Overrides:

equals in class Object

hashCode

public int hashCode()

Returns a hash code value for this configuration.

Overrides:

hashCode in class Object