## org.ascape.model.rule
Class Rule

    java.lang.Object
      org.ascape.model.AscapeObject
          org.ascape.model.rule.Rule

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, HasName, RandomFunctions

Direct Known Subclasses:
  CollectStats, ExecuteThenUpdate, MoveRandomWithin, Propogate, SearchRule, SetValues

    public abstract class Rule

extends AscapeObject

An abstract base class for behaviors that can be be iterated across agent scapes or a single agent. You can subclass rule to provide any kind of behavior you want for an agent. Often, rules will simply call agent member functions. But, because rules aren't themselves member functions of agents, they don't need to follow class inheiritance rules, and they can be added, removed and executed dynamically. In effect, they provide a kind of dynamic method dispatch capability to the framework, and allow us to flexibly execute methods upon collections of agents without needing to know anything about the underlying structure of the collection or the method of execution. The system is designed to be powerful, without imposing large performance or conceptual costs. For many common tasks, you can use built-in rules. For example, if you want to allow movement for your agents, you can add a standard movement rule to the scape containing them. These rules are memebers of the Agent and Cell classes.

     scape.addRule(MOVEMENT_RULE);

Then, simply override the built-in agent movement rule.

###

###

###

###

###

###

###

     public class MyAgent extends CellOccupant {
     ...
     public void movement() {
     [Your movement code]
     }
     ...
     }

     There are a number of rules that have behavior allready defined. (And more planned.)
     For these ruels, you simply need to add them to  a scape. So to have you agents take a
     random walk in any direction, simply add the random walk rule.
     <pre>
     scape.addRule(RANDOM_WALK_RULE);
     <pre>
     To create your own rules you can implement a rule as a straight-forward class. You may
     want to do this if there is significant state that is kept as part of the rule, as we do
     for our stat collector and value setter rules, or if you want to extend rules in different
     ways. But typically, rules are implemented as inner classes, static member classes or
     anoymous inner classes.
     <pre>
     scape.addRule(new Rule("Update Radius & ExecutionStrategy") {
     public void execute(Agent agent) {
     ((NormCell) agent).updateRadius();
     ((NormCell) agent).updateStrategy();
     }
     });
     </pre>
     Information about the rule provided by the isRandomExecution and isCauseDelete is used by
     the scape execution methods to optimize rule execution. The default behavior is conservative,
     that is, rules are assumed to need random execution and potentially cause deletion in their
     parent scapes. For better performance, if your rules do not need to be execute randomly (typically
     because their outcomes do not affect otehr agents and/or are not affected by execution order),
     or cannot cause an agent to be deleted, you should override these methods and return false.

    Since:
      1.0
    Version:
      1.0
    Author:
      Miles Parker
    See Also:Scape,
    Agent,
    Cell,
    StatCollector,
    ValueSetter,
    Propogate,
    Serialized Form

    Field Summary

    Fields inherited from class org.ascape.model.AscapeObject

    ARBITRARY_SEED, name, PLATFORM_DEFAULT_COLOR, scape

    Constructor Summary

    Rule(java.lang.String name)

              Constructs a rule with the providied name.

    Method Summary

    abstract  void
    execute(Agent agent)

              Perform the rule for the specified agent.

     Scape
    getScape()

              Returns the scape the agent will act within.

     boolean
    isCauseRemoval()

              Could this rule cause the removal of any agents from within an this
     rule's scape or any agent's scape? Used to determine safe optimization of
     iterations.

     boolean
    isIterateAll()

              Should this rule be iterated across all even if iterations per cycle is
     set? Typically false.

     boolean
    isRandomExecution()

              Does this action affect the state of any other agent in such a way that
     that another agent's execution of this rule would be affected?
     Used to determine safe optimization of iterations.

     void
    setScape(Scape scape)

              Sets the scape for the agent to act within.

    Methods inherited from class org.ascape.model.AscapeObject

    clone, diffDeep, diffDeep, diffDeepBFS, diffDeepDFS, diffDeepValidate, diffDeepVisit, equalsDeep, equalsDeep, equalsDeep, getComparisonStream, getName, getRandom, getRandomSeed, randomInRange, randomInRange, randomIs, randomToLimit, reseed, setComparisonStream, setName, setRandom, setRandomSeed, toString

    Methods inherited from class java.lang.Object

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

    Constructor Detail

    Rule

    public Rule(java.lang.String name)

    Constructs a rule with the providied name.
     It is strongly encouraged to provide a name for all rules.
     This name will be used for run time rule selection and provides important information
     fopr analyzing and debugging models.

    Parameters:name - the name of this object

    Method Detail

    execute

    public abstract void execute(Agent agent)

    Perform the rule for the specified agent.

    Parameters:agent - the target agent.

    setScape

    public void setScape(Scape scape)

    Sets the scape for the agent to act within.

    Overrides:setScape in class AscapeObject

    Parameters:scape - the scape that this rule 'belongs' to

    getScape

    public Scape getScape()

    Returns the scape the agent will act within.

    Overrides:getScape in class AscapeObject

    Returns:the scape

    isRandomExecution

    public boolean isRandomExecution()

    Does this action affect the state of any other agent in such a way that
     that another agent's execution of this rule would be affected?
     Used to determine safe optimization of iterations.

    Returns:true, if is random execution

    isCauseRemoval

    public boolean isCauseRemoval()

    Could this rule cause the removal of any agents from within an this
     rule's scape or any agent's scape? Used to determine safe optimization of
     iterations.

    Returns:true, if is cause removal

    isIterateAll

    public boolean isIterateAll()

    Should this rule be iterated across all even if iterations per cycle is
     set? Typically false. Used for rules like INITIALIZE that must be
     executed on all agents.

    Returns:true, if is iterate all