edu.nrao.sss.model.project.scan
Class Scan

java.lang.Object
  edu.nrao.sss.model.project.scan.ScanLoopElement
      edu.nrao.sss.model.project.scan.Scan

All Implemented Interfaces:

UserAccountable, Identifiable, Cloneable

Direct Known Subclasses:

DelayScan, FocusScan, PointingScan, SimpleScan, SwitchingScan, TippingScan

public abstract class Scan
extends ScanLoopElement

A sequence of one or more observations that share a single goal. A scan is made up of a target source, a calibrator, resources, timing information, and an observing mode.

A Scan is usually an observation of a single target source or calibrator, but may involve different pointing and focus patterns.

Version Info:

$Revision: 2277 $

$Date: 2009-04-29 11:19:38 -0600 (Wed, 29 Apr 2009) $

$Author: dharland $

Since:

2006-02-24

Author:

David M. Harland

Field Summary

static String

DEFAULT_NAME

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

UNIDENTIFIED

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

NULL_USER_ID

Method Summary

void	clearId() Resets this scan's id to UNIDENTIFIED, an similarly resets it's source catalog entry and resource id's.
Scan	clone() Returns a scan that is a copy of this one.
static Scan	createFor(ScanMode scanMode) A factory method for creating a new scan.
boolean	equals(Object o) Returns true if o is equal to this scan.
static <T extends Scan> T	fromXml(Class<T> scanType, Reader reader) Creates a new scan based on the XML data read from reader.
static <T extends Scan> T	fromXml(Class<T> scanType, String xmlFile) Creates a new scan from the XML data in the given file.
boolean	getAllowOverTheTop() Returns true if this scan allows the telescope to tip beyond the zenith.
AntennaWrap	getAntennaWrap() Returns the antenna wrapping direction for this scan.
boolean	getApplyLastPhase() Returns true if this scan should apply the most recent set of phase offsets.
boolean	getApplyLastReferenceDelay() Returns true if this scan should apply the most recent set of reference delays.
boolean	getApplyLastReferenceFocus() Returns true if this scan should apply the most recent set of reference focus offsets.
boolean	getApplyLastReferencePointing() Returns true if this scan should apply the most recent set of reference pointing offsets.
Map<String,ScanDopplerSpecs>	getDopplerSpecs() Returns a copy of this scan's map of Doppler tracking information.
ScanDopplerSpecs	getDopplerSpecs(String key) Returns the Doppler tracking information associated with key, if any.
DopplerTracker	getDopplerTracker(String key, Date dateTime, Frequency restFrequency) Returns a new Doppler tracker based on the given parameters and the properties of this scan.
Set<ScanIntent>	getIntents() Returns a set of the purposes for which this scan is intended.
String	getLongName() Deprecated.
ScanMode	getMode() Returns the mode of this scan.
AntennaSelection	getReferenceAntennas() Returns a set of antennas to be used as references for this scan.
Resource	getResource() Returns the resource to use for this scan, or null if one cannot be found.
String	getShortName() Deprecated.
boolean	getSolarObserving() Returns true if this scan is for solar observing.
Source	getSource() Returns the source to use at the current time.
Source	getSource(Date dateTime) Returns the source to use at the given time.
SourceCatalogEntry	getSourceCatalogEntry() Returns either the Source or SourceLookupTable that is the focus of this scan.
AntennaSelection	getSubarray() Returns the antennas selected for a subarray.
ScanTimeSpecification	getTimeSpec() Returns the timing specification for this scan.
boolean	getUseResourceOfPriorScan() Indicates whether this scan should use its own hardware configuration or that of the prior scan.
int	hashCode() Returns a hash code value for this scan loop element.
void	removeDopplerSpecs(String key) Removes the Doppler tracking information stored previously with the given key.
void	reset() Resets this scan to its initial state.
void	setAllowOverTheTop(boolean allow) Indicates whether or not this scan will allow the telescope to tip beyond the zenith.
void	setAntennaWrap(AntennaWrap wrap) Sets the antenna wrapping direction for this scan.
void	setApplyLastPhase(boolean apply) Tells this scan whether or not it should apply the most recent set of phase offsets.
void	setApplyLastReferenceDelay(boolean apply) Tells this scan whether or not is should apply the most recent set of reference delays.
void	setApplyLastReferenceFocus(boolean apply) Tells this scan whether or not is should apply the most recent set of reference focus offsets.
void	setApplyLastReferencePointing(boolean apply) Tells this scan whether or not is should apply the most recent set of reference pointing offsets.
void	setDopplerSpecs(String key, ScanDopplerSpecs dopplerInfo) Saves Doppler tracking specifications using the given key.
void	setIntents(Set<ScanIntent> replacementSet) Sets the purposes for which this scan is intended.
void	setLongName(String newName) Deprecated.
void	setResource(Resource newResource) Sets the resource to be used for this scan.
void	setShortName(String newName) Deprecated.
void	setSolarObserving(boolean solar) Indicates whether or not this scan is for solar observing.
void	setSourceCatalogEntry(SourceCatalogEntry sourceOrTable) Sets either the Source or SourceLookupTable that is the focus of this scan.
void	setUseResourceOfPriorScan(boolean usePriorResource) Indicates whether this scan should use its own hardware configuration or that of the prior scan.
String	toSummaryString() Returns a short textual description of this scan loop element.

Methods inherited from class edu.nrao.sss.model.project.scan.ScanLoopElement

appendComments, getComments, getCreatedBy, getCreatedOn, getId, getLastUpdatedBy, getLastUpdatedOn, getName, getProgramBlock, getProject, getSchedulingBlock, hasSchedulingBlock, setComments, setCreatedBy, setCreatedOn, setId, setLastUpdatedBy, setLastUpdatedOn, setName, setSchedulingBlock, toString, toXml, writeAsXmlTo

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_NAME

public static final String DEFAULT_NAME

See Also:

Constant Field Values

Method Detail

createFor

public static Scan createFor(ScanMode scanMode)

A factory method for creating a new scan. The returned scan will be of a variety that is appropriate for the given observation mode.

Parameters:

scanMode - the observation mode for which a scan is desired.

Returns:

a new scan instance.

Throws:

IllegalArgumentException - if scanMode is null.

reset

public void reset()

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

Overrides:

reset in class ScanLoopElement

clearId

public void clearId()

Resets this scan's id to UNIDENTIFIED, an similarly resets it's source catalog entry and resource id's.

Overrides:

clearId in class ScanLoopElement

getLongName

@Deprecated
public String getLongName()

Deprecated.

setLongName

@Deprecated
public void setLongName(String newName)

Deprecated.

getShortName

@Deprecated
public String getShortName()

Deprecated.

setShortName

@Deprecated
public void setShortName(String newName)

Deprecated.

getMode

public ScanMode getMode()

Returns the mode of this scan.

Returns:

the mode of this scan.

getTimeSpec

public ScanTimeSpecification getTimeSpec()

Returns the timing specification for this scan. The returned object will never be null and is the actual instance held by this scan, so changes made to it will be reflected herein.

Returns:

the timing specification for this scan.

getSource

public Source getSource()

Returns the source to use at the current time. If this scan has no such source, null is returned.

Returns:

the source to use at the current time, or null if there is no such source.

getSource

public Source getSource(Date dateTime)

Returns the source to use at the given time. If this scan has no such source, null is returned.

Parameters:

dateTime - the time for which the source is needed.

Returns:

the source to use at the given time, or null if there is no such source.

setSourceCatalogEntry

public void setSourceCatalogEntry(SourceCatalogEntry sourceOrTable)

Sets either the Source or SourceLookupTable that is the focus of this scan.

Parameters:

sourceOrTable - the Source or SourceLookupTable to use for this scan.

getSourceCatalogEntry

public SourceCatalogEntry getSourceCatalogEntry()

Returns either the Source or SourceLookupTable that is the focus of this scan. The returned value may be null.

Returns:

the Source or SourceLookupTable used for this scan, or null if this scan has neither.

setUseResourceOfPriorScan

public void setUseResourceOfPriorScan(boolean usePriorResource)

Indicates whether this scan should use its own hardware configuration or that of the prior scan.

Calling this method has no impact on the value of the resource property.

Parameters:

usePriorResource - true if this scan should the hardware configuration of the prior scan, false if it should use its own configuration.

See Also:

setResource(Resource)

getUseResourceOfPriorScan

public boolean getUseResourceOfPriorScan()

Indicates whether this scan should use its own hardware configuration or that of the prior scan.

Returns:

true if this scan should the hardware configuration of the prior scan, false if it should use its own configuration.

See Also:

getResource()

setResource

public void setResource(Resource newResource)

Sets the resource to be used for this scan. This method will accept a value of null.

The newResource should be used only if the value returned by getUseResourceOfPriorScan() is true.

Calling this method has no impact on the value of the use-resource-of-prior-scan property.

Parameters:

newResource - the resource to be used for this scan.

See Also:

setUseResourceOfPriorScan(boolean)

getResource

public Resource getResource()

Returns the resource to use for this scan, or null if one cannot be found. Most clients will first want to call getUseResourceOfPriorScan() and then call this method only if the value returned by that method is true.

Note that this method may return a non-null resource even when getUseResourceOfPriorScan returns false.

Returns:

the resource to use for this scan, or null if one cannot be found.

getSubarray

public AntennaSelection getSubarray()

Returns the antennas selected for a subarray.

Returns:

the antennas selected for a subarray.

getReferenceAntennas

public AntennaSelection getReferenceAntennas()

Returns a set of antennas to be used as references for this scan.

Returns:

a set of antennas to be used as references for this scan.

setDopplerSpecs

public void setDopplerSpecs(String key,
                            ScanDopplerSpecs dopplerInfo)

Saves Doppler tracking specifications using the given key.

Parameters:

key - the key for retrieving dopplerInfo from this scan. See the description of the key parameter to the getDopplerTracker(String, Date, Frequency) method for important information.

dopplerInfo - information regarding doppler tracking for this scan.

Since:

2009-09-10

removeDopplerSpecs

public void removeDopplerSpecs(String key)

Removes the Doppler tracking information stored previously with the given key.

Parameters:

key - a key used previously in setDopplerSpecs(String, ScanDopplerSpecs) for storing Doppler tracking information. See the description of the key parameter to the getDopplerTracker(String, Date, Frequency) method for important information.

Since:

2009-09-10

getDopplerSpecs

public ScanDopplerSpecs getDopplerSpecs(String key)

Returns the Doppler tracking information associated with key, if any.

Parameters:

key - a key used previously in setDopplerSpecs(String, ScanDopplerSpecs) for storing Doppler tracking information. See the description of the key parameter to the getDopplerTracker(String, Date, Frequency) method for important information.

Returns:

the Doppler tracking information associated with key, if any. If no Doppler information exists for key, null is returned.

Since:

2008-09-22

getDopplerSpecs

public Map<String,ScanDopplerSpecs> getDopplerSpecs()

Returns a copy of this scan's map of Doppler tracking information.

The returned map is not reference by this scan, so changes made to it will not be reflected herein. The returned map might be empty but will never be null.

Returns:

a copy of this scan's map of Doppler tracking information.

Since:

2008-09-22

getDopplerTracker

public DopplerTracker getDopplerTracker(String key,
                                        Date dateTime,
                                        Frequency restFrequency)

Returns a new Doppler tracker based on the given parameters and the properties of this scan.

This method first looks for a ScanDopplerSpecs object associated with key. If one is found, it is queried for source position and velocity information. If the found specification is missing position or velocity information, that information is sought from this scan's source. If no Doppler specs are found for key, this method will again use this scan's source for the needed information. The EarthPosition used in the returned DopplerTracker comes from the telescope used by this scan's Resource. If this scan's resource is null, the DopplerTracker will use a default position.

It is important to note that this method makes no determination about whether or not Doppler tracking should be used; that decision is up to the client. This method will never return a null tracker.

Parameters:

key - a key used previously for storing Doppler specifications. At this point the key can be any arbitrary text chosen by clients. We would like in the future, though, to use the name of a signal as the key. By "signal" we mean one of the outputs from the antenna electronics of this scan's resource. If we were to adopt this convention, we could eliminate the restFrequency parameter (see below). The hardware configuration code is not yet ready for this, so clients currently have the inconvenience of furnishing a rest frequency.

dateTime - used to fetch the source from this scan. If this parameter is null the current system time is used.

restFrequency - an optional parameter that is used only if this method needs to fetch velocity information from this scan's source. If this scan has Doppler tracking information for signalName, and if that object has velocity information, this parameter will not be used.

Ideally this parameter should not be needed, and if we enhance the Resource class or one of its components, we should be able to eliminate it. If the key parameter is truly the name of a signal, this method should be able to talk to its resource, get the named signal, and fetch the central frequency from it.

Returns:

a new Doppler tracker based on properties of this scan.

Since:

2009-09-10

setIntents

public void setIntents(Set<ScanIntent> replacementSet)

Sets the purposes for which this scan is intended. If replacementSet is null, it will be intrepreted as a new, empty, set.

This scan will hold a reference to replacementSet (unless it is null), so any changes made to the set after calling this method will be reflected in this object.

Parameters:

replacementSet - a set of the purposes for which this scan is intended.

getIntents

public Set<ScanIntent> getIntents()

Returns a set of the purposes for which this scan is intended.

The returned set is the actual set held by this scan, so changes made to the set will be reflected in this object.

Returns:

a set of the purposes for which this scan is intended.

setApplyLastPhase

public void setApplyLastPhase(boolean apply)

Tells this scan whether or not it should apply the most recent set of phase offsets.

Parameters:

apply - true if this scan should apply the most recent set of phase offsets.

getApplyLastPhase

public boolean getApplyLastPhase()

Returns true if this scan should apply the most recent set of phase offsets.

Returns:

true if this scan should apply the most recent set of phase offsets.

setApplyLastReferencePointing

public void setApplyLastReferencePointing(boolean apply)

Tells this scan whether or not is should apply the most recent set of reference pointing offsets.

Parameters:

apply - true if this scan should apply the most recent set of reference pointing offsets.

getApplyLastReferencePointing

public boolean getApplyLastReferencePointing()

Returns true if this scan should apply the most recent set of reference pointing offsets.

Returns:

true if this scan should apply the most recent set of reference pointing offsets.

setApplyLastReferenceFocus

public void setApplyLastReferenceFocus(boolean apply)

Tells this scan whether or not is should apply the most recent set of reference focus offsets.

Parameters:

apply - true if this scan should apply the most recent set of reference focus offsets.

getApplyLastReferenceFocus

public boolean getApplyLastReferenceFocus()

Returns true if this scan should apply the most recent set of reference focus offsets.

Returns:

true if this scan should apply the most recent set of reference focus offsets.

setApplyLastReferenceDelay

public void setApplyLastReferenceDelay(boolean apply)

Tells this scan whether or not is should apply the most recent set of reference delays.

Parameters:

apply - true if this scan should apply the most recent set of reference delays.

getApplyLastReferenceDelay

public boolean getApplyLastReferenceDelay()

Returns true if this scan should apply the most recent set of reference delays.

Returns:

true if this scan should apply the most recent set of reference delays.

setSolarObserving

public void setSolarObserving(boolean solar)

Indicates whether or not this scan is for solar observing.

Parameters:

solar - true if this scan is for solar observing.

getSolarObserving

public boolean getSolarObserving()

Returns true if this scan is for solar observing.

Returns:

true if this scan is for solar observing.

setAllowOverTheTop

public void setAllowOverTheTop(boolean allow)

Indicates whether or not this scan will allow the telescope to tip beyond the zenith.

Parameters:

allow - true if this scan allows the telescope to tip beyond the zenith.

getAllowOverTheTop

public boolean getAllowOverTheTop()

Returns true if this scan allows the telescope to tip beyond the zenith.

Returns:

true if this scan allows the telescope to tip beyond the zenith.

setAntennaWrap

public void setAntennaWrap(AntennaWrap wrap)

Sets the antenna wrapping direction for this scan.

Parameters:

wrap - the antenna wrapping direction for this scan.

getAntennaWrap

public AntennaWrap getAntennaWrap()

Returns the antenna wrapping direction for this scan.

Returns:

the antenna wrapping direction for this scan.

toSummaryString

public String toSummaryString()

Description copied from class: ScanLoopElement

Returns a short textual description of this scan loop element.

Specified by:

toSummaryString in class ScanLoopElement

Returns:

a short textual description of this scan loop element.

fromXml

public static <T extends Scan> T fromXml(Class<T> scanType,
                                         String xmlFile)
                              throws JAXBException,
                                     XMLStreamException,
                                     FileNotFoundException

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

Sample usage:

   FocusScan myScan = Scan.fromXml(FocusScan.class, myFile);

Type Parameters:

T - the particular subclass of Scan returned.

Parameters:

scanType - the Class of an object that extends Scan.

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

Returns:

a new scan 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 <T extends Scan> T fromXml(Class<T> scanType,
                                         Reader reader)
                              throws JAXBException,
                                     XMLStreamException

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

Sample usage:

   DelayScan myScan = Scan.fromXml(DelayScan.class, myReader);

Type Parameters:

T - the particular subclass of Scan returned.

Parameters:

scanType - the Class of an object that extends Scan.

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

Returns:

a new scan 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 Scan clone()

Returns a scan that is a copy of this one.

The returned scan is, for the most part, a deep copy of this one. However, there are a few exceptions:

1. The ID will be set to Identifiable.UNIDENTIFIED.
2. The schedulingBlock will be null.
3. The createdOn and lastUpdatedOn attributes will be set to the current system time.

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

Overrides:

clone in class ScanLoopElement

equals

public boolean equals(Object o)

Returns true if o is equal to this scan.

In order to be equal to this element, o must be non-null and of the same class as this element. Equality is determined by examining the equality of corresponding attributes, with the following exceptions, which are ignored when assessing equality:

1. id
2. schedulingBlock
3. createdOn
4. createdBy
5. lastUpdatedOn
6. lastUpdatedBy

Overrides:

equals in class ScanLoopElement

hashCode

public int hashCode()

Description copied from class: ScanLoopElement

Returns a hash code value for this scan loop element.

Overrides:

hashCode in class ScanLoopElement