edu.brook.ascape.rule
Class Rule

java.lang.Object
  |
  +--edu.brook.ascape.model.AscapeObject
        |
        +--edu.brook.ascape.rule.Rule

Direct Known Subclasses:

CollectStats, ExecuteThenUpdate, MoveRandomWithin, Propogate, 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 perfromace 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.
 
 scape.addRule(RANDOM_WALK_RULE);
 
 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.
 
 	scape.addRule(new Rule("Update Radius & Strategy") {
 	    public void execute(Agent agent) {
          ((NormCell) agent).updateRadius();
          ((NormCell) agent).updateStrategy();
 	    }
 	});
 
 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
See Also: 
edu.brook.ascape.view.Scape, 
edu.brook.ascape.view.Agent, 
edu.brook.ascape.view.Cell, 
StatCollector, 
ValueSetter, 
Propogate, Serialized Form









Fields inherited from class edu.brook.ascape.model.AscapeObject
ARBITRARY_SEED,  
count,  
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 edu.brook.ascape.model.AscapeObject
clone, 
getName, 
getRandom, 
getRandomSeed, 
randomInRange, 
randomInRange, 
randomIs, 
randomToLimit, 
reseed, 
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.

Parameters:
agent - the target agent.
Overrides:
setScape in class AscapeObject





getScape
public Scape getScape()

Returns the scape the agent will act within.

Overrides:
getScape in class AscapeObject





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.



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.



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.