se.sics.tasim.sim
Class Simulation

java.lang.Object
  extended by se.sics.tasim.sim.Simulation

public abstract class Simulation
extends java.lang.Object


Field Summary
static java.lang.String COORDINATOR
           
static int COORDINATOR_INDEX
           
protected static int RECOVERY_AFTER_NEXT_TICK
           
protected static int RECOVERY_IMMEDIATELY
           
protected static int RECOVERY_NONE
           
 
Constructor Summary
protected Simulation(ConfigManager config)
           
 
Method Summary
protected  void addTimeListener(TimeListener listener)
           
 int agentIndex(java.lang.String name)
           
protected  void clearTimeListeners()
           
protected abstract  void completeStopSimulation()
          Notification when this simulation has been stopped.
protected  int createBuiltinAgents(java.lang.String base, int role)
          Creates agents with the specified names and registers them in this simulation.
protected  int createBuiltinAgents(java.lang.String base, int role, java.lang.Class baseClass)
           
protected  int createDummies(java.lang.String base, int role, int numberOfAgents)
           
protected  int createDummies(java.lang.String base, int role, int numberOfAgents, java.lang.String namePrefix)
           
protected  void createExternalAgent(java.lang.String name, int role, int participantID)
           
protected  void finalize()
           
protected  SimulationAgent getAgent(int participantID)
           
protected  SimulationAgent getAgent(java.lang.String name)
           
protected abstract  int getAgentRecoverMode(SimulationAgent agent)
          Called whenever an external agent has logged in and needs to recover its state.
protected  SimulationAgent[] getAgents()
           
protected  SimulationAgent[] getAgents(int role)
           
 ConfigManager getConfig()
           
 EventWriter getEventWriter()
           
protected  LogWriter getLogWriter()
           
 java.util.Random getRandom()
           
 long getServerTime()
           
 SimulationInfo getSimulationInfo()
           
 ThreadPool getSimulationThreadPool()
           
protected  TimeListener[] getTimeListeners()
           
protected  int getTimeUnitCount()
           
protected  java.lang.String getTimeUnitName()
           
protected  void invokeLater(java.lang.Runnable target)
          Causes target.run() to be executed with the simulation thread.
protected abstract  void messageReceived(Message message)
          Delivers a message to the coordinator (the simulation).
protected  void nextTimeUnitFinished(int timeUnit)
          Called when a new time unit has begun similar to time listeners but this method is guaranteed to be called after the time listeners.
protected  void nextTimeUnitStarted(int timeUnit)
          Called when entering a new time unit similar to time listeners but this method is guaranteed to be called before the time listeners.
protected abstract  void prepareStopSimulation()
          Notification when this simulation is preparing to stop.
protected abstract  void recoverAgent(SimulationAgent agent)
          Called whenever an external agent has logged in and needs to recover its state.
protected  SimulationAgent registerAgent(Agent agent, java.lang.String name, int role, int participantID)
          Registers the specified agent in this simulation and initializes it.
protected  void removeTimeListener(TimeListener listener)
           
protected  void requestStopSimulation()
           
protected  void sendMessage(Message message)
          Sends the specified message from the simulation coordinator to the agent specified as the receiver in the message.
protected  void sendMessage(java.lang.String receiver, Transportable content)
          Sends the specified message from the simulation coordinator to the agent specified as the receiver in the message.
protected  void sendToRole(int role, Transportable content)
           
protected abstract  void setupSimulation()
           
protected abstract  void startSimulation()
           
protected  void startTickTimer(long startServerTime, int millisPerTimeUnit)
           
protected abstract  boolean validateMessage(SimulationAgent receiver, Message message)
          Validates this message to ensure that it may be delivered to the agent.
protected abstract  boolean validateMessageToRole(int role, Transportable content)
          Validates this message from the coordinator to ensure that it may be broadcasted to all agents with the specified role.
protected abstract  boolean validateMessageToRole(SimulationAgent sender, int role, Transportable content)
          Validates this message to ensure that it may be broadcasted to all agents with the specified role.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COORDINATOR

public static final java.lang.String COORDINATOR
See Also:
Constant Field Values

COORDINATOR_INDEX

public static final int COORDINATOR_INDEX
See Also:
Constant Field Values

RECOVERY_NONE

protected static final int RECOVERY_NONE
See Also:
Constant Field Values

RECOVERY_IMMEDIATELY

protected static final int RECOVERY_IMMEDIATELY
See Also:
Constant Field Values

RECOVERY_AFTER_NEXT_TICK

protected static final int RECOVERY_AFTER_NEXT_TICK
See Also:
Constant Field Values
Constructor Detail

Simulation

protected Simulation(ConfigManager config)
Method Detail

requestStopSimulation

protected void requestStopSimulation()

getConfig

public ConfigManager getConfig()

getServerTime

public long getServerTime()

getSimulationInfo

public SimulationInfo getSimulationInfo()

getRandom

public java.util.Random getRandom()

getSimulationThreadPool

public ThreadPool getSimulationThreadPool()

getEventWriter

public EventWriter getEventWriter()

getLogWriter

protected LogWriter getLogWriter()

agentIndex

public int agentIndex(java.lang.String name)

getAgent

protected SimulationAgent getAgent(java.lang.String name)

getAgent

protected SimulationAgent getAgent(int participantID)

getAgents

protected SimulationAgent[] getAgents()

getAgents

protected SimulationAgent[] getAgents(int role)

registerAgent

protected SimulationAgent registerAgent(Agent agent,
                                        java.lang.String name,
                                        int role,
                                        int participantID)
Registers the specified agent in this simulation and initializes it. The agent will be registered with the specified name as address. If the agent is an registered agent it will be given the registered agent name instead of the specified name.

Parameters:
agent - the agent to be registered
name - the name of the agent
role - the role of the agent
participantID - the id of the agent or -1 if the agent is not a registered agent

invokeLater

protected void invokeLater(java.lang.Runnable target)
Causes target.run() to be executed with the simulation thread.


startTickTimer

protected void startTickTimer(long startServerTime,
                              int millisPerTimeUnit)

getTimeListeners

protected TimeListener[] getTimeListeners()

addTimeListener

protected void addTimeListener(TimeListener listener)

removeTimeListener

protected void removeTimeListener(TimeListener listener)

clearTimeListeners

protected void clearTimeListeners()

setupSimulation

protected abstract void setupSimulation()
                                 throws IllegalConfigurationException
Throws:
IllegalConfigurationException

getTimeUnitName

protected java.lang.String getTimeUnitName()

getTimeUnitCount

protected int getTimeUnitCount()

startSimulation

protected abstract void startSimulation()

prepareStopSimulation

protected abstract void prepareStopSimulation()
Notification when this simulation is preparing to stop. Called after the agents have been stopped but still can receive messages.


completeStopSimulation

protected abstract void completeStopSimulation()
Notification when this simulation has been stopped. Called after the agents shutdown.


nextTimeUnitStarted

protected void nextTimeUnitStarted(int timeUnit)
Called when entering a new time unit similar to time listeners but this method is guaranteed to be called before the time listeners.

Parameters:
timeUnit - the current time unit

nextTimeUnitFinished

protected void nextTimeUnitFinished(int timeUnit)
Called when a new time unit has begun similar to time listeners but this method is guaranteed to be called after the time listeners.

Parameters:
timeUnit - the current time unit

getAgentRecoverMode

protected abstract int getAgentRecoverMode(SimulationAgent agent)
Called whenever an external agent has logged in and needs to recover its state. The simulation should respond with the current recover mode (none, immediately, or after next time unit). This method should return RECOVERY_NONE if the simulation not yet have been started.

The simulation might recover the agent using this method if recovering the agent can be done using the agent communication thread. In that case RECOVERY_NONE should be returned. If any other recover mode is returned, the simulation will later be asked to recover the agent using the simulation thread by a call to recoverAgent. A common case might be when an agent reestablishing a lost connection to the server.

Parameters:
agent - the SimulationAgent to be recovered.
Returns:
the recovery mode for the agent
See Also:
RECOVERY_NONE, RECOVERY_IMMEDIATELY, RECOVERY_AFTER_NEXT_TICK, recoverAgent(SimulationAgent)

recoverAgent

protected abstract void recoverAgent(SimulationAgent agent)
Called whenever an external agent has logged in and needs to recover its state. The simulation should respond with the setup messages together with any other state information the agent needs to continue playing in the simulation (orders, inventory, etc). This method should not do anything if the simulation not yet have been started.

A common case might be when an agent reestablishing a lost connection to the server.

Parameters:
agent - the SimulationAgent to be recovered.

sendMessage

protected void sendMessage(java.lang.String receiver,
                           Transportable content)
Sends the specified message from the simulation coordinator to the agent specified as the receiver in the message.

Parameters:
receiver - the message to send

sendMessage

protected void sendMessage(Message message)
Sends the specified message from the simulation coordinator to the agent specified as the receiver in the message.

Parameters:
message - the message to send

sendToRole

protected void sendToRole(int role,
                          Transportable content)

validateMessage

protected abstract boolean validateMessage(SimulationAgent receiver,
                                           Message message)
Validates this message to ensure that it may be delivered to the agent. Messages to the coordinator and the administration are never validated.

Parameters:
receiver - the agent to deliver the message to
message - the message to validate
Returns:
true if the message should be delivered and false otherwise

validateMessageToRole

protected abstract boolean validateMessageToRole(SimulationAgent sender,
                                                 int role,
                                                 Transportable content)
Validates this message to ensure that it may be broadcasted to all agents with the specified role. This method can also be used to log messages

Parameters:
sender - the agent sender the message
role - the role of all receiving agents
content - the message content
Returns:
true if the message should be delivered and false otherwise

validateMessageToRole

protected abstract boolean validateMessageToRole(int role,
                                                 Transportable content)
Validates this message from the coordinator to ensure that it may be broadcasted to all agents with the specified role. This method can also be used to log messages

Parameters:
role - the role of all receiving agents
content - the message content
Returns:
true if the message should be delivered and false otherwise

messageReceived

protected abstract void messageReceived(Message message)
Delivers a message to the coordinator (the simulation). The coordinator must self validate the message.

Parameters:
message - the message

createExternalAgent

protected void createExternalAgent(java.lang.String name,
                                   int role,
                                   int participantID)

createBuiltinAgents

protected int createBuiltinAgents(java.lang.String base,
                                  int role)
                           throws IllegalConfigurationException
Creates agents with the specified names and registers them in this simulation. The class name for the agents are found by constructing a property as base + '.' + name + '.class' and take its value from the configuration manager.

Parameters:
base - the base of the agent property
role - the role of the agents
Returns:
the number of agents created
Throws:
IllegalConfigurationException - if an error occurs

createBuiltinAgents

protected int createBuiltinAgents(java.lang.String base,
                                  int role,
                                  java.lang.Class baseClass)
                           throws IllegalConfigurationException
Throws:
IllegalConfigurationException

createDummies

protected int createDummies(java.lang.String base,
                            int role,
                            int numberOfAgents)
                     throws IllegalConfigurationException
Throws:
IllegalConfigurationException

createDummies

protected int createDummies(java.lang.String base,
                            int role,
                            int numberOfAgents,
                            java.lang.String namePrefix)
                     throws IllegalConfigurationException
Throws:
IllegalConfigurationException

finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable


Copyright © 2007-2009 Association for Trading Agent Research. All Rights Reserved.