Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## sim.engine
Class Sequence

    java.lang.Object
      sim.engine.Sequence

All Implemented Interfaces:
  java.io.Serializable, Steppable

Direct Known Subclasses:
  ParallelSequence, RandomSequence

    public class Sequence

extends java.lang.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 is set in setEnsuresOrder(...).

See Also:
  Serialized Form

Field Summary
`protected int` | `size` The number of actual Steppables in the steps array.
`protected Steppable[]` | `steps` The internal Steppables to be stepped.

Constructor Summary
`Sequence(java.util.Collection collection)`
`Sequence(Steppable[] steps)`

Method Summary
`void` | `addSteppable(Steppable steppable)` Requests that the provided Steppable be added to the Sequence prior to the next step() call.
`void` | `addSteppables(java.util.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(java.util.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(java.util.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 Detail

### 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 Detail

### Sequence

    public Sequence(Steppable[] steps)

### Sequence

    public Sequence(java.util.Collection collection)

Method Detail

### 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(java.util.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(java.util.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(java.util.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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD