org.ascape.model
Class AscapeObject

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, HasName, RandomFunctions

Direct Known Subclasses:

Agent, Rule

public class AscapeObject
extends java.lang.Object
implements RandomFunctions, HasName, java.lang.Cloneable, java.io.Serializable

The cannonical class for most ascape model objects, including rules. Used to manage basic features, such as access to random stream. Every ascape object should 'belong' to some scape, but is not neccesarily a member of that scape.

Since:

1.0.1

Version:

2.0

Author:

Miles Parker

See Also:

Serialized Form

Field Summary

static int	ARBITRARY_SEED Symbol for random seed to be arbitrary (current time in milliseconds.)
protected java.lang.String	name The name of this object
protected Scape	scape The agent that this object belongs to.

Constructor Summary

AscapeObject()
Constructs an ascape object.

AscapeObject(java.lang.String name)
Constructs an ascape object.

Method Summary

java.lang.Object	clone() Clones this object.
java.util.ArrayList	diffDeep(java.lang.Object o) Does a deep comparison of this object with another, returning an array list containing a string description of the differences found.
static java.util.ArrayList	diffDeep(java.lang.Object o1, java.lang.Object o2) Does a deep comparison of two objects, returning an array list containing a string description of the differences found.
static java.util.ArrayList	diffDeepBFS(java.util.HashSet visitedObjects, java.util.LinkedList queue) Does a deep comparison of two objects, returning an array list containing a string description of the differences found.
static java.util.ArrayList	diffDeepDFS(java.lang.Object o1, java.lang.Object o2) Does a deep comparison of two objects, returning an array list containing a string description of the differences found.
protected static java.lang.String	diffDeepValidate(org.ascape.model.AscapeObject.SearchNode n) Helper method for both diffDeep mothods.
protected static java.lang.String	diffDeepVisit(org.ascape.model.AscapeObject.SearchNode n) Helper method for both diffDeep mothods.
static boolean	equalsDeep(java.util.HashSet visitedObjects, org.ascape.model.AscapeObject.SearchNode currentNode) Does a deep comparison of two objects, returning wether the two objects are deeply identical.
boolean	equalsDeep(java.lang.Object o) Does a deep compare of the two objects.
static boolean	equalsDeep(java.lang.Object o1, java.lang.Object o2) Does a deep comparison of two objects, returning wether the two objects are deeply identical.
static java.io.PrintStream	getComparisonStream() Return the stream used to capture the results of object deep comparison.
java.lang.String	getName() A name this object may be referred to by.
java.util.Random	getRandom() Gets the random number stream used by this object.
long	getRandomSeed() Returns the seed for the default random number seed.
Scape	getScape() Returns the scape that this object is primarily related to.
double	randomInRange(double low, double high) Generate a double uniformly distributed across some range.
int	randomInRange(int low, int high) Generate an integer uniformly distributed across some range.
boolean	randomIs() Returns a random boolean value.
int	randomToLimit(int limit) Generate an integer uniformly distributed across 0...limit - 1.
void	reseed() Resets the random number generator.
static void	setComparisonStream(java.io.PrintStream comparisonStream) Sets the stream used to capture the results of object deep comparison.
void	setName(java.lang.String name) Sets a name this object may be referred to by.
void	setRandom(java.util.Random newRandom) Sets the random number stream to be used by this object.
void	setRandomSeed(long seed) Sets the seed for the default random number seed.
void	setScape(Scape scape) Sets the scape that this object is primarily related to.
java.lang.String	toString() A string representing this object.

Methods inherited from class java.lang.Object

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

Field Detail

ARBITRARY_SEED

public static final int ARBITRARY_SEED

Symbol for random seed to be arbitrary (current time in milliseconds.)

See Also:

Constant Field Values

scape

protected Scape scape

The agent that this object belongs to. Note that this object is not neccesarily a member of the scape.

name

protected java.lang.String name

The name of this object

Constructor Detail

AscapeObject

public AscapeObject()

Constructs an ascape object.

AscapeObject

public AscapeObject(java.lang.String name)

Constructs an ascape object.

Parameters:

name - the name of this object

Method Detail

setScape

public void setScape(Scape scape)

Sets the scape that this object is primarily related to.

Parameters:

scape - the scape this agent is belongs to

getScape

public Scape getScape()

Returns the scape that this object is primarily related to.

getName

public java.lang.String getName()

A name this object may be referred to by.

Specified by:

getName in interface HasName

setName

public void setName(java.lang.String name)

Sets a name this object may be referred to by.

setRandom

public void setRandom(java.util.Random newRandom)

Sets the random number stream to be used by this object. For this base class, sets a static variable random that is available to all objects. May be overriden to set an instance random stream instead.

Specified by:

setRandom in interface RandomFunctions

Parameters:

newRandom - the new random number stream to use

See Also:

getRandom()

getRandom

public java.util.Random getRandom()

Gets the random number stream used by this object. For this base class, this is a static variable random available to all objects. If you want to provide scapes or agents with their own randoms, override this method and be sure to use it instead of simply accessing the random variable.

Specified by:

getRandom in interface RandomFunctions

getRandomSeed

public long getRandomSeed()

Returns the seed for the default random number seed. Will return actual seed (not the arbitrary seed symbol) if seed is set for arbitrary seed.

setRandomSeed

public void setRandomSeed(long seed)

Sets the seed for the default random number seed. Call or override to set the seed for any instance random streams. Set to ARBITRARY_SEED to have the system generate an arbitrary random seed (current time in milliseconds) at start.

Parameters:

seed - the random number seed to use

reseed

public void reseed()

Resets the random number generator. If a seed has been provided, returns the number generator to its orginal state, so that the last series of random numbers can be reproduced. If the random seed has not been set, sets the random number generator to some undetermined state (based on current system clock.)

randomInRange

public int randomInRange(int low,
                         int high)

Generate an integer uniformly distributed across some range.

Specified by:

randomInRange in interface RandomFunctions

Parameters:

low - the lowest number (inclusive) that the resulting int might be

high - the hignest number (inclusive) that the resulting int might be

Returns:

uniformly distributed pseudorandom int

randomInRange

public double randomInRange(double low,
                            double high)

Generate a double uniformly distributed across some range.

Specified by:

randomInRange in interface RandomFunctions

Parameters:

low - the lowest number (inclusive) that the resulting double might be

high - the hignest number (exclusive) that the resulting double might be

Returns:

uniformly distributed pseudorandom double

randomToLimit

public int randomToLimit(int limit)

Generate an integer uniformly distributed across 0...limit - 1.

Specified by:

randomToLimit in interface RandomFunctions

Parameters:

limit - the maximum limit (exclusive) of the resulting int

Returns:

uniformly distributed pseudorandom int

randomIs

public boolean randomIs()

Returns a random boolean value.

Specified by:

randomIs in interface RandomFunctions

diffDeepVisit

protected static java.lang.String diffDeepVisit(org.ascape.model.AscapeObject.SearchNode n)

Helper method for both diffDeep mothods. Checks for node equivalence. At this point, node is known to contain two primitive objects. Returns null if the nodes are equivalent, and the node's description if not.

Parameters:

n - the node in the object tree that is currently being explored

Returns:

an ArrayList enumerating any differences, containing Strings of the form "field.memberField{[index]}: {object 1 value}, {object 2 value}"

diffDeepValidate

protected static java.lang.String diffDeepValidate(org.ascape.model.AscapeObject.SearchNode n)

Helper method for both diffDeep mothods. Checks 'exterior' equivalence of the node pair. Do they share the sane null state, class, and or type? Returns null if objects are validated, a String describing the node (and the object differences) otherwise.

Parameters:

n - the node in the object tree that is currently being explored

Returns:

an ArrayList enumerating any differences, containing Strings of the form "field.memberField{[index]}: {object 1 value}, {object 2 value}"

diffDeepDFS

public static java.util.ArrayList diffDeepDFS(java.lang.Object o1,
                                              java.lang.Object o2)

Does a deep comparison of two objects, returning an array list containing a string description of the differences found.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

Returns:

an ArrayList enumerating any differences, containing Strings of the form "field.memberField{[index]}: {object 1 value}, {object 2 value}"

diffDeep

public static java.util.ArrayList diffDeep(java.lang.Object o1,
                                           java.lang.Object o2)

Does a deep comparison of two objects, returning an array list containing a string description of the differences found. This version does a breadth first search, so that objects are discovered at the lowest point in the object tree.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

Returns:

an ArrayList enumerating any differences, containing Strings of the form "field.memberField{[index]}: {object 1 value}, {object 2 value}"

diffDeepBFS

public static java.util.ArrayList diffDeepBFS(java.util.HashSet visitedObjects,
                                              java.util.LinkedList queue)

Does a deep comparison of two objects, returning an array list containing a string description of the differences found.

Parameters:

visitedObjects - the set of objects that have allready been tested

queue - the current search node queue

Returns:

an ArrayList enumerating any differences, containing Strings of the form "field.memberField{[index]}: {object 1 value}, {object 2 value}"

diffDeep

public java.util.ArrayList diffDeep(java.lang.Object o)

Does a deep comparison of this object with another, returning an array list containing a string description of the differences found.

Parameters:

o - the object to compare to

Returns:

an ArrayList enumerating any differences, containing Strings of the form "field.memberField{[index]}: {object 1 value}, {object 2 value}"

equalsDeep

public static boolean equalsDeep(java.lang.Object o1,
                                 java.lang.Object o2)

Does a deep comparison of two objects, returning wether the two objects are deeply identical.

Parameters:

o1 - the first object to compare

o2 - the second object to compare

Returns:

true if the objects are deeply identical, false otherwise

equalsDeep

public static boolean equalsDeep(java.util.HashSet visitedObjects,
                                 org.ascape.model.AscapeObject.SearchNode currentNode)

Does a deep comparison of two objects, returning wether the two objects are deeply identical.

Parameters:

visitedObjects - a string describing the parent members of the objects (may be empty)

currentNode - the node in the object tree that is currently being explored

Returns:

true if the objects are deeply identical, false otherwise

equalsDeep

public boolean equalsDeep(java.lang.Object o)

Does a deep compare of the two objects. To be equal, the deep internal state of two objects must be identical, but they do not have to share any of the same objects. e.g. for an object composed of other objects, those objects do not have to be the same object. However, they must be of the same class, and any primitive values must be identical. Warning: This equals method uses reflection and does a deep tour of the entire object's makeup; therefore, it can be very time-consuming. This method is primarily designed for testing, verification, and other circumstances where runtime performacne isn't critical. For simple agent comparison's, it is probably better to override this method and prvoide a hardcoded internal state comparison.

getComparisonStream

public static java.io.PrintStream getComparisonStream()

Return the stream used to capture the results of object deep comparison. If not null, the tests and results of equal and diff will be sent to the stream.

setComparisonStream

public static void setComparisonStream(java.io.PrintStream comparisonStream)

Sets the stream used to capture the results of object deep comparison. If not null, the tests and results of equal and diff will be sent to the stream.

clone

public java.lang.Object clone()

Clones this object. Typically should be overridden to create a copy that is deep with respect to its internal state (for mutables), shares parent and 'context' data with the original, and clears any positional or relational state that might create a resulting illegal state in a parent or peer. For example, a cloned cell with a memory vector would copy the memory vector, retain the original's scape, and clear its coordinate data (because it is usually not legal for two cells to exists at the same coordinate.) Does not throw CloneNotSupportedException, since all ascape objects should support it.

Overrides:

clone in class java.lang.Object

toString

public java.lang.String toString()

A string representing this object.

Overrides:

toString in class java.lang.Object