Agent (fjage 1.12.3 API)

java.lang.Object
- org.arl.fjage.Agent

All Implemented Interfaces:: java.lang.Runnable, Messenger, TimestampProvider

Direct Known Subclasses:: ShellAgent

public class Agent
extends java.lang.Object
implements java.lang.Runnable, TimestampProvider, Messenger

Base class to be extended by all agents. An agent must be added to a container in order to run. An agent usually overrides the init() and shutdown() methods to provide the appropriate behavior.

A simple example agent is shown below:

 import org.arl.fjage.*;

 public class MyAgent extends Agent {

    @Override
   public void init() {
     log.info("MyAgent is starting");
     add(new MessageBehavior() {
        @Override
       public void onReceive(Message msg) {
         log.info("Got a message!");
         // do things with the message
       }
     });
     // add other behaviors
   }

 }

Field Summary

Fields
Modifier and Type	Field and Description
`protected static java.util.logging.Level`	`ALL`
`static long`	`BLOCKING` Represents a blocking timeout of infinite time.
`protected static java.util.logging.Level`	`FINE`
`protected static java.util.logging.Level`	`FINER`
`protected static java.util.logging.Level`	`FINEST`
`protected boolean`	`ignoreExceptions`
`protected static java.util.logging.Level`	`INFO`
`protected java.util.logging.Logger`	`log` Logger for the agent to log messages to.
`static long`	`NON_BLOCKING` Represents a non-blocking timeout of 0 seconds.
`protected static java.util.logging.Level`	`OFF`
`protected static java.util.logging.Level`	`SEVERE`
`protected java.lang.Thread`	`thread`
`protected long`	`tid`
`protected static java.util.logging.Level`	`WARNING`

Constructor Summary

Constructors
Constructor and Description

Agent()

Constructors
Constructor and Description
`Agent()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Behavior`	`add(Behavior b)` Adds a behavior to the agent.
`AgentID`	`agent(java.lang.String name)` Convenience method to create agent id for the named agent.
`AgentID`	`agentForService(java.lang.Enum<?> service)` Finds an agent that provides a named service.
`AgentID`	`agentForService(java.lang.String service)` Finds an agent that provides a named service.
`AgentID[]`	`agentsForService(java.lang.Enum<?> service)` Finds all agents that provides a named service.
`AgentID[]`	`agentsForService(java.lang.String service)` Finds all agents that provides a named service.
`protected void`	`block()` Blocks the agent until its woken up by a message or a call to the `wake()` method.
`protected void`	`block(long millis)` Blocks the agent until its woken up by a message or a call to the `wake()` method or until timeout, whichever occurs earlier.
`<T extends java.io.Serializable> T`	`clone(T obj)` Deep clones an object.
`long`	`currentTimeMillis()` Gets the current platform time in milliseconds.
`protected void`	`delay(long millis)` Blocks the agent for a specified period.
`boolean`	`deregister(java.lang.Enum<?> service)` De-registers the agent from the directory service as a provider of a named service.
`boolean`	`deregister(java.lang.String service)` De-registers the agent from the directory service as a provider of a named service.
`protected void`	`die(java.lang.Throwable ex)` Called by the container if the agent terminates abnormally.
`AgentID`	`getAgentID()` Gets the agent id.
`Container`	`getContainer()` Gets the container hosting the agent.
`java.lang.String`	`getName()` Gets the name of the agent.
`Platform`	`getPlatform()` Gets the platform hosting the agent.
`AgentState`	`getState()` Gets the state of the agent.
`Store`	`getStore()` Gets a persistent store for the agent.
`java.lang.String`	`getType()` Gets class name of agent.
`protected boolean`	`getYieldDuringReceive()` Checks if messages will be processed during a blocking receive().
`protected void`	`init()` Called by the container when the agent is started.
`long`	`nanoTime()` Gets the current platform time in nanoseconds.
`void`	`platformSend(Message m)` Sends a message to the recipient indicated in the message on all containers running on the current platform.
`RequestSender`	`prepareRequest(Message request)` Prepares a request to be sent.
`void`	`println(java.lang.Object msg)` Logs a message at an INFO level.
`Message`	`receive()` Returns a message received by the gateway.
`Message`	`receive(java.lang.Class<?> cls)` Returns a message of a given class received by the gateway.
`Message`	`receive(java.lang.Class<?> cls, long timeout)` Returns a message of a given class received by the gateway.
`Message`	`receive(long timeout)` Returns a message received by the agent.
`Message`	`receive(Message m)` Returns a response message received by the gateway.
`Message`	`receive(MessageFilter filter)` Returns a message received by the gateway and matching the given filter.
`Message`	`receive(MessageFilter filter, long timeout)` Returns a message received by the gateway and matching the given filter.
`Message`	`receive(Message m, long timeout)` Returns a response message received by the gateway.
`boolean`	`register(java.lang.Enum<?> service)` Registers the agent with the directory service as a provider of a named service.
`boolean`	`register(java.lang.String service)` Registers the agent with the directory service as a provider of a named service.
`Message`	`request(Message msg)` Sends a request and waits for a response.
`Message`	`request(Message msg, long timeout)` Sends a request and waits for a response.
`void`	`run()` Lifecycle of the agent.
`boolean`	`send(Message m)` Sends a message to the recipient indicated in the message.
`void`	`setLogLevel(java.util.logging.Level level)` Changes the logging level for the agent.
`void`	`setQueueSize(int size)` Sets the maximum length of the incoming message queue for the agent.
`protected void`	`setYieldDuringReceive(boolean b)` Enables/disables processing of messages during a blocking receive().
`protected void`	`shutdown()` Called by the container when the agent is terminated.
`void`	`stop()` Requests an agent to terminate.
`boolean`	`subscribe(AgentID topic)` Subscribes the agent to receive all messages sent to the given topic.
`AgentID`	`topic()` Returns an object representing the notification topic for this agent.
`AgentID`	`topic(AgentID agent)` Returns an object representing the notification topic for an agent.
`AgentID`	`topic(AgentID agent, java.lang.Enum<?> topic)` Returns an object representing a named notification topic for an agent.
`AgentID`	`topic(AgentID agent, java.lang.String topic)` Returns an object representing a named notification topic for an agent.
`AgentID`	`topic(java.lang.Enum<?> topic)` Returns an object representing the named topic.
`AgentID`	`topic(java.lang.String topic)` Returns an object representing the named topic.
`java.lang.String`	`toString()` Gets a string representation of the agent.
`boolean`	`unsubscribe(AgentID topic)` Unsubscribes the agent from a given topic.
`void`	`wake()` Wakes up the agent if it was blocked using `block()`.

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

- Field Detail
  - NON_BLOCKING
```
public static final long NON_BLOCKING
```
    Represents a non-blocking timeout of 0 seconds. Can be used with all Agent methods that take a timeout parameter.
    
    See Also:
    
    Constant Field Values
  - BLOCKING
```
public static final long BLOCKING
```
    Represents a blocking timeout of infinite time. Can be used with all Agent methods that take a timeout parameter.
    
    See Also:
    
    Constant Field Values
  - ALL
```
protected static final java.util.logging.Level ALL
```
  - FINEST
```
protected static final java.util.logging.Level FINEST
```
  - FINER
```
protected static final java.util.logging.Level FINER
```
  - FINE
```
protected static final java.util.logging.Level FINE
```
  - INFO
```
protected static final java.util.logging.Level INFO
```
  - WARNING
```
protected static final java.util.logging.Level WARNING
```
  - SEVERE
```
protected static final java.util.logging.Level SEVERE
```
  - OFF
```
protected static final java.util.logging.Level OFF
```
  - tid
```
protected long tid
```
  - thread
```
protected java.lang.Thread thread
```
  - ignoreExceptions
```
protected boolean ignoreExceptions
```
  - log
```
protected java.util.logging.Logger log
```
    Logger for the agent to log messages to.
- Constructor Detail
  - Agent
```
public Agent()
```
- Method Detail
  - init
```
protected void init()
```
    Called by the container when the agent is started. This method is usually overridden by a class implementing an agent to initialize the agent and its behaviors.
  - shutdown
```
protected void shutdown()
```
    Called by the container when the agent is terminated. This method may optionally be overridden to provide a clean up before termination.
  - die
```
protected void die(java.lang.Throwable ex)
```
    Called by the container if the agent terminates abnormally. This method may be optionally overridden to provide special handling of malfunctioning agents. This method is called before the shutdown() method is called to terminate the agent. The behaviors of the agent are no longer active once this method is called.
    
    Parameters:
    
    ex - exception that caused the agent to die.
  - getAgentID
```
public AgentID getAgentID()
```
    Gets the agent id.
    
    Returns:
    
    the agent id for this agent.
  - getName
```
public java.lang.String getName()
```
    Gets the name of the agent.
    
    Returns:
    
    the name of the agent.
  - getType
```
public java.lang.String getType()
```
    Gets class name of agent.
    
    Returns:
    
    qualified class name
  - setLogLevel
```
public void setLogLevel(java.util.logging.Level level)
```
    Changes the logging level for the agent.
    
    Parameters:
    
    level - log level
    
    See Also:
    
    Level
  - block
```
protected void block()
```
    Blocks the agent until its woken up by a message or a call to the wake() method.
  - block
```
protected void block(long millis)
```
    Blocks the agent until its woken up by a message or a call to the wake() method or until timeout, whichever occurs earlier.
    
    Parameters:
    
    millis - timeout in milliseconds
  - delay
```
protected void delay(long millis)
```
    Blocks the agent for a specified period. This method should be used in preference to Thread.sleep(long) as this method provides measures correct delay time for the hosting platform, be it a real-time or a simulated discrete-time platform.
    
    Parameters:
    
    millis - period to delay in milliseconds.
  - wake
```
public void wake()
```
    Wakes up the agent if it was blocked using block().
  - stop
```
public void stop()
```
    Requests an agent to terminate.
  - add
```
public Behavior add(Behavior b)
```
    Adds a behavior to the agent. The Behavior.onStart() method of the behavior is immediately called once its added to the agent.
    
    Parameters:
    
    b - behavior to be added.
    
    Returns:
    
    the behavior (same as input b)
  - getState
```
public AgentState getState()
```
    Gets the state of the agent.
    
    Returns:
    
    the state of the agent.
  - getPlatform
```
public Platform getPlatform()
```
    Gets the platform hosting the agent.
    
    Returns:
    
    the platform hosting the agent, null if the agent is not bound to a container yet.
  - getContainer
```
public Container getContainer()
```
    Gets the container hosting the agent.
    
    Returns:
    
    the container hosting the agent, null if the agent is not bound to a container yet.
  - currentTimeMillis
```
public long currentTimeMillis()
```
    Gets the current platform time in milliseconds. This method should be used by the agent to get the current time in preference to System.currentTimeMillis() as this method returns the real time or the simulated discrete time depending on the platform that the agent is running on.
    
    Specified by:
    
    currentTimeMillis in interface TimestampProvider
    
    Returns:
    
    current platform time in milliseconds.
  - nanoTime
```
public long nanoTime()
```
    Gets the current platform time in nanoseconds. This method should be used by the agent to get the current time in preference to System.nanoTime() as this method returns the real time or the simulated discrete time depending on the platform that the agent is running on.
    
    Specified by:
    
    nanoTime in interface TimestampProvider
    
    Returns:
    
    current platform time in nanoseconds.
  - agent
```
public AgentID agent(java.lang.String name)
```
    Convenience method to create agent id for the named agent.
    
    Returns:
    
    agent id for the named agent.
  - topic
```
public AgentID topic(java.lang.String topic)
```
    Returns an object representing the named topic.
    
    Parameters:
    
    topic - name of the topic.
    
    Returns:
    
    object representing the topic.
  - topic
```
public AgentID topic(java.lang.Enum<?> topic)
```
    Returns an object representing the named topic.
    
    Parameters:
    
    topic - name of the topic.
    
    Returns:
    
    object representing the topic.
  - topic
```
public AgentID topic(AgentID agent)
```
    Returns an object representing the notification topic for an agent.
    
    Parameters:
    
    agent - agent to get notification topic for.
    
    Returns:
    
    object representing the topic.
  - topic
```
public AgentID topic(AgentID agent,
                     java.lang.String topic)
```
    Returns an object representing a named notification topic for an agent.
    
    Parameters:
    
    agent - agent to get notification topic for.
    
    topic - name for the notification topic.
    
    Returns:
    
    object representing the topic.
  - topic
```
public AgentID topic(AgentID agent,
                     java.lang.Enum<?> topic)
```
    Returns an object representing a named notification topic for an agent.
    
    Parameters:
    
    agent - agent to get notification topic for.
    
    topic - name for the notification topic.
    
    Returns:
    
    object representing the topic.
  - topic
```
public AgentID topic()
```
    Returns an object representing the notification topic for this agent.
    
    Returns:
    
    object representing the topic.
  - send
```
public boolean send(Message m)
```
    Description copied from interface: Messenger
    
    Sends a message to the recipient indicated in the message. The recipient may be either an agent or a topic.
    
    Specified by:
    
    send in interface Messenger
    
    Parameters:
    
    m - message to be sent.
    
    Returns:
    
    true if message accepted for delivery, false on failure.
  - prepareRequest
```
public RequestSender prepareRequest(Message request)
```
    Prepares a request to be sent.
    
    Parameters:
    
    request - Request message.
    
    Returns:
    
    Request sender.
  - platformSend
```
public void platformSend(Message m)
```
    Sends a message to the recipient indicated in the message on all containers running on the current platform. The recipient may be another agent or a topic. This method is useful in simulations where multiple containers with the same agents run on the same platform.
    
    Parameters:
    
    m - message to be sent.
  - setYieldDuringReceive
```
protected void setYieldDuringReceive(boolean b)
```
    Enables/disables processing of messages during a blocking receive(). Experimental implementation. Disabled by default, except in the shell agent.
    
    Parameters:
    
    b - true to process messages while waiting, false to disable processing.
  - getYieldDuringReceive
```
protected boolean getYieldDuringReceive()
```
    Checks if messages will be processed during a blocking receive().
    
    See Also:
    
    setYieldDuringReceive(boolean)
  - receive
```
public Message receive(MessageFilter filter,
                       long timeout)
```
    Description copied from interface: Messenger
    
    Returns a message received by the gateway and matching the given filter. This method blocks until timeout if no message available.
    
    Specified by:
    
    receive in interface Messenger
    
    Parameters:
    
    filter - message filter.
    
    timeout - timeout in milliseconds.
    
    Returns:
    
    received message matching the filter, null on timeout.
  - receive
```
public Message receive(MessageFilter filter)
```
    Description copied from interface: Messenger
    
    Returns a message received by the gateway and matching the given filter. This method is non-blocking.
    
    Specified by:
    
    receive in interface Messenger
    
    Parameters:
    
    filter - message filter.
    
    Returns:
    
    received message matching the filter, null on timeout.
  - receive
```
public Message receive()
```
    Description copied from interface: Messenger
    
    Returns a message received by the gateway. This method is non-blocking.
    
    Specified by:
    
    receive in interface Messenger
    
    Returns:
    
    received message, null if none available.
  - receive
```
public Message receive(long timeout)
```
    Description copied from interface: Messenger
    
    Returns a message received by the agent. This method blocks until timeout if no message available.
    
    Specified by:
    
    receive in interface Messenger
    
    Parameters:
    
    timeout - timeout in milliseconds.
    
    Returns:
    
    received message, null on timeout.
  - receive
```
public Message receive(java.lang.Class<?> cls)
```
    Description copied from interface: Messenger
    
    Returns a message of a given class received by the gateway. This method is non-blocking.
    
    Specified by:
    
    receive in interface Messenger
    
    Parameters:
    
    cls - the class of the message of interest.
    
    Returns:
    
    received message of the given class, null if none available.
  - receive
```
public Message receive(java.lang.Class<?> cls,
                       long timeout)
```
    Description copied from interface: Messenger
    
    Returns a message of a given class received by the gateway. This method blocks until timeout if no message available.
    
    Specified by:
    
    receive in interface Messenger
    
    Parameters:
    
    cls - the class of the message of interest.
    
    timeout - timeout in milliseconds.
    
    Returns:
    
    received message of the given class, null on timeout.
  - receive
```
public Message receive(Message m)
```
    Description copied from interface: Messenger
    
    Returns a response message received by the gateway. This method is non-blocking.
    
    Specified by:
    
    receive in interface Messenger
    
    Parameters:
    
    m - original message to which a response is expected.
    
    Returns:
    
    received response message, null if none available.
  - receive
```
public Message receive(Message m,
                       long timeout)
```
    Description copied from interface: Messenger
    
    Returns a response message received by the gateway. This method blocks until timeout if no message available.
    
    Specified by:
    
    receive in interface Messenger
    
    Parameters:
    
    m - original message to which a response is expected.
    
    timeout - timeout in milliseconds.
    
    Returns:
    
    received response message, null on timeout.
  - request
```
public Message request(Message msg,
                       long timeout)
```
    Description copied from interface: Messenger
    
    Sends a request and waits for a response. This method blocks until timeout if no response is received.
    
    Specified by:
    
    request in interface Messenger
    
    Parameters:
    
    msg - message to send.
    
    timeout - timeout in milliseconds.
    
    Returns:
    
    received response message, null on timeout.
  - request
```
public Message request(Message msg)
```
    Sends a request and waits for a response. This method blocks until a default timeout of 1 second, if no response is received.
    
    Specified by:
    
    request in interface Messenger
    
    Parameters:
    
    msg - message to send.
    
    Returns:
    
    received response message, null on timeout.
  - setQueueSize
```
public void setQueueSize(int size)
```
    Sets the maximum length of the incoming message queue for the agent. If the queue overflows, the oldest messages are dropped.
    
    Parameters:
    
    size - maximum number of messages in the message queue.
  - subscribe
```
public boolean subscribe(AgentID topic)
```
    Subscribes the agent to receive all messages sent to the given topic.
    
    Parameters:
    
    topic - the topic to subscribe to.
    
    Returns:
    
    true if the subscription is successful, false otherwise.
  - unsubscribe
```
public boolean unsubscribe(AgentID topic)
```
    Unsubscribes the agent from a given topic.
    
    Parameters:
    
    topic - the topic to unsubscribe.
    
    Returns:
    
    true if the unsubscription is successful, false otherwise.
  - register
```
public boolean register(java.lang.String service)
```
    Registers the agent with the directory service as a provider of a named service.
    
    Parameters:
    
    service - the named service that the agent provides.
    
    Returns:
    
    true if the registration was successful, false otherwise.
  - register
```
public boolean register(java.lang.Enum<?> service)
```
    Registers the agent with the directory service as a provider of a named service.
    
    Parameters:
    
    service - the named service that the agent provides.
    
    Returns:
    
    true if the registration was successful, false otherwise.
  - deregister
```
public boolean deregister(java.lang.String service)
```
    De-registers the agent from the directory service as a provider of a named service.
    
    Parameters:
    
    service - the named service that the agent no longer provides.
    
    Returns:
    
    true if the de-registration was successful, false otherwise.
  - deregister
```
public boolean deregister(java.lang.Enum<?> service)
```
    De-registers the agent from the directory service as a provider of a named service.
    
    Parameters:
    
    service - the named service that the agent no longer provides.
    
    Returns:
    
    true if the de-registration was successful, false otherwise.
  - agentForService
```
public AgentID agentForService(java.lang.String service)
```
    Finds an agent that provides a named service. If multiple agents are registered to provide a given service, any of the agents' id may be returned.
    
    Parameters:
    
    service - the named service of interest.
    
    Returns:
    
    an agent id for an agent that provides the service.
  - agentForService
```
public AgentID agentForService(java.lang.Enum<?> service)
```
    Finds an agent that provides a named service. If multiple agents are registered to provide a given service, any of the agents' id may be returned.
    
    Parameters:
    
    service - the named service of interest.
    
    Returns:
    
    an agent id for an agent that provides the service.
  - agentsForService
```
public AgentID[] agentsForService(java.lang.String service)
```
    Finds all agents that provides a named service.
    
    Parameters:
    
    service - the named service of interest.
    
    Returns:
    
    an array of agent ids representing all agent that provide the service.
  - agentsForService
```
public AgentID[] agentsForService(java.lang.Enum<?> service)
```
    Finds all agents that provides a named service.
    
    Parameters:
    
    service - the named service of interest.
    
    Returns:
    
    an array of agent ids representing all agent that provide the service.
  - println
```
public void println(java.lang.Object msg)
```
    Logs a message at an INFO level.
    
    Parameters:
    
    msg - message to log.
  - getStore
```
public Store getStore()
```
    Gets a persistent store for the agent.
  - clone
```
public <T extends java.io.Serializable> T clone(T obj)
```
    Deep clones an object. This is typically used to explicitly clone a message for modification when autocloning is not enabled.
    
    Parameters:
    
    obj - object to clone.
    
    Returns:
    
    cloned object.
  - toString
```
public java.lang.String toString()
```
    Gets a string representation of the agent.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    string representation of the agent.
    
    See Also:
    
    Object.toString()
  - run
```
public final void run()
```
    Lifecycle of the agent. Called by the container as needed.
    
    Specified by:
    
    run in interface java.lang.Runnable
    
    See Also:
    
    Runnable.run()

Class Agent

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NON_BLOCKING

BLOCKING

ALL

FINEST

FINER

FINE

INFO

WARNING

SEVERE

OFF

tid

thread

ignoreExceptions

log

Constructor Detail

Agent

Method Detail

init

shutdown

die

getAgentID

getName

getType

setLogLevel

block

block

delay

wake

stop

add

getState

getPlatform

getContainer

currentTimeMillis

nanoTime

agent

topic

topic

topic

topic

topic

topic

send

prepareRequest

platformSend

setYieldDuringReceive

getYieldDuringReceive

receive

receive

receive

receive

receive

receive

receive

receive

request

request

setQueueSize

subscribe

unsubscribe

register

register

deregister

deregister

agentForService

agentForService

agentsForService

agentsForService

println

getStore

clone

toString

run