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

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

All Implemented Interfaces:

UserAccountable, Identifiable, Cloneable

public class ScanLoop
extends ScanLoopElement

A loop of scans and scan loops.

This class is used primarily by the SchedulingBlock. It allows an observer to create a scan sequence that allows multiple nesting of repeated loops of scans.

This loop consists of an iteration count and zero or more ScanLoopElements. Each element is executed once per iteration in the order in which they appear in this loop's list of elements. Note that some of the elements may themselves be loops, allowing the construction of arbritrarily deep nesting of loops.

Version Info:

$Revision: 2277 $

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

$Author: dharland $

Since:

2006-07-31

Author:

David M. Harland

Field Summary

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

UNIDENTIFIED

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

NULL_USER_ID

Constructor Summary

ScanLoop()
Creates a new loop with no elements and with an iteration count of one.

Method Summary

void	add(int index, Scan scan) Adds the given scan to this loop at the given position.
void	add(Scan scan) Adds the given scan to this loop.
ScanLoop	addCopyOf(int index, ScanLoop loop) Adds a copy of the given loop to this loop at the given position.
ScanLoop	addCopyOf(ScanLoop loop) Adds a copy of the given loop to this loop.
void	clearId() Resets this loop's id to UNIDENTIFIED and calls all of it's chilren's clearId() methods.
ScanLoop	clone() Returns a scan loop that is a deep copy of this one.
boolean	contains(ScanLoopElement element, EqualityMethod equalityMethod) Returns true if element is held either directly, or indirectly, by this loop.
boolean	containsDirectly(ScanLoopElement element, EqualityMethod equalityMethod) Returns true if element is held directly by this loop.
boolean	decrementIndexOf(ScanLoopElement element) Moves element to an index one lower than its current position in this loop.
boolean	decrementIndexOfElementAt(int index) Moves the element at index to an index of index-minus-one.
boolean	equals(Object o) Returns true if o is equal to this scan loop.
static ScanLoop	fromXml(Reader reader) Creates a new scan loop based on the XML data read from reader.
static ScanLoop	fromXml(String xmlFile) Creates a new scan loop from the XML data in the given file.
boolean	getBracketed() Returns whether or not this loop is a "bracketed" loop.
ScanLoopElement	getElement(int index) Returns the element at index.
List<ScanLoopElement>	getElements() Returns a list of the elements of this loop.
int	getIterationCount() Returns the number of times that this loop should be executed.
TimeDuration	getMaximumDuration() Returns the maximum amount of time that may be spent in this loop.
int	hashCode() Returns a hash code value for this scan loop element.
boolean	incrementIndexOf(ScanLoopElement element) Moves element to an index one higher than its current position in this loop.
boolean	incrementIndexOfElementAt(int index) Moves the element at index to an index of index-plus-one.
ScanLoopElement	remove(int index) Removes the element at index.
void	remove(ScanLoopElement element, EqualityMethod equalityMethod) Removes all occurrences the given element from this loop.
void	removeAll() Removes all elements from this loop.
ScanLoopElement	removeElement(int index) Deprecated.
void	removeRecursively(ScanLoopElement element, EqualityMethod equalityMethod) Removes element from this loop and all nested loops.
void	replaceEqualScansRecursivelyWith(Scan replacmentScan) Recursively replaces all scans in this loop that are equal to replacmentScan with replacmentScan.
void	replaceEqualScansWith(Scan replacmentScan) Replaces all scans in this loop that are equal to replacmentScan with replacmentScan.
void	reset() Resets this loop so that it has no elements and an iteration count of one.
void	setBracketed(boolean b) Sets whether or not this loop is a "bracketed" loop.
void	setIterationCount(int count) Sets the number of times that this loop should be executed.
void	setMaximumDuration(TimeDuration maxTime) Sets the maximum amount of time that may be spent in this loop.
void	setSchedulingBlock(SchedulingBlock newSchedBlock) Sets the scheduling block to which this scan loop belongs.
int	size() Returns the number of elements in this loop.
boolean	swapElements(int index1, int index2) Swaps the elements at the given positions.
void	testScansForResourceFromJaxb() Meant for use by containers of scan loops; most clients should not use this method.
List<Scan>	toScanList() Returns a list of scans that represents the expansion of this loop and all of its contained loops.
Set<Scan>	toScanSet() Returns the set of scans held by this loop and recursively down through all inner loops.
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, toString, toXml, writeAsXmlTo

Methods inherited from class java.lang.Object

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

Constructor Detail

ScanLoop

public ScanLoop()

Creates a new loop with no elements and with an iteration count of one.

Method Detail

reset

public void reset()

Resets this loop so that it has no elements and an iteration count of one.

Overrides:

reset in class ScanLoopElement

setIterationCount

public void setIterationCount(int count)

Sets the number of times that this loop should be executed.

Parameters:

count -

getIterationCount

public int getIterationCount()

Returns the number of times that this loop should be executed.

Returns:

the number of times that this loop should be executed.

setBracketed

public void setBracketed(boolean b)

Sets whether or not this loop is a "bracketed" loop. A bracketed loop will repeat it's first ScanLoopElement once more at the end such that the loop begins and ends with the same element when unrolled.

In other words, if a loop contains Scans A and B, with an interation count of 3, a regular loop will unroll to: A B A B A B whereas a bracketed loop would unroll to A B A B A B A.

Default is true.

getBracketed

public boolean getBracketed()

Returns whether or not this loop is a "bracketed" loop. A bracketed loop will repeat it's first ScanLoopElement once more at the end such that the loop begins and ends with the same element when unrolled.

In other words, if a loop contains Scans A and B, with an interation count of 3, a regular loop will unroll to: A B A B A B whereas a bracketed loop would unroll to A B A B A B A.

Default is true.

Returns:

whether or not this loop is a "bracketed" loop.

setMaximumDuration

public void setMaximumDuration(TimeDuration maxTime)

Sets the maximum amount of time that may be spent in this loop. If maxTime is null, the maximum duration will be set to an arbitrarily large number.

Parameters:

maxTime - the maximum amount of time that may be spent in this loop.

getMaximumDuration

public TimeDuration getMaximumDuration()

Returns the maximum amount of time that may be spent in this loop.

Returns:

the maximum amount of time that may be spent in this loop.

size

public int size()

Returns the number of elements in this loop. Note that each element is either a Scan or a ScanLoop.

Returns:

the number of elements in this loop.

setSchedulingBlock

public void setSchedulingBlock(SchedulingBlock newSchedBlock)

Sets the scheduling block to which this scan loop belongs.

This method does not communicate back to newSchedBlock about its new loop. This is because the scheduling block does not hold loops scans directly, other than its main loop. This means that the model is not enforcing integrity in the container / contained relationship that exists between SchedulingBlock and ScanLoop.

If this loop is currently the main loop of a scheduling block, this method will not allow a change of scheduling block.

Passing this method a schedulingBlock of null has the effect of disconnecting this loop from any scheduling block.

Overrides:

setSchedulingBlock in class ScanLoopElement

Parameters:

newSchedBlock - the scheduling block to which this scan belongs.

getElements

public List<ScanLoopElement> getElements()

Returns a list of the elements of this loop.

The returned list is not held internally by this loop. This means that any changes made to the list after the call will not be reflected in this object. The elements in the list, however, are the actual elements of this loop, so changes made to them will be reflected in this object.

Returns:

a list of the elements of this loop.

getElement

public ScanLoopElement getElement(int index)

Returns the element at index.

Parameters:

index - see List.get(int) for a discussion of this parameter.

Returns:

the element at index.

contains

public boolean contains(ScanLoopElement element,
                        EqualityMethod equalityMethod)

Returns true if element is held either directly, or indirectly, by this loop. If this loop has no element equal to element, but contains a nested loop that does contain element, this method will return true because it does contain element, albeit indirectly.

Containment is determined by the equalityMethod provided. If this parameter is null, EqualityMethod.VALUE will be used.

Parameters:

element - the element to test for containment.

equalityMethod - determines whether containment is based on reference or value equality. A value of null will be interpreted as a signal to use value equality.

Returns:

true if element is held directly or indirectly by this loop.

See Also:

containsDirectly(ScanLoopElement, EqualityMethod)

containsDirectly

public boolean containsDirectly(ScanLoopElement element,
                                EqualityMethod equalityMethod)

Returns true if element is held directly by this loop. If this loop has no element equal to element, but contains a nested loop that does contain element, this method still returns false because it does not directly hold element.

Containment is determined by the equalityMethod provided. If this parameter is null, EqualityMethod.VALUE will be used.

Parameters:

element - the element to test for containment.

equalityMethod - determines whether containment is based on reference or value equality. A value of null will be interpreted as a signal to use value equality.

Returns:

true if element is held directly by this loop.

See Also:

contains(ScanLoopElement, EqualityMethod)

add

public void add(Scan scan)

Adds the given scan to this loop.

Parameters:

scan - the scan to be added to this loop.

Throws:

IllegalArgumentException - if scan is null.

add

public void add(int index,
                Scan scan)

Adds the given scan to this loop at the given position.

Parameters:

index - the position at which to add the new scan. See the add(int, E) method of List for a discussion of the insertion.

scan - the scan to be added to this loop.

Throws:

IllegalArgumentException - if scan is null.

addCopyOf

public ScanLoop addCopyOf(ScanLoop loop)

Adds a copy of the given loop to this loop.

Parameters:

loop - the loop to be added to this loop.

Returns:

the copy of the loop that was added to this loop.

Throws:

IllegalArgumentException - if loop is null or is this loop.

See Also:

addCopyOf(int, ScanLoop)

addCopyOf

public ScanLoop addCopyOf(int index,
                          ScanLoop loop)

Adds a copy of the given loop to this loop at the given position.

The reason for adding a copy, instead of loop itself, is to ensure that the model could never be put into a state where loops swallow their own tails. That is, we seek to prevent a situation where loop A holds loop B which holds loop A which holds...

Parameters:

loop - the loop to be added to this loop.

index - the position at which to add the new loop. See the add(int, E) method of List for a discussion of the insertion.

Returns:

the copy of the loop that was added to this loop.

Throws:

IllegalArgumentException - if loop is null or is this loop.

incrementIndexOf

public boolean incrementIndexOf(ScanLoopElement element)

Moves element to an index one higher than its current position in this loop. The element will not be moved if it is not in this loop, or if it is already in the highest position.

If element is in this loop in multiple positions, the instance with the lowest index will be moved.

Parameters:

element - the element to be moved.

Returns:

true if the element was successfully moved.

decrementIndexOf

public boolean decrementIndexOf(ScanLoopElement element)

Moves element to an index one lower than its current position in this loop. The element will not be moved if it is not in this loop, or if it is already in the lowest position.

If element is in this loop in multiple positions, the instance with the highest index will be moved.

Parameters:

element - the element to be moved.

Returns:

true if the element was successfully moved.

incrementIndexOfElementAt

public boolean incrementIndexOfElementAt(int index)

Moves the element at index to an index of index-plus-one. No move will occur if index is out of bounds, or if it is already the highest index of this loop.

Parameters:

index - the index of the element to be moved.

Returns:

true if the element was successfully moved.

decrementIndexOfElementAt

public boolean decrementIndexOfElementAt(int index)

Moves the element at index to an index of index-minus-one. No move will occur if index is out of bounds, or if it is already the lowest index of this loop.

Parameters:

index - the index of the element to be moved.

Returns:

true if the element was successfully moved.

swapElements

public boolean swapElements(int index1,
                            int index2)

Swaps the elements at the given positions.

If the indices are equal, no action is taken. If one or both of the indices are not in the range [0,size()), the underlying List will throw an exception.

Parameters:

index1 - the position of the one of the elements.

index2 - the position of another of the elements.

Returns:

true if the positions were swapped.

replaceEqualScansWith

public void replaceEqualScansWith(Scan replacmentScan)

Replaces all scans in this loop that are equal to replacmentScan with replacmentScan. This is when you want the loop to hold multiple references to the exact same scan.

Note that this method operates only on scans held directly by this loop, not on those of inner loops contained within this one. To replace all scans in this loop and all contained loops, use replaceEqualScansRecursivelyWith(Scan).

Parameters:

replacmentScan - a scan used to replace all scans in this loop that are equal to it.

replaceEqualScansRecursivelyWith

public void replaceEqualScansRecursivelyWith(Scan replacmentScan)

Recursively replaces all scans in this loop that are equal to replacmentScan with replacmentScan.

Parameters:

replacmentScan - a scan used to replace all scans in this loop that are equal to it.

See Also:

replaceEqualScansWith(Scan)

removeElement

@Deprecated
public ScanLoopElement removeElement(int index)

Deprecated.

remove

public ScanLoopElement remove(int index)

Removes the element at index. If the removed element is no longer contained anywhere in its scheduling block, its scheduling block is set to null.

Parameters:

index - see List.remove(int) for a discussion of this parameter.

Returns:

the element previously at the specified position.

removeRecursively

public void removeRecursively(ScanLoopElement element,
                              EqualityMethod equalityMethod)

Removes element from this loop and all nested loops.

In order for element to be removed from this loop, it must be contained by this loop. Containment is determined by the equalityMethod provided. If this parameter is null, EqualityMethod.VALUE will be used.

To remove element from this loop while leaving nested loops untouched, call remove(ScanLoopElement, EqualityMethod).

Parameters:

element - the element to be removed from this loop and all nested loops.

equalityMethod - determines whether containment is based on reference or value equality. A value of null will be interpreted as a signal to use value equality.

remove

public void remove(ScanLoopElement element,
                   EqualityMethod equalityMethod)

Removes all occurrences the given element from this loop.

In order for element to be removed from this loop, it must be contained by this loop. Containment is determined by the equalityMethod provided. If this parameter is null, EqualityMethod.VALUE will be used.

Parameters:

element - the element to be removed from this loop.

equalityMethod - determines whether containment is based on reference or value equality. A value of null will be interpreted as a signal to use value equality.

removeAll

public void removeAll()

Removes all elements from this loop.

toScanList

public List<Scan> toScanList()

Returns a list of scans that represents the expansion of this loop and all of its contained loops. The returned list represents the same sequence of scans as this loop does, but in a longhand form.

Returns:

the expanded form of this loop.

See Also:

toScanSet()

toScanSet

public Set<Scan> toScanSet()

Returns the set of scans held by this loop and recursively down through all inner loops. If a scan appears in multiple loops, it has only one entry in the set. The ordering of scans within the returned set is arbitrary.

Returns:

the set of scans held by this loop and all its inner loops.

See Also:

toScanList()

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

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

Creates a new scan loop 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 scan loop 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.

testScansForResourceFromJaxb

public void testScansForResourceFromJaxb()
                                  throws JAXBException

Meant for use by containers of scan loops; most clients should not use this method.

Throws:

JAXBException - if the any scan of this loop has no resource and the useResourceOfPriorScan flag is false.

clearId

public void clearId()

Resets this loop's id to UNIDENTIFIED and calls all of it's chilren's clearId() methods.

Overrides:

clearId in class ScanLoopElement

clone

public ScanLoop clone()

Returns a scan loop that is a deep copy of this one.

The returned loop is, for the most part, a deep copy of this one. For example, any scans or (inner) scan loops in the returned loop will be copies of their counterparts in this loop. 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 loop.

In order to be equal to this loop, o must be non-null and of the same class as this loop. In order for two loops to be equal, they must contain equal elements in the same order. Their iteration counts and maximum durations must also be equal.

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