edu.nrao.sss.model.resource
Class CorrelatorConfiguration

java.lang.Object
  extended by edu.nrao.sss.model.resource.CorrelatorConfiguration
All Implemented Interfaces:
TelescopeBackend, Identifiable, ActionListener, Cloneable, EventListener
Direct Known Subclasses:
EvlaWidarConfiguration, VlaConfiguration

public abstract class CorrelatorConfiguration
extends Object
implements TelescopeBackend, ActionListener

Configuration information for a correlator of a radio telescope.

How To Use This Class

Getting an Instance
Clients are discouraged from creating new instances of this type by using the constructors of concrete subclasses. The preferred way to get an instance of this type is to use the static factory method, makeFor(CorrelatorName, AntennaElectronics). The static method getSupportedCorrelators() lists the correlator supported by this configuration class.

Working with Basebands and Baseband Pairs
This configuration now has only one method for fetching basebands: getBasebands(). The method getBasebandPairs() has been eliminated, but the CorrelatorBaseband now has methods to determine whether or not it is part of pair and, if so, who its parter is. The basebands held by this configuration were originally constructed based on the output signals of the AntennaElectronics provided to the factory method.

Listening for Changes
This configuration gives clients the ability to listen for changes in the collection of basebands in this configuration. Clients may register by using the addBasebandCollectionListener method. Registered users will be notified when a baseband(s) is added to the configuration, removed from the configuration, or both at once. Note that a listener's basebandCollectionChanged method is called only when the collection itself changes, not when properties of the contained basebands change.

Version Info:

$Revision: 2287 $
$Date: 2009-05-07 13:54:58 -0600 (Thu, 07 May 2009) $
$Author: dharland $ (last person to modify)

Since:
2008-02-04
Author:
David M. Harland

Field Summary
protected  List<CorrelatorBasebandAbs> activeBBs
          The basebands of this configuration.
protected  List<BasebandCollectionListener> bbListeners
          Objects interested in changes to our collection of basebands.
protected  Map<String,CorrelatorBasebandAbs> inactiveBBs
          Basebands that had been, but are not currently, active.
protected  AntennaElectronics signalSource
          The provider of digital signals for the basebands of this configuration.
 
Fields inherited from interface edu.nrao.sss.util.Identifiable
UNIDENTIFIED
 
Constructor Summary
protected CorrelatorConfiguration()
           
protected CorrelatorConfiguration(AntennaElectronics signalSrc)
          Constructs a new configuration that is initialized from signalSrc.
 
Method Summary
 void addBasebandCollectionListener(BasebandCollectionListener newListener)
          Registers a new listener that will be notified whenever the collection of basebands in this configuration is changed.
 void clearId()
          Resets this instance's ID, and the IDs of all its components, to a value that represents the unidentified state.
 CorrelatorConfiguration clone()
          Returns a copy of this configuration.
protected  void createdBasebandsFromPersistentStore()
          Called after basebands were created from a persistent store, such as a database or XMl file.
 boolean equals(Object o)
          Returns true if o is equal to this configuration.
 List<CorrelatorBaseband> getBasebands()
          Returns the basebands of this correlator configuration.
 Long getId()
           
protected  List<CorrelatorBaseband> getOrderedBasebands()
          Allows concrete subclasses to be in charge of the ordering of the basebands returned by getBasebands().
 AntennaElectronics getSignalSource()
          Returns the source of input signals for this configuration, if any.
static List<CorrelatorName> getSupportedCorrelators()
          Returns a list of the correlators that are supported by the factory method of this class.
 BackendType getType()
          Creates and initializes the active basebands for this configuration based on the antenna electronics that were sent to the constructor.
 int hashCode()
          Returns a hash code value for this configuration.
protected abstract  CorrelatorBaseband makeBasebandFrom(DigitalSignal ds)
          Creates a new baseband from the given digital signal.
protected abstract  CorrelatorBaseband makeBasebandFrom(DigitalSignal ds1, DigitalSignal ds2)
          Creates a new baseband from the given digital signals.
static CorrelatorConfiguration makeFor(CorrelatorName correlator, AntennaElectronics signalSrc)
          Creates and returns a new configuration for the given correlator that is initialized from signalSrc.
 void removeBasebandCollectionListener(BasebandCollectionListener formerListener)
          Removes formerListener from this configuration's list of baseband collection listeners.
 void setId(Long id)
          Sets the ID of this object; not recommended for most clients.
 void setSignalSource(AntennaElectronics newSource)
          Sets the source of input signals for this configuration.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface edu.nrao.sss.model.resource.TelescopeBackend
configureFrom, getName
 
Methods inherited from interface java.awt.event.ActionListener
actionPerformed
 

Field Detail

activeBBs

protected List<CorrelatorBasebandAbs> activeBBs
The basebands of this configuration.


inactiveBBs

protected Map<String,CorrelatorBasebandAbs> inactiveBBs
Basebands that had been, but are not currently, active. Subclasses do not have to work with this variable. The intention behind it is to help with a single-level "redo" feature. The targeted use case goes something like this:
  1. A user has set up the antenna electronics that feeds this configuration in such a way that eight basebands are produced.
  2. The user completely configures all basebands, including breaking them down into subbands.
  3. The user then either intentionally or accidentally modifies the antenna electronics in such a way that two of the fully configured basebands are replaced by two new basebands.
  4. The user puts the antenna electronics back into its original state. This means that the original eight basebands are again active.
This variable can be used to restore all the work the user had done on the disappearing basebands when they reappear.


signalSource

protected AntennaElectronics signalSource
The provider of digital signals for the basebands of this configuration.


bbListeners

protected List<BasebandCollectionListener> bbListeners
Objects interested in changes to our collection of basebands.

Constructor Detail

CorrelatorConfiguration

protected CorrelatorConfiguration(AntennaElectronics signalSrc)
Constructs a new configuration that is initialized from signalSrc.

Parameters:
signalSrc - the antenna electronics that provide the input signals for the basebands of this configuration.
Throws:
IllegalArgumentException - if signalSrc is null.

CorrelatorConfiguration

protected CorrelatorConfiguration()
Method Detail

makeFor

public static CorrelatorConfiguration makeFor(CorrelatorName correlator,
                                              AntennaElectronics signalSrc)
Creates and returns a new configuration for the given correlator that is initialized from signalSrc.

Parameters:
correlator - the name of a known correlator.
signalSrc - the antenna electronics that provide the input signals for the basebands of this configuration.
Returns:
a new configuration for the given correlator whose basebands are initialized based on the given antenna electronics.
Throws:
IllegalArgumentException - if correlator is not one of the supported types.

getSupportedCorrelators

public static List<CorrelatorName> getSupportedCorrelators()
Returns a list of the correlators that are supported by the factory method of this class.

Returns:
the correlators for which this class can construct configurations.

getId

public Long getId()
Specified by:
getId in interface Identifiable

setId

public void setId(Long id)
Description copied from interface: TelescopeBackend
Sets the ID of this object; not recommended for most clients. This method is here primarily for the use of persistence mechanisms.

Specified by:
setId in interface TelescopeBackend
Parameters:
id - a new ID for this object.

clearId

public void clearId()
Description copied from interface: TelescopeBackend
Resets this instance's ID, and the IDs of all its components, to a value that represents the unidentified state.

This method is useful for preparing an instance 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 instance for the first time, you may need to call this method before performing a save. This is especially true if you have created this instance from XML, as the XML unmarshalling brings along the ID property.

Specified by:
clearId in interface TelescopeBackend

setSignalSource

public void setSignalSource(AntennaElectronics newSource)
Sets the source of input signals for this configuration. Most clients will not need to use this method, since it is expected that they created this configuration with a valid signal source in the first place.

Specified by:
setSignalSource in interface TelescopeBackend
Parameters:
newSource - a new source of input signals for this configuration. A value of null is accepted here.

getSignalSource

public AntennaElectronics getSignalSource()
Returns the source of input signals for this configuration, if any. If no signal source has been provided, the returned value will be null.

Specified by:
getSignalSource in interface TelescopeBackend
Returns:
the source of input signals for this configuration.

getOrderedBasebands

protected List<CorrelatorBaseband> getOrderedBasebands()
Allows concrete subclasses to be in charge of the ordering of the basebands returned by getBasebands(). This default implementation returns a copy of the activeBBs list without any reordering


getType

public BackendType getType()
Creates and initializes the active basebands for this configuration based on the antenna electronics that were sent to the constructor. This method is called from the constructor after the signalSource variable was set. protected void initializeBasebands() { activeBBs.clear(); inactiveBBs.clear(); //Create new basebands from the input signals and save as active BBs for (List inputPair : signalSource.getSignalPairs()) { CorrelatorBaseband bb0 = makeBasebandFrom(inputPair.get(0)); CorrelatorBaseband bb1 = makeBasebandFrom(inputPair.get(1)); if (bb0 != null) activeBBs.put(bb0.getName(), bb0); if (bb1 != null) activeBBs.put(bb1.getName(), bb0); } }

Specified by:
getType in interface TelescopeBackend
Returns:
the general type of this backend.

makeBasebandFrom

protected abstract CorrelatorBaseband makeBasebandFrom(DigitalSignal ds)
Creates a new baseband from the given digital signal. Subclasses of this one decide which implementation of a CorrelatorBaseband to construct.

This method is expected to produce a CorrelatorBaseband whose CorrelatorBaseband.isSinglet() property is true.

Parameters:
ds - the digital signal that serves as the signal source for the newly created baseband.
Returns:
a new baseband, or null if ds is null.

makeBasebandFrom

protected abstract CorrelatorBaseband makeBasebandFrom(DigitalSignal ds1,
                                                       DigitalSignal ds2)
Creates a new baseband from the given digital signals. Subclasses of this one decide which implementation of a CorrelatorBaseband to construct.

This method is expected to produce a CorrelatorBaseband whose CorrelatorBaseband.isPair() property is true.

Parameters:
ds1 - one of two digital signals that serve as the signal sources for the newly created baseband.
ds2 - one of two digital signals that serve as the signal sources for the newly created baseband.
Returns:
a new baseband, or null if either ds1 or ds2 is null.

getBasebands

public List<CorrelatorBaseband> getBasebands()
Returns the basebands of this correlator configuration.

While the basebands in the returned list are the actual basebands held internally by this configuration, the list itself is a new list created at the time this method is called and not referenced by this configuration. The returned list may be empty, but will never be null.

Returns:
the basebands of this correlator configuration.

createdBasebandsFromPersistentStore

protected void createdBasebandsFromPersistentStore()
Called after basebands were created from a persistent store, such as a database or XMl file. This method is here so that subclasses may override it. This default implementation does nothing.


addBasebandCollectionListener

public void addBasebandCollectionListener(BasebandCollectionListener newListener)
Registers a new listener that will be notified whenever the collection of basebands in this configuration is changed. Note that "changed" means that there are new basebands in the collection, that some basebands formerly in the collection no longer are, or both of the preceding. For the purpose of the BasebandCollectionListener, a change to a baseband already in the collection is not considered an event. Only a modification of the collection itself causes notification.

Parameters:
newListener - an object that will be notified when the collection of basebands held by this configuration changes. A value of null will be ignored.

removeBasebandCollectionListener

public void removeBasebandCollectionListener(BasebandCollectionListener formerListener)
Removes formerListener from this configuration's list of baseband collection listeners. If formerListener is not currently a registered baseband collection listener, this method does nothing.

Parameters:
formerListener - an object that no longer wishes to be notified about changes in the collection of basebands held by this configuration.

clone

public CorrelatorConfiguration clone()
Returns a copy of this configuration. The returned object is a deep copy of this one, with the following exceptions:
  1. Both configurations are using the same signal source.
  2. While each configuration has its own list of listeners, the same listeners are present in each list.

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

Specified by:
clone in interface TelescopeBackend
Overrides:
clone in class Object
Returns:
a copy of this backend.

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


Copyright © 2009. All Rights Reserved.