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, 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