jas.engine
Class AgentList

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractList<E>
          java.util.ArrayList
              jas.engine.AgentList

All Implemented Interfaces:

ISimEventListener, java.io.Serializable, java.lang.Cloneable, java.lang.Iterable, java.util.Collection, java.util.List, java.util.RandomAccess

public class AgentList
extends java.util.ArrayList
implements ISimEventListener

An array list with some useful features like shuffling, rotation and async message passing. It allows to call the performAction method of each agent into the list, using both serial and parallel execution modes. When asyncExecute method is invoked the same message is posted asynchronously to the list. The AgentList waits until every agent has terminated or a timeout time has been reached. It is useful to launch time-expensive routines on different machines on a network.

Title: JAS

Description: Java Agent-based Simulation library

Copyright (C) 2002 Michele Sonnessa

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

Author:

Michele Sonnessa

See Also:

Serialized Form

Field Summary

int	TIMEOUT The time out time for an asynchronous execution.

Constructor Summary

AgentList()
Default constructor.

AgentList(AgentList agentList)
Construct an agent list from another one.

AgentList(int initialCapacity)
Construct an agent list allocating an initialCapacity into ArrayList.

Method Summary

void	add(int index, java.lang.Object eventListener) Add an agent to the index of the collection.
boolean	add(java.lang.Object eventListener) Add an agent to the end of the collection.
boolean	addAll(java.util.Collection c) Unsupported method.
boolean	addAll(int index, java.util.Collection c) Unsupported method.
void	addSafe(java.lang.Object item)
void	appendSafe(java.lang.Object item)
void	asyncExecute(int actionType) Executes asynchronously the given action type for each agent in the list.
void	asyncJobExecuted() Notifies to the agent list that an asynchronous task has been terminated.
void	execute(int actionType) Executes the given action type for each agent in the list.
void	performAction(int actionType) Impements ISimEventListener interface.
boolean	removeSafe(java.lang.Object item)
void	rotate(int distance) Rotates the elements in the specified list by the specified distance.
void	shuffle() Randomly permutes the list using a default source of randomness.
void	swap(int firstIndex, int secondIndex) Swaps the elements at the specified positions.
AgentList	synchronizedList() Returns a synchronized (thread-safe) list backed by the specified list.

Methods inherited from class java.util.ArrayList

clear, clone, contains, ensureCapacity, get, indexOf, isEmpty, lastIndexOf, remove, remove, set, size, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals, hashCode, iterator, listIterator, listIterator, subList

Methods inherited from class java.util.AbstractCollection

containsAll, removeAll, retainAll, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

containsAll, equals, hashCode, iterator, listIterator, listIterator, removeAll, retainAll, subList

Field Detail

TIMEOUT

public int TIMEOUT

The time out time for an asynchronous execution.

Constructor Detail

AgentList

public AgentList()

Default constructor.

AgentList

public AgentList(AgentList agentList)

Construct an agent list from another one. It does not clone objects.

Parameters:

agentList - An agent list to copy.

AgentList

public AgentList(int initialCapacity)

Construct an agent list allocating an initialCapacity into ArrayList.

Parameters:

initialCapacity - The initial length of the internal array.

Method Detail

add

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

Add an agent to the index of the collection.

Specified by:

add in interface java.util.List

Overrides:

add in class java.util.ArrayList

Parameters:

eventListener - The object must implement the ISimEventListener interface.

index - The index at which the specified element is to be inserted.

add

public boolean add(java.lang.Object eventListener)

Add an agent to the end of the collection.

Specified by:

add in interface java.util.Collection

Specified by:

add in interface java.util.List

Overrides:

add in class java.util.ArrayList

Parameters:

eventListener - The object must implement the ISimEventListener interface.

addAll

public boolean addAll(java.util.Collection c)

Unsupported method.

Specified by:

addAll in interface java.util.Collection

Specified by:

addAll in interface java.util.List

Overrides:

addAll in class java.util.ArrayList

addAll

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

Unsupported method.

Specified by:

addAll in interface java.util.List

Overrides:

addAll in class java.util.ArrayList

addSafe

public void addSafe(java.lang.Object item)

appendSafe

public void appendSafe(java.lang.Object item)

asyncExecute

public void asyncExecute(int actionType)

Executes asynchronously the given action type for each agent in the list. The execution is done in parallel. All agents are activated without waiting for its answer. The asyncExecute method is locked until all agents in the list have terminated their execution.

Parameters:

actionType - The id of the action. See ISimEventListener for more details.

asyncJobExecuted

public void asyncJobExecuted()

Notifies to the agent list that an asynchronous task has been terminated.

execute

public void execute(int actionType)

Executes the given action type for each agent in the list. The execution is done serially. Only when an agent terminates execution, the subsequent can start.

Parameters:

actionType - The id of the action. See ISimEventListener for more details.

performAction

public void performAction(int actionType)

Impements ISimEventListener interface. This call is sent to each agent in the list. It is executed the execute(actionType) command.

Specified by:

performAction in interface ISimEventListener

Parameters:

actionType - The id of the action. See ISimEventListener for more details.

removeSafe

public boolean removeSafe(java.lang.Object item)

rotate

public void rotate(int distance)

Rotates the elements in the specified list by the specified distance. After calling this method, the element at index i will be the element previously at index (i - distance) mod list.size(), for all values of i between 0 and list.size()-1, inclusive. (This method has no effect on the size of the list.)

This method calls Collections.rotate. See JDK Collections API for more details.

Parameters:

distance - the distance to rotate the list. There are no constraints on this value; it may be zero, negative, or greater than list.size().

shuffle

public void shuffle()

Randomly permutes the list using a default source of randomness. All permutations occur with approximately equal likelihood.

The seed of random generator is synchronized with the simulation seed.

The hedge "approximately" is used in the foregoing description because default source of randomenss is only approximately an unbiased source of independently chosen bits. If it were a perfect source of randomly chosen bits, then the algorithm would choose permutations with perfect uniformity.

This implementation traverses the list backwards, from the last element up to the second, repeatedly swapping a randomly selected element into the "current position". Elements are randomly selected from the portion of the list that runs from the first element to the current position, inclusive.

This method runs in linear time. If the specified list does not implement the RandomAccess interface and is large, this implementation dumps the specified list into an array before shuffling it, and dumps the shuffled array back into the list. This avoids the quadratic behavior that would result from shuffling a "sequential access" list in place.

This method calls Collections.shuffle. See JDK Collections API for more details.

swap

public void swap(int firstIndex,
                 int secondIndex)

Swaps the elements at the specified positions. (If the specified positions are equal, invoking this method leaves the list unchanged.)

This method calls Collections.swap. See JDK Collections API for more details.

Parameters:

i - the index of one element to be swapped.

j - the index of the other element to be swapped.

Throws:

java.lang.IndexOutOfBoundsException - if either i or j is out of range (i < 0 || i >= list.size() || j < 0 || j >= list.size()).

synchronizedList

public AgentList synchronizedList()

Returns a synchronized (thread-safe) list backed by the specified list. In order to guarantee serial access, it is critical that all access to the backing list is accomplished through the returned list.

It is imperative that the user manually synchronize on the returned list when iterating over it:

  List list = thisList.synchronizedList();
      ...
  synchronized(list) {
      Iterator i = list.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Failure to follow this advice may result in non-deterministic behavior.

The returned list will be serializable if the specified list is serializable.

This method calls Collections.synchronizedList. See JDK Collections API for more details.

Returns:

a synchronized view of the specified list.