xdc.services.getset
Class Group

java.lang.Object
  extended by xdc.services.getset.Group

public class Group
extends java.lang.Object

A group of Fxns that are each run to completion before any other Fxn in the group. The purpose of a Group is to control interactions between a group of setters. Within each Group the Fxns execute one at a time. Even if a Fxn makes changes that will cause another Fxn in the Group to run, that won't happen until after the first Fxn completes. This allows setters within a group to modify internal state without interference from other setters in the same Group (that may operate on the same internal state). Each group runs to completion. When a setter in the group runs, it might modify other config params and schedule further setters in the same group to run. All of these complete before control is returned to the original execution flow. From the point of view of code outside the group, all the setters ran as an atomic operation. Groups may be interrupted. When a setter modifies a config param that is being monitored by a second group, the second group starts running immediately. It will run to completion before returning control to the first group. So the first group sees the second group as atomic. This allows groups to be tested independently, and combined without affecting their behavior. Cycles aren't permitted in the execution flow between groups. If a setter gets triggered from a group that has already been interrupted, it is deferred and run when control eventually returns to its own group. Cycles between groups can break the appearance of atomic execution, and so should be avoided when possible. Exceptions thrown by a Fxn f in a group only trigger the retraction the value of the Observable associated with f or any Observable that recursively triggered f. Groups only control the order of execution of setters and do not, in the event of an exception, cause retraction of all values set by the setters in the group. Since retractions occur "one value at a time", setters that check consistency amoung multiple values risk triggering an exception duringa retraction; this results in a "double fault" fatal error and must be avoided by the setters.


Constructor Summary
Group()
          Create a new Group governed by the given scheduler
 
Method Summary
 Fxn add(Fxn fxn)
          Add a new Fxn to the group, and execute it once.
 AutoFxn addAuto(org.mozilla.javascript.Callable body)
          Wrap the given function body as an AutoFxn and add it to the group.
 void addStale(Fxn fxn)
          Indicate that a Fxn in the group needs to be run.
static int getMaxIterations()
          Get the maximum number of iterations allowed in each group, as a debugging aid.
 Fxn getRunning()
          Get the currently running function (unused?)
 boolean getScheduled()
          Ask if the Group has already been scheduled to be run
 boolean getStale()
          Ask if the group needs to be run.
 Fxn onSet(xdc.services.intern.xsr.Value.Observable obj, int index, org.mozilla.javascript.Callable body)
           
 Fxn onSet(xdc.services.intern.xsr.Value.Observable obj, java.lang.String name, org.mozilla.javascript.Callable body)
          Wrap the given function body as a Fxn and specify one input to fire on.
 void removeStale()
          Indicate that no Fxn's in the group need to be run.
 void removeStale(Fxn fxn)
          Indicate that a Fxn in the group no longer needs to be run.
 void run()
          Run all the Fxns in the Group that need it.
 void schedule(Fxn fxn)
          Mark the given Fxn as stale, and schedule the whole group to be run at the next opportunity.
static void setMaxIterations(int maxIterations)
          Get the maximum number of iterations allowed in each group, as a debugging aid.
 void setScheduled(boolean scheduled)
          Indicate that the Group has now been scheduled to be run
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Group

public Group()
Create a new Group governed by the given scheduler

Method Detail

onSet

public Fxn onSet(xdc.services.intern.xsr.Value.Observable obj,
                 java.lang.String name,
                 org.mozilla.javascript.Callable body)
Wrap the given function body as a Fxn and specify one input to fire on. Add it to the group and execute it once.

Returns:
the Fxn, so that additional inputs and outputs can be specified.

onSet

public Fxn onSet(xdc.services.intern.xsr.Value.Observable obj,
                 int index,
                 org.mozilla.javascript.Callable body)

addAuto

public AutoFxn addAuto(org.mozilla.javascript.Callable body)
Wrap the given function body as an AutoFxn and add it to the group. Executes the function once.

A typical use is to establish two-way update between related XDCscript fields, say x.a and y.b :

   group.addAuto(function bToA(){ x.a = y.b; });
   group.addAuto(function aToB(){ y.b = x.a; });
 
This example constrains x.a and y.b to have the same value. Whenever one of them changes, one AutoFxn in the Group runs and copies the change to the other field. The Group is responsible for deciding when to execute each AutoFxn, based on examining its inputs and outputs.

Returns:
the AutoFxn, so that additional inputs and outputs can be specified.

add

public Fxn add(Fxn fxn)
Add a new Fxn to the group, and execute it once.


getStale

public boolean getStale()
Ask if the group needs to be run. Should be run whenever any Fxn in the group is stale.


addStale

public void addStale(Fxn fxn)
Indicate that a Fxn in the group needs to be run.


removeStale

public void removeStale(Fxn fxn)
Indicate that a Fxn in the group no longer needs to be run.


removeStale

public void removeStale()
Indicate that no Fxn's in the group need to be run.


setScheduled

public void setScheduled(boolean scheduled)
Indicate that the Group has now been scheduled to be run


getScheduled

public boolean getScheduled()
Ask if the Group has already been scheduled to be run


getRunning

public Fxn getRunning()
Get the currently running function (unused?)


run

public void run()
Run all the Fxns in the Group that need it.


schedule

public void schedule(Fxn fxn)
Mark the given Fxn as stale, and schedule the whole group to be run at the next opportunity.


getMaxIterations

public static int getMaxIterations()
Get the maximum number of iterations allowed in each group, as a debugging aid.


setMaxIterations

public static void setMaxIterations(int maxIterations)
Get the maximum number of iterations allowed in each group, as a debugging aid.