Package sim.engine

Class Sequence

java.lang.Object

sim.engine.Sequence

All Implemented Interfaces:

Serializable, Steppable

Direct Known Subclasses:

ParallelSequence, RandomSequence

public class Sequence
extends Object
implements Steppable

Sequence is Steppable which holds an array of Steppables. When it is stepped, Sequence steps each of its subsidiary Steppables in turn.

You provide Sequence with a Collection of Steppables, or with an array of Steppables, via its constructor. It then copies the Collection or array into its own internal array and uses that whenever you step it.

You can also modify the Steppables after the fact, in one of three ways. First, you can provide a new Collection or array to replace the internal array it is presently using, via the method replaceSteppables(...). Second, you can provide a collection of Steppables to be removed from the internal array, via the methods removeSteppable(...) or removeSteppables(...). Third, you can provide a collection of Steppables to be added to the internal array, via the methods addSteppable(...) or addSteppables(...). Sequence delays performing these actions until step(...) is called on it. At which time it first replaces the Steppabes with those provided by replaceSteppables(...), then removes any Steppables requested, then finally adds any Steppables requested. It then steps all the Steppables in the resulting internal array.

By default, after removing Steppables from the internal array, Sequence does not guarantee that the remaining Steppables will still be in the same order. It does this for speed. If you want to force them to be in the same order, you can call setEnsuresOrder(true). Note that even if the array has a consistent order internally, subclasses are free to ignore this: for example, RandomSequence and ParallelSequence do not keep the order consistent.

Removing Steppables is costly: the Sequence has to hunt through its array to find the ones you've asked to be removed, and that's O(n) per Steppable to remove. If you are often removing a fair number of Steppables (perhaps more than 5 at a time), Sequence provides a further option which results in O(1) removal: using an internal Set. The procedure is as follows: all the current Steppables, or the ones to relace them, are maintained in a LinkedHashSet. The Steppables to be removed are removed from the Set (O(1) per Steppable). Steppables to be added are then added to the Set. Finally the Set is dumped to an array, which is then Stepped.

To turn on this option, call setUsesSets(true).

This approach is dramatically faster than the default approach when a large number of Steppables are in the Sequence and at least a moderate number (5 or greater typically) is removed at a time. It has three disadvantages however. First, it is slower when the number of Steppables is very small, or when the number of Steppables removed is small (less than 5 perhaps). Second, because a Set is used, the Steppables in the Sequence must be unique: you cannot insert the same Steppable multiple times in the array. Third, using sets does not ensure order regardless of what you stated in setEnsuresOrder(...).

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
protected int	size	The number of actual Steppables in the steps array.
protected Steppable[]	steps	The internal Steppables to be stepped.

Constructor Summary

Constructors

Constructor	Description
Sequence(Collection collection)
Sequence(Steppable[] steps)

Method Summary

Modifier and Type	Method	Description
void	addSteppable(Steppable steppable)	Requests that the provided Steppable be added to the Sequence prior to the next step() call.
void	addSteppables(Collection steppables)	Requests that the provided Steppables be added to the Sequence prior to the next step() call.
void	addSteppables(Steppable[] steppables)	Requests that the provided Steppables be added to the Sequence prior to the next step() call.
protected boolean	canEnsureOrder()	If your subclass does not respect order, override this method to return false, and Sequence will ignore the ensuresOrder result.
boolean	getEnsuresOrder()	Returns whether the order among the remaining Steppables in the internal array is maintained after removing Steppables via removeSteppable() or removeSteppables().
boolean	getUsesSets()	Returns whether the Sequence uses a Set internally to manage the internal array.
protected void	loadSteps()	Subclasses should call this method as more or less the first thing in their step(...) method.
void	removeSteppable(Steppable steppable)	Requests that the provided Steppable be removed from the Sequence prior to the next step() call.
void	removeSteppables(Collection steppables)	Requests that the provided Steppables be removed from the Sequence prior to the next step() call.
void	removeSteppables(Steppable[] steppables)	Requests that the provided Steppables be removed from the Sequence prior to the next step() call.
void	replaceSteppables(Collection collection)	Requests that the provided Steppables replace the existing Steppables in the internal array prior to the next step() call.
void	replaceSteppables(Steppable[] steppables)	Requests that the provided Steppables replace the existing Steppables in the internal array prior to the next step() call.
void	setEnsuresOrder(boolean val)	Sets whether the order among the remaining Steppables in the internal array is maintained after removing Steppables via removeSteppable() or removeSteppables().
void	setUsesSets(boolean val)	Sets whether the Sequence uses a Set internally to manage the internal array.
void	step(SimState state)

Methods inherited from class java.lang.Object

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

Field Details

steps

protected Steppable[] steps

The internal Steppables to be stepped. Only steps[0...size-1] are valid. This array will be populated after loadSteps() is called.

size

protected int size

The number of actual Steppables in the steps array.

Constructor Details

Sequence

public Sequence(Steppable[] steps)

Sequence

public Sequence(Collection collection)

Method Details

getEnsuresOrder

public boolean getEnsuresOrder()

Returns whether the order among the remaining Steppables in the internal array is maintained after removing Steppables via removeSteppable() or removeSteppables(). Note that this value may be entirely ignored by subclasses for which maintaining order doesn't make sense (such as parallel or random sequences). Also if you use sets (via setUsesSets(true)), then order is never ensured regardless.

setEnsuresOrder

public void setEnsuresOrder(boolean val)

Sets whether the order among the remaining Steppables in the internal array is maintained after removing Steppables via removeSteppable() or removeSteppables(). Note that this value may be entirely ignored by subclasses for which maintaining order doesn't make sense (such as parallel or random sequences). Also if you use sets (via setUsesSets(true)), then order is never ensured regardless.

canEnsureOrder

protected boolean canEnsureOrder()

If your subclass does not respect order, override this method to return false, and Sequence will ignore the ensuresOrder result.

getUsesSets

public boolean getUsesSets()

Returns whether the Sequence uses a Set internally to manage the internal array. This is faster, often much faster, for large numbers of removals (perhaps more than 5 or so), but requires that each Steppable in the internal array be unique.

setUsesSets

public void setUsesSets(boolean val)

Sets whether the Sequence uses a Set internally to manage the internal array. This is faster, often much faster, for large numbers of removals (perhaps more than 5 or so), but requires that each Steppable in the internal array be unique.

loadSteps

protected void loadSteps()

Subclasses should call this method as more or less the first thing in their step(...) method. This method replaces, removes, and adds new Steppables to the internal array as directed by the user. After calling this method, the Sequence is ready to have the Steppables in its internal array stepped.

replaceSteppables

public void replaceSteppables(Collection collection)

Requests that the provided Steppables replace the existing Steppables in the internal array prior to the next step() call.

replaceSteppables

public void replaceSteppables(Steppable[] steppables)

Requests that the provided Steppables replace the existing Steppables in the internal array prior to the next step() call.

addSteppable

public void addSteppable(Steppable steppable)

Requests that the provided Steppable be added to the Sequence prior to the next step() call.

addSteppables

public void addSteppables(Steppable[] steppables)

Requests that the provided Steppables be added to the Sequence prior to the next step() call.

addSteppables

public void addSteppables(Collection steppables)

Requests that the provided Steppables be added to the Sequence prior to the next step() call.

removeSteppable

public void removeSteppable(Steppable steppable)

Requests that the provided Steppable be removed from the Sequence prior to the next step() call.

removeSteppables

public void removeSteppables(Steppable[] steppables)

Requests that the provided Steppables be removed from the Sequence prior to the next step() call.

removeSteppables

public void removeSteppables(Collection steppables)

Requests that the provided Steppables be removed from the Sequence prior to the next step() call.

step

public void step(SimState state)

Specified by:

step in interface Steppable