stella.xml
Class XMLSequencer

java.lang.Object
  util.PropertyContainer
      util.PropertyResources
          util.PropertyBundles
              util.rmi.RmiPropertyContainer
                  util.rmi.AbstractRmiCaster
                      stella.CastingContainer
                          stella.AbstractSequencer<Collection<DOMSequence.TaskElement>>
                              stella.xml.XMLSequencer

All Implemented Interfaces:

Cloneable, Runnable, Remote, ClusterDepending, ReplySubscriber, ReservedTriggers, Sequencing<Collection<DOMSequence.TaskElement>>, CancelRunnable, ExitCleaning, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying, RmiCaster, RmiPropertyBearing

public class XMLSequencer
extends AbstractSequencer<Collection<DOMSequence.TaskElement>>
implements ReservedTriggers, CancelRunnable

Nested Class Summary

private class

XMLSequencer.Conditioner The helper class that deals with incoming reply messages.

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.URLResource

Field Summary

static String	ACKNOWLEDGE_PREFIX The String prefixing an acknowledge command trigger.
private boolean	cancel The cancel flag.
static Object	CHAINING The type signaling pure chaining targets with no steps.
private CommandRendering	chef A link to the master command renderer.
protected static char	COLON The seperator char between command templates and ref-attributes.
private static long	DEFSLEEP Default maximum sleeping period, in ms.
private static ThreadGroup	DELAY The thread group the alarms run in ('delay').
private CommandLaunching[]	devices The devices, abstract representations of remote command servers.
private DOMSequence	dom The DOMSequence helper object.
static String	DONE_PREFIX The String prefixing a done command trigger.
private ParameterClustering	extern A trigger set of external triggers.
private Map	finished The triggers linked to completed tasks, set by the sequencer.
static String	KEY_DEVICETRIGGERS The key matching to a comma-separated list of device trigger endings.
static String	KEY_NAMEDTRIGGERS The key matching to a comma-separated list of additional triggers.
static String	KEY_SLEEP The key matching the maximum sleep period for the sequencer, in ms.
static String	KEY_TARGETTYPES The key matching to the sequence-definition properties file.
private Map	local The local triggers, set by the sequencer.
private Object	lock The synchronizing object.
private Map	lookUp A lookup table matching command templates to a list of replies.
private Map	matchUp A lookup table matching reply events plus time to reply templates.
private Thread	mythread A reference to the thread the sequencer is running in.
protected static char	PLUS The char to indicate delayed trigger response.
private Map	replies The internal triggers constructed from replies.
private long	sleep The sleep time, ms.
private ListIterator<Collection<DOMSequence.TaskElement>>	step The list iterator to pass through the dom sequence.
private Collection<DOMSequence.TaskElement>	task The collection of tasks belonging to the current step.
private Map	typetable The lookup table for target types to sequence xml-files.

Fields inherited from class util.rmi.AbstractRmiCaster

ALTERNATEHOST, ALTERNATEPORT, KEY_BINDNAME, KEY_EXPORTPORT, KEY_REGISTRYHOST, KEY_REGISTRYPORT

Fields inherited from class util.PropertyBundles

KEY_LOCALECOUNTRY, KEY_LOCALELANGUAGE, KEY_RESOURCEBUNDLES

Fields inherited from class util.PropertyResources

KEY_NOINITONCREATE, localurl, locate, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_URL, urlset

Fields inherited from class util.PropertyContainer

KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface stella.ReservedTriggers

RESERVED

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Fields inherited from interface util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Constructor Summary

XMLSequencer(Map<String,String> parser)
Constructs a new xml-sequence instant.

Method Summary

void	abort(List<Collection<DOMSequence.TaskElement>> abort) Aborts current task and sequence.
void	append(List<Collection<DOMSequence.TaskElement>> append) Appends the sequencing step found in the target file at the end of the current sequence.
void	cancel() Cancel this sequencer.
void	forward(ReplyEvent answer) This method is called by the ReplyDeliverer.
Thread	getAsociatedThread() Returns the thread the sequencer is running in.
DOMSequence	getStepsForTarget(TargetDefinition target) Converts an identifier into a list of sequencer steps.
private String	getVariableFromReply(ReplyEvent reply) Converts an incomming reply to a reply variable.
private void	insert(int index, int start, List xml) Inserts the sequence dom stored in the argument file at the given position.
boolean	isCancel() Tests if the last sequence was executed successfully.
void	load(List<Collection<DOMSequence.TaskElement>> xml) Loads a sequencer file.
long	maxTimeToCancel() Returns the maximum time the sequencer needs to cancel.
void	prepend(List<Collection<DOMSequence.TaskElement>> prep) Prepends the sequncing step found in the target file at the start of the current sequence.For expansion of comand version, see insert(int, int, java.util.List).
boolean	query(String istrue) Parses a string following the general boolean algebra rules.
void	registerCluster(ParameterClustering externals) Register the set of external triggers.
void	registerLauncher(CommandLaunching[] launch) Registers a set of devices.
void	registerRender(CommandRendering boss) Registers the master mind.
void	retrieveReplies() Parses boolean expression for all variable names.
void	run() The run method of the sequencer.
private void	setReady(String[] template, boolean to) Sets directly stated triggers.
protected void	setReply(String varname, Boolean val) Sets a specified variable to a value.
private void	setTaskTriggers() Scans the DOMSequence for all task references.
private void	setupLocals() Sets up the local variables.
Thread	start() Starts the sequencer in a well-known thread.
String	toString() Returns the class name of this sequencer and the current tasks worked on.

Methods inherited from class stella.AbstractSequencer

createSequencer

Methods inherited from class stella.CastingContainer

addErrorListener, addRmiErrorListener, exit, isValid, notifyErrorListener, removeErrorListener, removeRmiErrorListener, sendError, sendError, sendError, sendStatus, sendStatus, sendStatus

Methods inherited from class util.rmi.AbstractRmiCaster

bindAlternate, bindToRegistry, bindToRegistry, bindToRegistry, casterExit, casterExit, getBindName, getBindName, unbindFromRegistry, unbindFromRegistry

Methods inherited from class util.rmi.RmiPropertyContainer

containsRemoteProperty, getRemoteProperties, getRemoteProperty, setRemoteProperty

Methods inherited from class util.PropertyBundles

clone, getLocalized, getLocalized, getLocalizedString, getLocalizedString, loadResource

Methods inherited from class util.PropertyResources

createFrom, createFrom, createFrom, getApplet, getAsResources, getLocalClassLoader, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, init, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer

augment, augment, augment, defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsEnums, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, isNew, parseObject, reload, removeProperty, rescanned, setObject, setProperties, setProperty, stringProperties

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface util.PropertySupplying

defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, parseObject, removeProperty, setObject, setProperty, stringProperties

Methods inherited from interface util.ResourceSupplying

getResource, getResourceAsStream, getResources

Methods inherited from interface util.Initializable

init

Field Detail

DONE_PREFIX

public static final String DONE_PREFIX

The String prefixing a done command trigger.

See Also:

Constant Field Values

ACKNOWLEDGE_PREFIX

public static final String ACKNOWLEDGE_PREFIX

The String prefixing an acknowledge command trigger.

See Also:

Constant Field Values

CHAINING

public static final Object CHAINING

The type signaling pure chaining targets with no steps.

KEY_TARGETTYPES

public static final String KEY_TARGETTYPES

The key matching to the sequence-definition properties file.

See Also:

Constant Field Values

KEY_SLEEP

public static final String KEY_SLEEP

The key matching the maximum sleep period for the sequencer, in ms.

See Also:

Constant Field Values

KEY_DEVICETRIGGERS

public static final String KEY_DEVICETRIGGERS

The key matching to a comma-separated list of device trigger endings.

See Also:

Constant Field Values

KEY_NAMEDTRIGGERS

public static final String KEY_NAMEDTRIGGERS

The key matching to a comma-separated list of additional triggers.

See Also:

Constant Field Values

DEFSLEEP

private static final long DEFSLEEP

Default maximum sleeping period, in ms.

See Also:

Constant Field Values

COLON

protected static final char COLON

The seperator char between command templates and ref-attributes.

See Also:

Constant Field Values

PLUS

protected static final char PLUS

The char to indicate delayed trigger response.

See Also:

Constant Field Values

chef

private CommandRendering chef

A link to the master command renderer.

devices

private CommandLaunching[] devices

The devices, abstract representations of remote command servers.

extern

private ParameterClustering extern

A trigger set of external triggers. Provides quick lookup.

local

private Map local

The local triggers, set by the sequencer. Reset after each sequence.

finished

private Map finished

The triggers linked to completed tasks, set by the sequencer.

replies

private Map replies

The internal triggers constructed from replies.

matchUp

private Map matchUp

A lookup table matching reply events plus time to reply templates.

lookUp

private Map lookUp

A lookup table matching command templates to a list of replies.

typetable

private Map typetable

The lookup table for target types to sequence xml-files.

dom

private DOMSequence dom

The DOMSequence helper object.

step

private ListIterator<Collection<DOMSequence.TaskElement>> step

The list iterator to pass through the dom sequence.

task

private Collection<DOMSequence.TaskElement> task

The collection of tasks belonging to the current step.

mythread

private Thread mythread

A reference to the thread the sequencer is running in.

cancel

private boolean cancel

The cancel flag.

lock

private Object lock

The synchronizing object.

sleep

private long sleep

The sleep time, ms.

DELAY

private static final ThreadGroup DELAY

The thread group the alarms run in ('delay').

Constructor Detail

XMLSequencer

public XMLSequencer(Map<String,String> parser)

Constructs a new xml-sequence instant. Using this constructor and therefore creating an instance of an xml-sequence In the construction process no parsing or converting is done.

The properties handed over to the constructer are also used to define the properties of the helper class, DOMSequence.

If the KEY_TARGETTYPES is not present in this sequencers properties an NullPointerException is thrown.

Method Detail

registerRender

public void registerRender(CommandRendering boss)

Registers the master mind. Must be called prior to start.

Specified by:

registerRender in interface Sequencing<Collection<DOMSequence.TaskElement>>

registerCluster

public void registerCluster(ParameterClustering externals)

Register the set of external triggers. Triggers that are event triggers receive this sequencer instance as the notification thread.

Specified by:

registerCluster in interface ClusterDepending

registerLauncher

public void registerLauncher(CommandLaunching[] launch)

Registers a set of devices. Devices are abstract representations of command servers. The sequencer delegates fully qualified commands to these servers.

Additionally, this sequencer registers as the ReplySubscriber at all command launchers if the argument is non-null.

Specified by:

registerLauncher in interface Sequencing<Collection<DOMSequence.TaskElement>>

start

public Thread start()

Starts the sequencer in a well-known thread. Reference to the sequencer thread is stored for further information.

Specified by:

start in interface Sequencing<Collection<DOMSequence.TaskElement>>

Returns:

The thread that has just been started

getAsociatedThread

public Thread getAsociatedThread()

Returns the thread the sequencer is running in. If the sequencer is not running, i.e. the sequencer's thread is not alive, this method returns null.

Specified by:

getAsociatedThread in interface CancelRunnable

getStepsForTarget

public DOMSequence getStepsForTarget(TargetDefinition target)

Converts an identifier into a list of sequencer steps. This sequencer matches the type of the target to a sequencer xml-file. If the file can be loaded and parsed, a DOMSequence list is returned.

Specified by:

getStepsForTarget in interface Sequencing<Collection<DOMSequence.TaskElement>>

load

public void load(List<Collection<DOMSequence.TaskElement>> xml)

Loads a sequencer file. An XML-sequencer expects the sequencing step to be in xml format, i.e. the list must be an DOMSequence. No clearing steps are performed.

Specified by:

load in interface Sequencing<Collection<DOMSequence.TaskElement>>

abort

public void abort(List<Collection<DOMSequence.TaskElement>> abort)

Aborts current task and sequence. If the argument file is not null the sequence is loaded as the new sequence.

Specified by:

abort in interface Sequencing<Collection<DOMSequence.TaskElement>>

append

public void append(List<Collection<DOMSequence.TaskElement>> append)

Appends the sequencing step found in the target file at the end of the current sequence. For expansion of comand version, see insert(int, int, java.util.List).

Specified by:

append in interface Sequencing<Collection<DOMSequence.TaskElement>>

prepend

public void prepend(List<Collection<DOMSequence.TaskElement>> prep)

Prepends the sequncing step found in the target file at the start of the current sequence.For expansion of comand version, see insert(int, int, java.util.List).

Specified by:

prepend in interface Sequencing<Collection<DOMSequence.TaskElement>>

cancel

public void cancel()

Cancel this sequencer. It's asociated thread dies. Sequencer can only be restarted in a new thread.

Specified by:

cancel in interface CancelRunnable

maxTimeToCancel

public long maxTimeToCancel()

Returns the maximum time the sequencer needs to cancel.

Specified by:

maxTimeToCancel in interface CancelRunnable

isCancel

public boolean isCancel()

Tests if the last sequence was executed successfully. Currently, only aborted sequences return a non-null error event.

Specified by:

isCancel in interface Sequencing<Collection<DOMSequence.TaskElement>>

run

public void run()

The run method of the sequencer.

Specified by:

run in interface Runnable

forward

public void forward(ReplyEvent answer)

This method is called by the ReplyDeliverer. It spawns an extra thread that process the reply to allow fast-return of this method.

• The ReplyEvent.getReplyMatch() is called.
• The hashtable keys are compared to the freshly generated variable name.
• Exact matches result in an immediate true setting of the asociated variable.
• If the name matches, but the hastable entry has an additional time delay attached to it with a plus sign, an Alarm with the Hashtable name of the variable (i.e. including the time delay string) is generated and started.
• If a variable has changed its value, the Sequencer's monitor object is notified.

Specified by:

forward in interface ReplySubscriber

setReply

protected void setReply(String varname,
                        Boolean val)

Sets a specified variable to a value. This method is useful for changing external variables that are not part of the received replies.

query

public boolean query(String istrue)
              throws ParseException

Parses a string following the general boolean algebra rules. The result of the expression parsing must be a Boolean instance. Variable names that can be translated to entries in this class's variable lookup table are converted to their primitive boolean string, namely true or false, before a call to the expression parser is made. If a ParseException is thrown by the boolean parser false is returned and an error message is passed to registered listeners.

Throws:

ParseException

See Also:

ExpressionNode

retrieveReplies

public void retrieveReplies()
                     throws ParseException

Parses boolean expression for all variable names. The boolean expressions scanned are in the Condition tags in the Complete tag.

Throws:

ParseException

toString

public String toString()

Returns the class name of this sequencer and the current tasks worked on.

Overrides:

toString in class PropertyContainer

setupLocals

private void setupLocals()

Sets up the local variables. All local variables that may ever be used during the life-time of the sequencer must be set already here. This requires that the KEY_DEVICETRIGGERS and the KEY_NAMEDTRIGGERS already point to an entire list.

setReady

private void setReady(String[] template,
                      boolean to)

Sets directly stated triggers. The two tags DTDConstants.TRUE and DTDConstants.FALSE work on the following triggers:

• First, test if the template name is a unique name in the set of external triggers in the parameter cluster extern. If the reference is resolvable, the trigger is set to the appropriate value. Note that not all external triggers allow setting of their value. An UnsupportedException may be thrown as a result.
• If the reference cannot be found in the external trigger list, the internal list of sequence-triggers, see KEY_NAMEDTRIGGERS is used for resolving the reference.
• If this look-up is not successful either, the internal task-triggers are checked finished. If this look-up is successful, the appropriate task's done attribute is set to the stated value, regardless of the actual execution status of the task.

Please note that the use of internal triggers (pt.2) is only justified for triggers that have their meaning only within a single sequence. Triggers that, e.g., qualify whether any group is executed should be linked to an external trigger to allow them to be available even after the current sequence has ended.

insert

private void insert(int index,
                    int start,
                    List xml)

Inserts the sequence dom stored in the argument file at the given position. Index is absolute in sequencing position, meaning that an insert index of zero prepends the new sequence before the old sequence. A true prepend after already completed tasks is possibly by using the nextIndex of the list iterator step.

Inserting a new sequence into an old one has a problem with command template version numbers. It is believed, however, that a simple procedure is sufficient to overcome this problem and to cover all possible error cases. The general contract is:

• If the command templates in the new sequence do have version numbers attached to it, they are inserted in the sequence as is.
• If version numbers are omitted on the templates the current sequence is scanned up to the point of insertion. The last version number found for the command template under question is appended to the newly inserted sequence. If no version number is found 1 is appended though this may cause problems with command completion.
• Mixed modes are possible.

Note that this procedure can possibly only deal with single-command non-version sequences as it is maybe not useful to state, e.g., two MOVE commands without version number because they will point to the same command.

This method does not abort the current tasks. If this behaviour is intended the DOMSequence.abortStep(int) has to be called before this method.

Throws:

IllegalArgumentException - If index is less than zero or higher than the number of active orders in the current sequence.

setTaskTriggers

private void setTaskTriggers()

Scans the DOMSequence for all task references. Each reference is used as a task trigger, consisting of the tag name of the task element, DTDConstants.TASK, plus its unique reference. All tasks present in the dom sequence are scanned and their DTDConstants.TASKDONE flag is evaluated.

getVariableFromReply

private String getVariableFromReply(ReplyEvent reply)

Converts an incomming reply to a reply variable. This is done by roaming thru the look-up table if the raw reply event (without version number) is matched here to the starting character sequence of a key. If so, the command issue time stored in the look-up table is compared to the command issue time found in the reply. If they are identically, the complete key with version number is returned. If no match is found null is returned.