## org.ascape.model.space
Class SubCollection

    java.lang.Object
      org.ascape.model.space.CollectionSpace
          org.ascape.model.space.SubCollection

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, Space, SubSpace, RandomFunctions

Direct Known Subclasses:
  SubContinuous

    public abstract class SubCollection

extends CollectionSpace
implements SubSpace

A space collection that is part of another space collection. Any agents added to this collection will also be added to the super collection, and any agents removed from this collection will be removed from the super collection. Note that agents removed directly from the super collection will not be removed from this collection.

Since:
  2.0
Version:
  3.0
Author:
  Miles Parker
See Also:
  Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.ascape.model.space.CollectionSpace
`CollectionSpace.ClosestDataPoint, CollectionSpace.ConditionalIterator, CollectionSpace.CSIterator, CollectionSpace.CSMutableIterator, CollectionSpace.ListMutableRandomIterator, CollectionSpace.ListRandomIterator, CollectionSpace.MutableSubIterator, CollectionSpace.SubIterator`

Field Summary

Fields inherited from class org.ascape.model.space.CollectionSpace
`collection, ESTIMATED_MAXIMUM_SIZE, extent, geometry`

Constructor Summary
`SubCollection()` Constructs a sub-collection.
`SubCollection(CoordinateDiscrete extent)` Constructs a sub-collection.

Method Summary
`boolean` `add(java.lang.Object o, boolean isParent)` Adds the supplied object (agent) to this list at the specified location and to end of the super list.
`boolean` `addAll(java.util.Collection c)` Inserts all of the agents in the specified collection at the location specified in this list, and at the end of the super list.
`double` `calculateDistance(Coordinate origin, Coordinate target)` Returns the shortest distance between one agent and the other, in the context of the superscape.
`void` `clear()` Removes all agents from the space, and all members of this space from the super collection.
`Space` `getSuperSpace()` Returns the super collection for this sub collection, that is, the collection defined to contain a superset of this space's agents.
`void` `moveAway(Location origin, Coordinate target, double distance)` Moves an agent toward the specified agent in the context of the superscape.
`void` `moveToward(Location origin, Coordinate target, double distance)` Moves an agent toward the specified agent in the context of the superscape.
`void` `populate()` Populates the space and its super collection with clones of the prototype agent.
`boolean` `remove(java.lang.Object o)` Removes the supplied object (agent) from this collection and its superlist.
`boolean` `removeAll(java.util.Collection c)` Removes all of the agnets contained in the collection from this space collection and its super space collection.
`boolean` `retainAll(java.util.Collection c)` Retains only the elements in the space that are in the specified collection.
`void` `setSuperSpace(Space superSpace)` Sets the super collection for this sub collection, that is, the collection defined to contain a superset of this space's agents.

Methods inherited from class org.ascape.model.space.CollectionSpace

`add, calculateDistance, clone, conditionalIterator, conditionalIterator, construct, contains, containsAll, countWithin, createOrder, createSpatialConditional, deleteSweep, filter, find, findMaximum, findMaximum, findMaximumWithin, findMinimum, findMinimum, findMinimumWithin, findNearest, findNearest, findRandom, findRandom, findRandom, findRandom, findRandomCoordinate, findRandomWithin, findWithin, get, getContext, getExtent, getGeometry, getRandom, getSize, hasWithin, initialize, isDeleteSweepNeeded, isEmpty, isMutable, isPeriodic, iterator, iteratorCount, iteratorToList, newLocation, newLocation, randomInRange, randomInRange, randomIs, randomizeOrder, randomToLimit, safeIterator, safeIterator, safeIterators, safeRandomIterator, set, setContext, setExtent, setExtent, setGeometry, setPeriodic, setRandom, setSize, size, toArray, toArray, toList, withinIterator`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface java.util.Collection
`equals, hashCode`

Constructor Detail

### SubCollection

    public SubCollection()

  Constructs a sub-collection.

### SubCollection

    public SubCollection(CoordinateDiscrete extent)

  Constructs a sub-collection.

  Parameters:
    `extent` - a coordinate describing the size of this space

Method Detail

### populate

    public void populate()

  Populates the space and its super collection with clones of the prototype agent. First removes any currently existing members from the super collection to prevent orphans. Prototype agent should be set before calling this method. (By default, the prototpye agent is a Node.)

  Specified by:
    `populate` in interface `Space`
  Overrides:
    `populate` in class `CollectionSpace`

### add

    public boolean add(java.lang.Object o,
                       boolean isParent)

  Adds the supplied object (agent) to this list at the specified location and to end of the super list. The object is assumed to be an agent, though that behavior may be loosened at some point.

  Specified by:
    `add` in interface `Space`
  Overrides:
    `add` in class `CollectionSpace`
  Parameters:
    `isParent` - should this space be made the parent space of the agent?
    `o` - the o
  Returns:
    true, if add
  Throws:
    `java.lang.ClassCastException` - if the object is not an instance of agent

### remove

    public boolean remove(java.lang.Object o)

  Removes the supplied object (agent) from this collection and its superlist. If the agent is _not_ a member of this space, but is a member of the super space, it is not removed from the super space.

  Specified by:
    `remove` in interface `java.util.Collection`
  Overrides:
    `remove` in class `CollectionSpace`
  Parameters:
    `o` - the agent to be removed
  Returns:
    true if the agent was deleted, false otherwise

### addAll

    public boolean addAll(java.util.Collection c)

  Inserts all of the agents in the specified collection at the location specified in this list, and at the end of the super list. Assumes (but does not check) that all of the elements are instances of agent.

  Specified by:
    `addAll` in interface `java.util.Collection`
  Overrides:
    `addAll` in class `CollectionSpace`
  Parameters:
    `c` - collection whose agents are to be added to the space
  Returns:
    true if the space had new agents added

### removeAll

    public boolean removeAll(java.util.Collection c)

  Removes all of the agnets contained in the collection from this space collection and its super space collection. No attempt is made to cache the removal; the agents are all removed at once.

  Specified by:
    `removeAll` in interface `java.util.Collection`
  Overrides:
    `removeAll` in class `CollectionSpace`
  Parameters:
    `c` - collection whose agents are to be added to the space
  Returns:
    true if the space had agents (but not neccessarily all?) removed

### retainAll

    public boolean retainAll(java.util.Collection c)

  Retains only the elements in the space that are in the specified collection. Removes from the super space collection those agents that are in this collection but not in the specified reatined collection.

  Specified by:
    `retainAll` in interface `java.util.Collection`
  Overrides:
    `retainAll` in class `CollectionSpace`
  Parameters:
    `c` - collection whose agents are to be retained in the space
  Returns:
    true if this space had agents removed

### clear

    public void clear()

  Removes all agents from the space, and all members of this space from the super collection.

  Specified by:
    `clear` in interface `java.util.Collection`
  Overrides:
    `clear` in class `CollectionSpace`

### getSuperSpace

    public Space getSuperSpace()

  Returns the super collection for this sub collection, that is, the collection defined to contain a superset of this space's agents.

  Specified by:
    `getSuperSpace` in interface `SubSpace`
  Returns:
    superSpace the collection used as super set

### setSuperSpace

    public void setSuperSpace(Space superSpace)

  Sets the super collection for this sub collection, that is, the collection defined to contain a superset of this space's agents. If a superlist had allready been assigned to this collection, this collection's elements are _not_ removed from the previous super collection. Any agents allready members of this collection would be added to the new superlist, however.

  Specified by:
    `setSuperSpace` in interface `SubSpace`
  Parameters:
    `superSpace` - the collection to assign as super set

### moveToward

    public void moveToward(Location origin,
                           Coordinate target,
                           double distance)

  Moves an agent toward the specified agent in the context of the superscape.

  Specified by:
    `moveToward` in interface `Space`
  Overrides:
    `moveToward` in class `CollectionSpace`
  Parameters:
    `origin` - the agent moving
    `target` - the agent's target
    `distance` - the distance to move

### moveAway

    public void moveAway(Location origin,
                         Coordinate target,
                         double distance)

  Moves an agent toward the specified agent in the context of the superscape.

  Specified by:
    `moveAway` in interface `Space`
  Overrides:
    `moveAway` in class `CollectionSpace`
  Parameters:
    `origin` - the agent moving
    `target` - the agent's target
    `distance` - the distance to move

### calculateDistance

    public double calculateDistance(Coordinate origin,
                                    Coordinate target)

  Returns the shortest distance between one agent and the other, in the context of the superscape.

  Specified by:
    `calculateDistance` in interface `Space`
  Overrides:
    `calculateDistance` in class `CollectionSpace`
  Parameters:
    `origin` - the starting cell
    `target` - the ending cell
  Returns:
    the double