org.iids.aos.messagecenter
Class MessageCenter

java.lang.Object
  org.iids.aos.systemservices.module.AbstractModule
      org.iids.aos.messagecenter.MessageCenter

All Implemented Interfaces:

Module

public class MessageCenter
extends AbstractModule

Author:

hidde

Constructor Summary

MessageCenter(Communicator _communicator, AgentScapeConfig config, AsLookupService lookupService)

Method Summary

void	addAgent(AgentID id) Register AgentID to be available for receiving messages.
Envelope	getMessage(AgentID fromId, java.util.Collection<AgentHandle> handles, boolean block) Implementation of HostManager.get_message(org.iids.aos.systemservices.communicator.structs.AgentID, java.util.Collection, boolean).
java.util.List<Envelope>	getMessages(AgentID fromId, java.util.Collection<AgentHandle> handles, boolean block) Similar to getMessage(org.iids.aos.systemservices.communicator.structs.AgentID, java.util.Collection, boolean) but it has the possibility of returning multiple messages (if currently available).
boolean	isStarted()
void	putMessage(Envelope env, boolean canForward) Drop off a single envelope for an agent.
void	putMessages(java.util.List<Envelope> envs, boolean canForward) Drop off a set of messages at this message center.
java.util.List<Envelope>	removeAgent(AgentID id) Remove receiver from message center.
java.util.List<Envelope>	removeAgentHandle(AgentID id, AgentHandle... ah) Removes all messages that are in the queue for a set of handles.
void	start()
void	stop()

Methods inherited from class org.iids.aos.systemservices.module.AbstractModule

getCommunicator, getModuleName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageCenter

public MessageCenter(Communicator _communicator,
                     AgentScapeConfig config,
                     AsLookupService lookupService)

Method Detail

removeAgentHandle

public java.util.List<Envelope> removeAgentHandle(AgentID id,
                                                  AgentHandle... ah)
                                           throws AgentIDUnknownException

Removes all messages that are in the queue for a set of handles. Because the message center does not manager the handles that belong to an agent, any incoming message for the removed handles will still be enqueued. This has to be handle by the part that manages the agent handles.

Parameters:

id - The ID of the agent to remove the handle from

ah - The handle to remove all messages for

Returns:

all envelopes currently enqueued for the handles

Throws:

AgentIDUnknownException

start

public void start()

stop

public void stop()

isStarted

public boolean isStarted()

getMessage

public Envelope getMessage(AgentID fromId,
                           java.util.Collection<AgentHandle> handles,
                           boolean block)
                    throws AgentIDUnknownException,
                           AgentUnknownException

Implementation of HostManager.get_message(org.iids.aos.systemservices.communicator.structs.AgentID, java.util.Collection, boolean).

Attempts to receive messages from an agent with AgentID fromId. It only receives messages sent to any of the handles in handles.

TODO: semantics when handes == null. For now, return an error (i.e. receive nothing) if there were no handles specified.

Parameters:

fromId - The AgentID of the agent to receive messages from.

handles - List of handles to receive from. The handles are assumed to belong to fromId, though this is not checked. So, if none of the handles in handles are valid, then nothing will be received.

block - If no messages are available, block and wait until a message becomes available for this agent, with a handle from handles.

Returns:

Envelope with the next in line message, or null if there are no messages available and block == false.

Throws:

AgentIDUnknownException - If the AgentID is not known to this message center, or

AgentUnknownException - If there are no handles supplied (either null or an empty list.

getMessages

public java.util.List<Envelope> getMessages(AgentID fromId,
                                            java.util.Collection<AgentHandle> handles,
                                            boolean block)
                                     throws AgentIDUnknownException,
                                            AgentUnknownException

Similar to getMessage(org.iids.aos.systemservices.communicator.structs.AgentID, java.util.Collection, boolean) but it has the possibility of returning multiple messages (if currently available). This method will block if needed, and wait for messages. If there is any result, this method will not block, and return what is currently available in the message queue.

Parameters:

fromId - The Agent to receive messages from

handles - All handles we want to look out for

block - Block if no result is available

Returns:

A set of envelopes (possibly empty if block is false) directed to (any of) the handles from the handles argument.

Throws:

AgentIDUnknownException - If the agent is not known

AgentUnknownException - If (one of) the handle(s) does not belong the the agent.

putMessages

public void putMessages(java.util.List<Envelope> envs,
                        boolean canForward)
                 throws MessageException

Drop off a set of messages at this message center. All the envelopes that can be locally delivered will be put in the message queue for the corresponding agents.

Messages that are for agents that are not registered to this message center, will be forwarded to the correct message center, but only if canForward is specified to be true.

Parameters:

envs - The envelopes to deliver

canForward - Indicates if messages that are not intended for local agents can be forwarded to a remote message center. This prevents message centers from bouncing messages for unknown agents that are still registered in the lookup service.

Throws:

MessageException - If some of the messages could not be delivered to their destination.

putMessage

public void putMessage(Envelope env,
                       boolean canForward)
                throws MessageException

Drop off a single envelope for an agent.

Parameters:

env - The envelope to drop off.

canForward - If true then the message may be forwarded to another message center. This will happen only if the current message center does not maintain the queue for the target agent.

Throws:

MessageException - If the message could not be delivered for some reason.

addAgent

public void addAgent(AgentID id)
              throws AgentAlreadyRegisteredException

Register AgentID to be available for receiving messages.

A message center will only accept messages for agents which IDs are registered here. Once an agent is moved, you can (or must) deregister the ID to collect all of its pending messages.

Parameters:

id - GUID of the agent to register

Throws:

AgentAlreadyRegisteredException - If the agent was already registered with this message center.

removeAgent

public java.util.List<Envelope> removeAgent(AgentID id)
                                     throws AgentIDUnknownException

Remove receiver from message center.

Any incoming message will not be enqueued anymore (raises exception). All pending messages for this agent are returned and cannot be dequeued anymore by subsequent calls to getMessage(org.iids.aos.systemservices.communicator.structs.AgentID, java.util.Collection, boolean).

Parameters:

id - Agent GUID to remove from message center

Returns:

Array with all envelopes that were left in the message center. If there were no pending messages, there will be zero elements in this.

Throws:

AgentIDUnknownException - If the agent was not registered with this message center.