stella.xml
Class DOMSequence

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractList<E>
          java.util.ArrayList<Collection<DOMSequence.TaskElement>>
              stella.xml.DOMSequence

All Implemented Interfaces:

Serializable, Cloneable, Iterable<Collection<DOMSequence.TaskElement>>, Collection<Collection<DOMSequence.TaskElement>>, List<Collection<DOMSequence.TaskElement>>, RandomAccess, DTDConstants

public class DOMSequence
extends ArrayList<Collection<DOMSequence.TaskElement>>
implements DTDConstants

An XML-parser-application interface to read sequencer files in XML format (see jaxp extension interface to first read in the file and parse it into a parse() method. Only after this method has been called, the DOM-sequence can be traversed with a call to it's iterator method. Note that this iterator delivers a collection of DOMSequence.TaskElements at calls to its next method. The Step as the top-level element of the sequence is only used to construct the list in the correct sequence. A dom sequence is a specialized list in the way that it only allows special elements. Concrete, if you add a sequencer step with one of the list's add method, the object added must be a collection of DOMSequence.TaskElements. The list's addAll method work only if the collection added is a dom sequence. In this case, the awkward checking of the individual elements, as done with the add methods, is not necessarry as a domsequence is believed to be constructed of the correct types.

Although removal and addition of sequencing steps is also possible after the list has been constructed and although this may happen in different threads it is impossible that addition and removal of elements happen at the same time, therfore no synchronization is necessary.

Grammer of the xml-file:
At the time of this writing, the DTD can be found at XMLSequencer.

The complete condition tells the sequencer when it should consider a task as finished. Note that this does not necessarily mean that all commands in this task have been completed.

True and false denote some Triggers that should be set to the appropriate value as this task is ready to execute.

If a Change element is present, its value is used to initiate an external change in the parameter cluster of the sequncer.

The commands are command templates (e.g. MOVE_TELESCOPE) that the sequencer can translate to device-understandable commands at runtime. To allow the sequencer or, more precisely, the rendering helper class used to transform the command template into an actual command three possibilities are available.

If the command carries an id attribute, this attribute is matched as a refernece to an element in the target actually observed. A common use is to reference here the Star-id in a DOMTarget.

If this reference is not unique an (additional) ref attribute may be specified, which must point to a unique element in the element-tree below the element specified with the id-tag (or the entire document, if no id- tag is given).

If the command needs external parameters, like the ambient temperature, additional Parameter elements may be given with the command template. The sequencer retrieves the current value of the stated parameter name out of its parameter list and passes it over to its rendering instance.

See Also:

XMLSequencer, Serialized Form

Nested Class Summary

class	DOMSequence.TaskElement Represents a special Element, namely a Task element in an xml-sequencer file.
static class	DOMSequence.Test Use for testing.

Field Summary

private boolean	parsed A boolean indicating successful parsing.
private Document	xml The document gained from parsing the sequence file.

Fields inherited from class java.util.AbstractList

modCount

Fields inherited from interface stella.xml.DTDConstants

ABORT, ABOVE, ABSTRACT, ABSTRACTPROPOSAL, ADDRESS, BELOW, BLOCK, BROADCAST, BROADCASTWITH, BV, CHANGE, CLASS, COMMAND, COMMANDID, COMMANDINIT, COMMANDLAST, COMMANDPARAMETER, COMMANDREF, COMMENT, COMPLETE, CONDITION, CONSTANT, CONSTANTNAME, CONSTANTVALUE, CONSTRAINT, CONSTRAINTOVERDUE, CONSTRAINTRELAX, DATA, DAUGHTER, DEC, DELAY, DELAYMAX, DELAYTIME, DISABLED, DOCPATH, DURATION, ELAPSED, EMAIL, ENABLED, EPOCH, EQUINOX, EXCEPTION, EXCEPTIONDAUGHTER, EXCEPTIONFOR, EXCEPTIONSUCCESSOR, EXCEPTIONTHIS, FALSE, FIELDOFVIEW, FILE, FITSHEADER, FITSHEADERID, FORMATCLASS, FORMATPATTERN, FROM, GAIN, HISTORY, HISTORYCOMPLETE, HISTORYDB, HISTORYMAX, HISTORYREAD, IGNORE, IMAGETYPE, INIT, INSTITUTION, INSTRUMENT, INTERN, KEY, MAX, MERIT, MIN, NOTIFY, OBJECT, OBJECTID, OBJECTNAME, OBSERVSTART, PICK, PICKMERIT, PICKSUCCESS, PMDEC, PMRA, POSITION, RA, RATE, REC, REQUIRES, RETRY, RETRYMAX, SELECT, SENDING, SEQUENCE, SEQUENCETYPE, SET, SETNAME, SETUP, SETUPID, STEP, STEPCOUNTER, STEPWHILE, SUCCESSOR, TARGET, TARGETACCESS, TARGETDB, TARGETNAME, TARGETNAMEPROPOSAL, TARGETREAD, TARGETSUBMITTED, TARGETTYPE, TASK, TASKDONE, TASKID, TEAM, TIMESLOT, TITLE, TO, TRUE, USER, V, VARIABLE

Constructor Summary

DOMSequence()
Construct a new dom sequence with an empty sequence file.

DOMSequence(Document doc)
Constructs a new dom sequence with the specified target dom.

DOMSequence(File doc)
Constructs a new dom sequence with the specified xml-file.

DOMSequence(URL doc)
Constructs a new dom sequence with the specified xml-file.

Method Summary

int	abortStep(int index) Marks all task belonging to the indicated step as done.
boolean	addAll(Collection c) Overrides the parent's addAll method.
boolean	addAll(int index, Collection c) Overrides the parent's addAll method.
private boolean	checkStep(Object o) Returns true if the object can be inserted as a step into the sequence.
void	clearDom() Clears the document file.
static DOMSequence	emptyList() Returns an empty list.
Collection<DOMSequence.TaskElement>	getAllTasks() Returns all tasks in this sequence as a collection.
Document	getDom() Gets the DOM-documnet this sequence efers to
private int	getOffset(String att) Tests if the attribute is of a back-reference type.
String	getSequenceID() Returns the sequence id of this sequence dom.
boolean	parse() Parses the document.
void	setDom(Document dom) Sets the DOM-document this DOM sequence should refer to.
void	setDom(File xml) Sets the DOM-xml file this DOM sequence should refer to.
void	setDom(URL xml) Sets the DOM-xml file this DOM sequence should refer to.
protected void	updateReferences() Updates command reference attributes with a back-reaction.

Methods inherited from class java.util.ArrayList

add, add, clear, clone, contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, remove, remove, removeRange, set, size, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode, iterator, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

containsAll, removeAll, retainAll, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.List

containsAll, equals, hashCode, iterator, listIterator, listIterator, removeAll, retainAll, subList

Field Detail

xml

private Document xml

The document gained from parsing the sequence file.

parsed

private boolean parsed

A boolean indicating successful parsing.

Constructor Detail

DOMSequence

public DOMSequence()

Construct a new dom sequence with an empty sequence file.

DOMSequence

public DOMSequence(File doc)

Constructs a new dom sequence with the specified xml-file. The list is only ready to use after a call to parse().

DOMSequence

public DOMSequence(URL doc)

Constructs a new dom sequence with the specified xml-file. The list is only ready to use after a call to parse().

DOMSequence

public DOMSequence(Document doc)

Constructs a new dom sequence with the specified target dom. The list is only ready to use after a call to parse().

Method Detail

emptyList

public static DOMSequence emptyList()

Returns an empty list.

checkStep

private boolean checkStep(Object o)

Returns true if the object can be inserted as a step into the sequence. The object must be an instance of collection and all the elements in the collection must be task elements.

addAll

public boolean addAll(Collection c)

Overrides the parent's addAll method. The only collection allowed to add are instances of dom sequences. If the dom sequence is not parsed it is parsed before adding it to the current sequence.

Specified by:

addAll in interface Collection<Collection<DOMSequence.TaskElement>>

Specified by:

addAll in interface List<Collection<DOMSequence.TaskElement>>

Overrides:

addAll in class ArrayList<Collection<DOMSequence.TaskElement>>

Parameters:

c - A dom sequence instance.

Throws:

IllegalArgumentException - If the collection to add is either null or not an instance of dom sequence.

addAll

public boolean addAll(int index,
                      Collection c)

Overrides the parent's addAll method. The only collection allowed to add are instances of dom sequences. If the dom sequence is not parsed it is parsed before adding it to the current sequence.

Specified by:

addAll in interface List<Collection<DOMSequence.TaskElement>>

Overrides:

addAll in class ArrayList<Collection<DOMSequence.TaskElement>>

Parameters:

index - The index where this task element collection should be inserted.

c - A dom sequence instance.

Throws:

IllegalArgumentException - If the collection to add is either null or not an instance of dom sequence.

updateReferences

protected void updateReferences()
                         throws ParseException

Updates command reference attributes with a back-reaction. Any reference attribute found to be equal to DTDConstants.COMMANDLAST is replaced with the last identical command template's reference attribute. If this reserved attribute is followed by a parsable integer it defines a relative offset in the reference replacemant, i.e. a -1 indicates that this reference attribute should be replaced with the attribute of the last occurence of this command template. If no offset is given, -1 is asumed. If the offset is 0, -1 is used. If the part following the reseverd attribute is not parsable, the whole attribute is treated as generic.

This method is synchronized to block any access to the list while updating the references.

Throws:

ParseException - If an offset reference could not be resolved.

getOffset

private int getOffset(String att)

Tests if the attribute is of a back-reference type. If the attribute cannot be interpreted as a back or forward reference, 0 is returned.

setDom

public void setDom(File xml)

Sets the DOM-xml file this DOM sequence should refer to.

setDom

public void setDom(URL xml)

Sets the DOM-xml file this DOM sequence should refer to.

setDom

public void setDom(Document dom)

Sets the DOM-document this DOM sequence should refer to.

clearDom

public void clearDom()

Clears the document file.

getDom

public Document getDom()

Gets the DOM-documnet this sequence efers to

getSequenceID

public String getSequenceID()

Returns the sequence id of this sequence dom. This is a required attribute and is used within a target-definition to uniquely define the observing sequence one target should obey.

Returns:

The Sequence ID-attribute or null if no DOM is loaded.

parse

public boolean parse()

Parses the document. Each DTDConstants.STEP Element is considered an entry in the list. The sequence given in the xml-file is retained. All the DTDConstants.TASKs comprising one step are stored as a DOMSequence.TaskElement collection as one entry in the list.

Note that this parse is independent of the DocumentBuilder.parse(File) method that parses an xml-file int a dom-document.

Returns:

A boolean indicating successful parsing into a task sequence.

abortStep

public int abortStep(int index)

Marks all task belonging to the indicated step as done. This method is not called during normal operation but used to abort actual tasks. In normal operation the sequencer checks the Complete condition of a task and sets it done if this condition is fulfilled.

Returns:

The number of unfinished tasks belonging to the current order.

getAllTasks

public Collection<DOMSequence.TaskElement> getAllTasks()

Returns all tasks in this sequence as a collection. Implementation note: To allow all the add, addAll, clear and remove methods of the list to work as well, we do not use a cached collection, but reconstruct it from the underlying list at each call. This may be a costly operation.