Container (fjage 2.0.0 API)

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

Direct Known Subclasses:

MasterContainer, SlaveContainer
```
public class Container
extends java.lang.Object
```
Container to manage agent lifecycle. Agents in a container are able to discover services provided by each other, and send or receive messages to each other or common topics. Containers run on a platform. For an example of how containers with agents are created, see RealTimePlatform.
By default, messages sent between agents are not cloned. The developer must ensure that a message or any object contained in the message is not modified after it has been sent or received. During deployment, this default behavior can be changed using setAutoClone(boolean).

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.util.Map<AgentID,Agent>`	`agents`
`protected java.util.Map<AgentID,Agent>`	`agentsToAdd`
`protected boolean`	`autoclone`
`protected java.lang.Object`	`cloner`
`protected java.lang.reflect.Method`	`doClone`
`static java.lang.String`	`FAST_CLONER`
`protected java.util.Set<AgentID>`	`idle`
`protected boolean`	`inited`
`protected boolean`	`initing`
`protected java.util.Set<MessageListener>`	`listeners`
`protected java.util.logging.Logger`	`log`
`protected java.lang.String`	`name`
`protected Platform`	`platform`
`protected boolean`	`running`
`static java.lang.String`	`SERIAL_CLONER`
`protected java.util.Map<java.lang.String,java.util.Set<AgentID>>`	`services`
`protected java.util.Map<AgentID,java.util.Set<Agent>>`	`topics`

Constructor Summary

Constructors
Constructor and Description

Container(Platform platform)
Creates a container.

Container(Platform platform, java.lang.String name)
Creates a named container.

Constructors
Constructor and Description
`Container(Platform platform)` Creates a container.
`Container(Platform platform, java.lang.String name)` Creates a named container.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`AgentID`	`add(Agent agent)` Adds an agent to the container.
`AgentID`	`add(java.lang.String name, Agent agent)` Adds an agent to the container.
`boolean`	`addListener(MessageListener listener)` Adds a listener to the container.
`AgentID`	`agentForService(java.lang.String service)` Finds an agent providing a named service.
`AgentID[]`	`agentsForService(java.lang.String service)` Finds all agents providing a named service.
`boolean`	`canLocateAgent(AgentID aid)` Checks if an agent can be located.
`<T extends java.io.Serializable> T`	`clone(T obj)` Deep clones an object.
`boolean`	`containsAgent(AgentID aid)` Checks if an agent exists in the container.
`void`	`deregister(AgentID aid)` Deregisters an agent as a provider of all services.
`boolean`	`deregister(AgentID aid, java.lang.String service)` Deregisters an agent as a provider of a specific service.
`Agent`	`getAgent(AgentID aid)` Gets an agent given its id.
`AgentID[]`	`getAgents()` Gets all agent ids in the container.
`boolean`	`getAutoClone()` Returns whether autoclone is enabled.
`java.lang.String`	`getName()` Gets the name of the container.
`Platform`	`getPlatform()` Gets the platform on which the container runs.
`java.lang.String[]`	`getServices()` Gets a list of all services that agents in this container provide.
`java.lang.String`	`getState()` Gets human readble state information for container.
`protected void`	`initComplete()` Called when the container is initialized.
`protected boolean`	`isDuplicate(AgentID aid)` Checks if an agent id already exists in the container.
`boolean`	`isIdle()` Checks if all agents in the container are idle.
`boolean`	`isRunning()` Checks if the container is currently running.
`boolean`	`kill(AgentID aid)` Terminates an agent.
`boolean`	`kill(java.lang.String name)` Terminates an agent.
`boolean`	`register(AgentID aid, java.lang.String service)` Registers an agent in the directory service as a provider of a named service.
`boolean`	`removeListener(MessageListener listener)` Removes a listener from the container.
`boolean`	`send(Message m)` Sends a message.
`boolean`	`send(Message m, boolean relay)` Sends a message.
`void`	`setAutoClone(boolean b)` Enables or disables autocloning.
`void`	`setCloner(java.lang.String name)` Sets the cloner to use for deep cloning.
`void`	`setName(java.lang.String name)` Sets the name of the container.
`void`	`shutdown()` Terminates the container and all agents in it.
`protected void`	`start()` Starts the container and all agents in it.
`boolean`	`subscribe(AgentID aid, AgentID topic)` Subscribes an agent to messages sent to a topic.
`java.lang.String`	`toString()` Gets a string representation of the container.
`void`	`unsubscribe(AgentID aid)` Unsubscribes an agent from all topics.
`boolean`	`unsubscribe(AgentID aid, AgentID topic)` Unsubscribes an agent from a topic.

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

- Field Detail
  - SERIAL_CLONER
```
public static final java.lang.String SERIAL_CLONER
```
    See Also:
    
    Constant Field Values
  - FAST_CLONER
```
public static final java.lang.String FAST_CLONER
```
    See Also:
    
    Constant Field Values
  - name
```
protected java.lang.String name
```
  - platform
```
protected Platform platform
```
  - agents
```
protected java.util.Map<AgentID,Agent> agents
```
  - agentsToAdd
```
protected java.util.Map<AgentID,Agent> agentsToAdd
```
  - topics
```
protected java.util.Map<AgentID,java.util.Set<Agent>> topics
```
  - services
```
protected java.util.Map<java.lang.String,java.util.Set<AgentID>> services
```
  - log
```
protected java.util.logging.Logger log
```
  - running
```
protected boolean running
```
  - initing
```
protected boolean initing
```
  - inited
```
protected boolean inited
```
  - cloner
```
protected java.lang.Object cloner
```
  - doClone
```
protected java.lang.reflect.Method doClone
```
  - autoclone
```
protected boolean autoclone
```
  - idle
```
protected java.util.Set<AgentID> idle
```
  - listeners
```
protected java.util.Set<MessageListener> listeners
```
- Constructor Detail
  - Container
```
public Container(Platform platform)
```
    Creates a container.
    
    Parameters:
    
    platform - platform on which the container runs.
  - Container
```
public Container(Platform platform,
                 java.lang.String name)
```
    Creates a named container.
    
    Parameters:
    
    platform - platform on which the container runs.
    
    name - name of the container.
- Method Detail
  - getPlatform
```
public Platform getPlatform()
```
    Gets the platform on which the container runs.
    
    Returns:
    
    the platform.
  - setName
```
public void setName(java.lang.String name)
```
    Sets the name of the container.
    
    Parameters:
    
    name - name of the container.
  - getName
```
public java.lang.String getName()
```
    Gets the name of the container.
    
    Returns:
    
    name of the container.
  - setCloner
```
public void setCloner(java.lang.String name)
```
    Sets the cloner to use for deep cloning. Two cloners are currently supported:
    - SERIAL_CLONER -- Cloner using serialization (default) (requires Apache commons-lang v3)
    - FAST_CLONER -- Fast but Groovy incompatible cloner (requires Java deep cloning library)
    Parameters:
    
    name - name of the cloner to use.
  - 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.
  - setAutoClone
```
public void setAutoClone(boolean b)
```
    Enables or disables autocloning. Autocloning is disabled by default.
    
    Parameters:
    
    b - true to enable autocloning, false to disable it.
  - getAutoClone
```
public boolean getAutoClone()
```
    Returns whether autoclone is enabled.
    
    Returns:
    
    true if autocloning enabled, false otherwise.
  - add
```
public AgentID add(java.lang.String name,
                   Agent agent)
```
    Adds an agent to the container.
    Agent names should only contain alphanumeric characters and underscores. The first character should not be a digit. Names with special characters such as '-', '.', '@', etc are considered reserved and should be avoided.
    While agent names inconsistent with this guideline may not be rejected today, they may not work well on all platforms. In future, we may enforce this guideline more strictly.
    
    Parameters:
    
    name - name of the agent.
    
    agent - the agent object.
    
    Returns:
    
    an agent id if successful, null on failure.
  - add
```
public AgentID add(Agent agent)
```
    Adds an agent to the container. The name of the agent is automatically chosen.
    
    Parameters:
    
    agent - the agent object.
    
    Returns:
    
    an agent id if successful, null on failure.
  - containsAgent
```
public boolean containsAgent(AgentID aid)
```
    Checks if an agent exists in the container.
    
    Parameters:
    
    aid - agent id to check.
    
    Returns:
    
    true if the agent exists, false otherwise.
  - canLocateAgent
```
public boolean canLocateAgent(AgentID aid)
```
    Checks if an agent can be located. If agent in not found in current container, any available remote containers are checked too.
    
    Parameters:
    
    aid - agent id to locate.
    
    Returns:
    
    true if the agent can be located, false otherwise.
  - getAgent
```
public Agent getAgent(AgentID aid)
```
    Gets an agent given its id. This method only finds agents in the current container.
    
    Parameters:
    
    aid - agent id.
    
    Returns:
    
    agent associated with the id if exists in the current container, null otherwise.
  - getAgents
```
public AgentID[] getAgents()
```
    Gets all agent ids in the container.
    
    Returns:
    
    an array of agent ids.
  - kill
```
public boolean kill(AgentID aid)
```
    Terminates an agent.
    
    Parameters:
    
    aid - id of agent to terminate.
    
    Returns:
    
    true if successful, false on failure.
  - kill
```
public boolean kill(java.lang.String name)
```
    Terminates an agent.
    
    Parameters:
    
    name - name of agent to terminate.
    
    Returns:
    
    true if successful, false on failure.
  - addListener
```
public boolean addListener(MessageListener listener)
```
    Adds a listener to the container. A listener is able to snoop on all messages passing through the container, and optionally able to ask the container to drop a message.
    
    Parameters:
    
    listener - listener.
    
    Returns:
    
    true if successfully added, false otherwise.
  - removeListener
```
public boolean removeListener(MessageListener listener)
```
    Removes a listener from the container.
    
    Parameters:
    
    listener - listener.
    
    Returns:
    
    true if successfully removed, false otherwise.
  - send
```
public boolean send(Message m)
```
    Sends a message. The message is sent to the recipient specified in the message. In case of associated remote containers, the message is only delivered to agents in this container.
    
    Parameters:
    
    m - message to deliver
    
    Returns:
    
    true if delivered, false otherwise.
  - send
```
public boolean send(Message m,
                    boolean relay)
```
    Sends a message. The message is sent to the recipient specified in the message.
    
    Parameters:
    
    m - message to deliver
    
    relay - enable relaying to associated remote containers.
    
    Returns:
    
    true if delivered, false otherwise.
  - subscribe
```
public boolean subscribe(AgentID aid,
                         AgentID topic)
```
    Subscribes an agent to messages sent to a topic.
    
    Parameters:
    
    aid - id of agent to subscribe.
    
    topic - topic to subscribe to.
    
    Returns:
    
    true on success, false on failure.
  - unsubscribe
```
public boolean unsubscribe(AgentID aid,
                           AgentID topic)
```
    Unsubscribes an agent from a topic.
    
    Parameters:
    
    aid - id of agent to unsubscribe.
    
    topic - topic to unsubscribe from.
    
    Returns:
    
    true on success, false on failure.
  - unsubscribe
```
public void unsubscribe(AgentID aid)
```
    Unsubscribes an agent from all topics.
    
    Parameters:
    
    aid - id of agent to unsubscribe.
  - register
```
public boolean register(AgentID aid,
                        java.lang.String service)
```
    Registers an agent in the directory service as a provider of a named service.
    
    Parameters:
    
    aid - id of agent providing the service.
    
    service - name of the service.
    
    Returns:
    
    true on success, false on failure.
  - getServices
```
public java.lang.String[] getServices()
```
    Gets a list of all services that agents in this container provide.
    
    Returns:
    
    an array of service names.
  - agentForService
```
public AgentID agentForService(java.lang.String service)
```
    Finds an agent providing a named service.
    
    Parameters:
    
    service - name of the service.
    
    Returns:
    
    agent id for service provider, null if none found.
  - agentsForService
```
public AgentID[] agentsForService(java.lang.String service)
```
    Finds all agents providing a named service.
    
    Parameters:
    
    service - name of the service.
    
    Returns:
    
    an array of agent ids for service providers, null if none found.
  - deregister
```
public boolean deregister(AgentID aid,
                          java.lang.String service)
```
    Deregisters an agent as a provider of a specific service.
    
    Parameters:
    
    aid - id of agent to deregister.
    
    service - name of the service to deregister.
    
    Returns:
    
    true on success, false on failure.
  - deregister
```
public void deregister(AgentID aid)
```
    Deregisters an agent as a provider of all services.
    
    Parameters:
    
    aid - id of agent to deregister.
  - initComplete
```
protected void initComplete()
```
    Called when the container is initialized. This is called after all agents have been initialized.
  - start
```
protected void start()
```
    Starts the container and all agents in it. This should be called after init().
  - shutdown
```
public void shutdown()
```
    Terminates the container and all agents in it.
  - isRunning
```
public boolean isRunning()
```
    Checks if the container is currently running.
    
    Returns:
    
    true if the container is running, false otherwise.
  - isIdle
```
public boolean isIdle()
```
    Checks if all agents in the container are idle.
    
    Returns:
    
    true if all agents are idle, false otherwise.
  - getState
```
public java.lang.String getState()
```
    Gets human readble state information for container.
    
    Returns:
    
    state string.
  - toString
```
public java.lang.String toString()
```
    Gets a string representation of the container.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    string representation of the container.
    
    See Also:
    
    Object.toString()
  - isDuplicate
```
protected boolean isDuplicate(AgentID aid)
```
    Checks if an agent id already exists in the container.
    
    Parameters:
    
    aid - the agent id to check.
    
    Returns:
    
    true if it exists, false otherwise.

Class Container

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SERIAL_CLONER

FAST_CLONER

name

platform

agents

agentsToAdd

topics

services

log

running

initing

inited

cloner

doClone

autoclone

idle

listeners

Constructor Detail

Container

Container

Method Detail

getPlatform

setName

getName

setCloner

clone

setAutoClone

getAutoClone

add

add

containsAgent

canLocateAgent

getAgent

getAgents

kill

kill

addListener

removeListener

send

send

subscribe

unsubscribe

unsubscribe

register

getServices

agentForService

agentsForService

deregister

deregister

initComplete

start

shutdown

isRunning

isIdle

getState

toString

isDuplicate