org.ascape.model.space
Class ListBase

java.lang.Object
  org.ascape.model.space.CollectionSpace
      org.ascape.model.space.Discrete
          org.ascape.model.space.Array
              org.ascape.model.space.ListBase

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, java.util.List, Space, RandomFunctions

Direct Known Subclasses:

Array1D, ListSpace

public abstract class ListBase
extends Array
implements java.util.List

A one-dimensional, fixed-size, collection of agents providing services described for space.

Since:

1.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.Array

CACHE_RESULTS

Fields inherited from class org.ascape.model.space.Discrete

performanceWarning

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

collection, ESTIMATED_MAXIMUM_SIZE, extent, geometry

Constructor Summary

ListBase()
Constructs a space array.

ListBase(CoordinateDiscrete extent)
Constructs a space array of provided extent, populated with clones of provided agent.

Method Summary

void	add(CoordinateDiscrete coordinate, java.lang.Object o) Adds the supplied object (assumed to be an agent) to this list.
void	add(int index, java.lang.Object o) Adds the supplied object (assumed to be an agent) to this list.
void	add(int index, java.lang.Object o, boolean isParent) Adds the supplied object (agent) to this list.
boolean	add(java.lang.Object o, boolean isParent) Adds the supplied object (agent) to this list.
boolean	addAll(int index, java.util.Collection c) Inserts all of the agents in the specified collection at the location specified.
double	calculateDistance(Coordinate origin, Coordinate target) Returns the shortest distance between one Location and another.
void	coordinateSweep() Walks through each agent, setting the agent's coordinates.
Node	findCellAway(Node origin, Node target) Returns the cell within immediate neighborhood furthest away from the requested cell.
Node	findCellToward(Node origin, Node target) Returns the next cell within immediate neighborhood toward the requested cell.
Node	findFirstMatchInRank(Coordinate origin, Conditional condition, int rank) Returns a random element in the supplied rank that matches the supplied condition, null if no matches.
int	findNearestMatchRank(Coordinate origin, Conditional condition, boolean includeOrigin) Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches.
int	findNearestMatchRank(Coordinate origin, Conditional condition, boolean includeOrigin, double maximumDistance) Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches.
Location	findRandomMatchInRank(Coordinate origin, Conditional condition, int rank) Returns a random element in the supplied rank that matches the supplied condition, null if no matches.
java.util.List	findWithinImpl(Coordinate origin, boolean includeSelf, double distance) Returns cells that are near the provided cell.
Node	get(CoordinateDiscrete coordinate) Returns the agents at the specified index.
java.lang.Object	get(int index) Returns the agents at the specified index.
int	indexOf(java.lang.Object o) Returns the index in this list of the first occurrence of the agent.
boolean	isCoordinateSweepNeeded() Is a coordinate location sweep needed for this space? Intended for internal purposes.
int	lastIndexOf(java.lang.Object o) Returns the index in this list of the last occurrence of the agent.
java.util.ListIterator	listIterator() Returns a list iterator across all agents in this space.
java.util.ListIterator	listIterator(int index) Returns a list iterator across all agents in this space, beginning at the specified index.
void	populate() Populates the space with clones of the prototype agent.
java.lang.Object	remove(CoordinateDiscrete coordinate) Removes the agent at the specified coordinate from this list.
java.lang.Object	remove(int index) Removes the agent at the specified position from this list.
boolean	remove(java.lang.Object o) Removes the supplied object (agent) from this list.
Node	set(int index, Location o, boolean isParent) Sets the agent at the specified coordinate to the supplied agent.
java.lang.Object	set(int index, java.lang.Object o) Sets the agent at the specified coordinate to the supplied agent.
void	setGeometry(Geometry geometry) Sets the geometry of this space.
java.util.List	subList(int fromIndex, int toIndex) Returns a view of a sublist of this list between the specified indices.

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

findNearest, findWithin, replace, swap

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

bfsWithinIterator, calculateDistance, calculateNeighbors, findAvailable, findAvailable, findCellAwayBFS, findCellTowardBFS, findNearestAvailable, findNearestBFS, findNeighbors, findOccupants, findOccupants, findRandomAvailable, findRandomAvailable, findRandomAvailable, findRandomAvailableNeighbor, findRandomNeighbor, findRandomNeighbor, findRandomUnoccupiedCell, findRandomUnoccupiedCell, findWithinDefault, getCells, getCellsNearDefault, getDistance, getMaximumRank, getSize

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

add, addAll, calculateDistance, clear, clone, conditionalIterator, conditionalIterator, construct, contains, containsAll, countWithin, createOrder, createSpatialConditional, deleteSweep, filter, find, findMaximum, findMaximum, findMaximumWithin, findMinimum, findMinimum, findMinimumWithin, findNearest, findRandom, findRandom, findRandom, findRandom, findRandomCoordinate, findRandomWithin, get, getContext, getExtent, getGeometry, getRandom, hasWithin, initialize, isDeleteSweepNeeded, isEmpty, isMutable, isPeriodic, iterator, iteratorCount, iteratorToList, moveAway, moveToward, newLocation, newLocation, randomInRange, randomInRange, randomIs, randomizeOrder, randomToLimit, removeAll, retainAll, safeIterator, safeIterator, safeIterators, safeRandomIterator, set, setContext, setExtent, setExtent, 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.List

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, removeAll, retainAll, size, toArray, toArray

Constructor Detail

ListBase

public ListBase()

Constructs a space array.

ListBase

public ListBase(CoordinateDiscrete extent)

Constructs a space array of provided extent, populated with clones of provided agent.

Parameters:

extent - a coordinate describing the size of this space

Method Detail

populate

public void populate()

Populates the space with clones of the prototype agent. Prototype agent should be set before calling this method.

Specified by:

populate in interface Space

Overrides:

populate in class CollectionSpace

add

public void add(int index,
                java.lang.Object o)

Adds the supplied object (assumed to be an agent) to this list.

Specified by:

add in interface java.util.List

Parameters:

index - location to insert the new agent

o - the agent to add

add

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

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

Parameters:

index - location to insert the new agent

o - the agent to add

isParent - should this space be made the parent space of the agent?

Throws:

java.lang.ClassCastException - if the object is not an instance of agent

add

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

Adds the supplied object (agent) to this 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:

o - the agent to add

isParent - should this space be made the parent space of the agent?

Returns:

true, if add

Throws:

java.lang.ClassCastException - if the object is not an instance of agent

add

public void add(CoordinateDiscrete coordinate,
                java.lang.Object o)

Adds the supplied object (assumed to be an agent) to this list.

Parameters:

coordinate - the coordinate to insert the new agent at

o - the agent to add

addAll

public boolean addAll(int index,
                      java.util.Collection c)

Inserts all of the agents in the specified collection at the location specified. Assumes (but does not check) that all of the elements are instances of agent.

Specified by:

addAll in interface java.util.List

Parameters:

index - the location at which to place the agents

c - collection whose agents are to be added to the space

Returns:

true if the space had new agents added

remove

public java.lang.Object remove(CoordinateDiscrete coordinate)

Removes the agent at the specified coordinate from this list.

Parameters:

coordinate - coordinate of the agent to delete

Returns:

the agent removed

remove

public java.lang.Object remove(int index)

Removes the agent at the specified position from this list.

Specified by:

remove in interface java.util.List

Parameters:

index - location of the agent to delete

Returns:

the agent removed

remove

public boolean remove(java.lang.Object o)

Removes the supplied object (agent) from this list.

Specified by:

remove in interface java.util.Collection

Specified by:

remove in interface java.util.List

Overrides:

remove in class CollectionSpace

Parameters:

o - the agent to be removed

Returns:

true if the agent was deleted, false otherwise

set

public java.lang.Object set(int index,
                            java.lang.Object o)

Sets the agent at the specified coordinate to the supplied agent. The object is expected to be an agent, though this requirement may be loosened at some point.

Specified by:

set in interface java.util.List

Parameters:

index - the lcoation to add the agent at

o - the agent to add

Returns:

the agent (if any) replaced at the location

set

public Node set(int index,
                Location o,
                boolean isParent)

Sets the agent at the specified coordinate to the supplied agent. The object is expected to be an agent, though this requirement may be loosened at some point.

Parameters:

index - the location to add the agent at

o - the agent to add

isParent - should this space be made the parent space of the agent?

Returns:

the node

setGeometry

public void setGeometry(Geometry geometry)

Sets the geometry of this space. Must of course be one-dimensional.

Overrides:

setGeometry in class CollectionSpace

Parameters:

geometry - the basic geometry of this space

indexOf

public int indexOf(java.lang.Object o)

Returns the index in this list of the first occurrence of the agent.

Specified by:

indexOf in interface java.util.List

Parameters:

o - the agent to search for.

Returns:

the index in this list of the first matching agent

lastIndexOf

public int lastIndexOf(java.lang.Object o)

Returns the index in this list of the last occurrence of the agent. (Obviously, this will typically be the same as indexOf, as agents do not typically appear in the same space twice.)

Specified by:

lastIndexOf in interface java.util.List

Parameters:

o - the agent to search for.

Returns:

the index in this list of the first matching agent

calculateDistance

public double calculateDistance(Coordinate origin,
                                Coordinate target)

Description copied from class: CollectionSpace

Returns the shortest distance between one Location and another. Warning: this default method only returns a coordinate specific distance. It uses no information about the context context; for example wether it is a periodic (wrapping) space or not. Therefore, if you implement your own versions of CollectionSpace, ensure that you have properly implemented a version of this method. (All Ascape spaces properly overide this method.)

Specified by:

calculateDistance in interface Space

Overrides:

calculateDistance in class Discrete

Parameters:

origin - one Location

target - another Location

Returns:

the double

findWithinImpl

public java.util.List findWithinImpl(Coordinate origin,
                                     boolean includeSelf,
                                     double distance)

Returns cells that are near the provided cell. Need to fix for non-periodic space!

Specified by:

findWithinImpl in class Array

Parameters:

origin - the coordinate to find cells near

distance - the distance to form centralCells to return cells

includeSelf - should supplied agent be included in the return set

Returns:

the list

findCellToward

public Node findCellToward(Node origin,
                           Node target)

Returns the next cell within immediate neighborhood toward the requested cell.

Specified by:

findCellToward in class Discrete

Parameters:

origin - the current cell

target - the cell that we are moving toward

Returns:

the node

findCellAway

public Node findCellAway(Node origin,
                         Node target)

Returns the cell within immediate neighborhood furthest away from the requested cell.

Specified by:

findCellAway in class Discrete

Parameters:

origin - the current cell

target - the cell that we are moving toward

Returns:

the node

findNearestMatchRank

public int findNearestMatchRank(Coordinate origin,
                                Conditional condition,
                                boolean includeOrigin)

Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches.

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

includeOrigin - should supplied agent (rank 0) be included in the search

Returns:

the int

findNearestMatchRank

public int findNearestMatchRank(Coordinate origin,
                                Conditional condition,
                                boolean includeOrigin,
                                double maximumDistance)

Returns the nearest rank that includes a cell which matches the supplied condition, -1 if no matches. Special Note: uses euclidian, _not_ geometry specific distance; this will be fixed soon.

Specified by:

findNearestMatchRank in class Array

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

includeOrigin - should supplied agent (rank 0) be included in the search

maximumDistance - the maximum distance to search within

Returns:

the int

findFirstMatchInRank

public Node findFirstMatchInRank(Coordinate origin,
                                 Conditional condition,
                                 int rank)

Returns a random element in the supplied rank that matches the supplied condition, null if no matches. Special Note: uses euclidian, _not_ geometry specific distance; this will be fixed soon.

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

rank - the rank to return match in

Returns:

the node

findRandomMatchInRank

public Location findRandomMatchInRank(Coordinate origin,
                                      Conditional condition,
                                      int rank)

Returns a random element in the supplied rank that matches the supplied condition, null if no matches. Special Note: uses euclidian, _not_ geometry specific distance; this will be fixed soon.

Specified by:

findRandomMatchInRank in class Array

Parameters:

origin - the agent to find cells near

condition - the condition that found cell must meet

rank - the rank to return match in

Returns:

the location

listIterator

public java.util.ListIterator listIterator()

Returns a list iterator across all agents in this space. The notes for iterator apply equally to the list iterators.

Specified by:

listIterator in interface java.util.List

Returns:

an iterator over the agents in space order

listIterator

public java.util.ListIterator listIterator(int index)

Returns a list iterator across all agents in this space, beginning at the specified index. The notes for iterator apply equally to the list iterators.

Specified by:

listIterator in interface java.util.List

Parameters:

index - index of first agent to be returned

Returns:

an iterator over the agents in space order

subList

public java.util.List subList(int fromIndex,
                              int toIndex)

Returns a view of a sublist of this list between the specified indices. See important Java List comments.

Specified by:

subList in interface java.util.List

Parameters:

fromIndex - the low index (inclusive)

toIndex - the high index (exclusive)

Returns:

a view of the specified range within this list.

Throws:

java.lang.IndexOutOfBoundsException - for an illegal endpoint index value @ see java.util.List

coordinateSweep

public void coordinateSweep()

Walks through each agent, setting the agent's coordinates. Warning -- should only be called on space's of which all agents have the space as a primary space.

isCoordinateSweepNeeded

public boolean isCoordinateSweepNeeded()

Is a coordinate location sweep needed for this space? Intended for internal purposes.

Returns:

true, if is coordinate sweep needed

get

public java.lang.Object get(int index)

Returns the agents at the specified index.

Specified by:

get in interface java.util.List

Parameters:

index - index of the agent to return.

Returns:

the agent at the specified place in the space

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range

get

public Node get(CoordinateDiscrete coordinate)

Returns the agents at the specified index.

Parameters:

coordinate - location of the agent to return.

Returns:

the agent at the specified place in the space

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range