## 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
`static java.lang.Object` `PLATFORM_DEFAULT_COLOR` Note, this color must be set from every target platform, and the setting class must load before the model is displayed.
`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

### PLATFORM_DEFAULT_COLOR

    public static java.lang.Object PLATFORM_DEFAULT_COLOR

  Note, this color must be set from every target platform, and the setting class must load before the model is displayed.

### 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`