org.iids.aos.api
Interface AgentScapeApi

All Superinterfaces:

java.rmi.Remote

All Known Implementing Classes:

AgentScapeApiRmiServer

public interface AgentScapeApi
extends java.rmi.Remote

AgentScape programmers API

.

This is the AgentScape interface, which is the only entry point for software (and agent) developers to interact with a running AgentScape platform. It exposes calls to create and manipulate (running) agents, and to use the AgentScape messaging and migration primitives. Moreover, any services that a running AgentScape platform offers have to be accessed through this interface.

Because this API generally is shared between processes/agents, the caller needs to provide an authentication token with each method invocation. For now, the caller can supply any of its AgentHandles. The API itself is stateless, meaning that it does not remember which handle you used for previous method invocations.

Note: many of these AgentScape API-methods are not meant to be called from the agent. Agents extend from Agent which offers a simpler (wrapper) interface to many of AgentScape's API methods.

Agents

Agents are created with the methods createAgent and startAgent. The method createAgent either creates an empty agent or is given a pre-built agent in the form of an AgentArchive. The contents (code+data) can written to the (empty) agent with writecodeSegment and writeDataSegment.

startAgent will set the agent running. waitForAgent can be used to wait until the agent has finished. killAgent can be used to kill the agent gracefully.

AgentHandles

Agents are identified via AgentHandles. Each agent can have multiple AgentHandles. At creation time two AgentHandles are created: the primary and owner handle. The owner handle can - by convention - be used by the creator of the agent to communicate with the agent (via messages, see below). New AgentHandles can be created with createAgentHandle. Existing handles can be removed with removeAgentHandle.

Communication

Agents can communicate with each other by sending and receiving messages. Messages are stored in Envelopes. Each Envelope contains a from and one or more to AgentHandles, indicating the sender and receiving agents respectively. The from AgentHandle can be any handle of the sending Agent. The to AgentHandle can be any handle of the receiving Agent. Envelopes with multiple to AgentHandles can be used to multi-cast messages.

Receivers of messages can specify for which AgentHandle (must be one of their own AgentHandles, of course) they want to receive messages. The to field of received multi-cast messages will only contain the AgentHandles that the receiving Agent has indicated to the receiveMessage(s) method. When sending a multicast message, each target will receive a copy (bcc) of the message.

AgentScape considers each multi-cast message to multiple AgentHandles as multiple messages, each to a single AgentHandle, even if AgentHandles belong to the same Agent. As a consequence, if an Agent has received a multi-cast message that has been sent to multiple of its AgentHandles, the method receiveMessage will return only one message for one of the multi-cast AgentHandles at a time. The method receiveMessages, however, will return the (single) multi-cast message with all relevant to AgentHandles in tact.

Data Storage

Agents can store data inside their agentcontainer. Each container can contain multiple Code and Data segments. These segments can be read and written with readCodeSegment, readDataSegment, writeCodeSegment, and writeDataSegment. Note, this interface may change in the future.

Migration

Agents can migrate between AgentScape locations. moveAgent will migrate an agent to a destination location. This is weak migration, meaning that the running state of the agent will be lost during the migration. The agent will (re)start at the destination location. State that should migrate with the agent should be stored in the agent's data segments.

Agent migration is typically done by calling methods in the Agents api.

Note: for Java agents, AgentScape will migrate any local (non-transient) variables declared within the agent's java code.

TODOs (developers)

• add lease negotiation calls? These are probably identical to what can be found in the AgentNegotiationLibInterface.
• there is no role management present yet, so in theory it should be possible for anyone to gain access to an agent by presenting an appropriate agent handle. Access control will be added sometime in the (near/distant) future.

See also the AgentScape tutorial, for more information.

Author:

rjtimmer, michel

See Also:

Agent

Field Summary

static java.lang.String	RMINAME
static java.lang.String	SVCNAME

Method Summary

AgreementOffer	acceptLease(AgentScapeID location, java.lang.String leaseId) Accept lease.
AgentInfo	createAgent(AgentScapeID location, AgentArchive arch) Create new agent from agent archive, without lease negotiation.
AgentInfo	createAgent(AgentScapeID location, Language lang) Create a new agent.
AgentInfo	createAgent(java.lang.String lease, AgentArchive arch) Create a new agent from archive and pre-negotiated lease.
AgentHandle	createAgentHandle(AgentHandle handle) Creates new handle (alias) for an existing agent.
void	deleteCodeSegment(AgentHandle handle, AgentCodeSegment code) Delete code segment from agent.
void	deleteDataSegment(AgentHandle handle, AgentDataSegment segment) Delete data segment from agent.
AgentArchive	exportAgent(AgentHandle handle) Export current agent state (from agent container) to an AgentArchive.
java.util.Hashtable<java.lang.String,java.util.Hashtable<java.lang.String,java.util.Vector<java.util.Vector<java.lang.Object>>>>	find(java.lang.String key, java.lang.String value)
AgentHandle[]	getAgentHandles(AgentHandle handle) Get agent handles belonging to an agent.
void	killAgent(AgentHandle handle) Kill a specific agent.
void	killAgent(AgentID id) Note: Only for administrative/debugging purposes.
java.util.Hashtable<java.lang.String,java.util.Hashtable<java.lang.String,java.util.Vector<java.util.Vector<java.lang.Object>>>>	list(java.lang.String key)
java.util.List<AgentHandle>	listAgentHandles(AgentID id) List all agenthandles of this agent.
java.util.HashMap<AgentScapeID,java.util.List<AgentID>>	listAgents(AgentScapeID location) List all agents running on a particular location.
AgentCodeSegment[]	listCodeSegments(AgentHandle handle) Obtain a list of all code segments stored in the agent container.
AgentDataSegment[]	listDataSegments(AgentHandle handle) Obtain a list of all data segments stored in the agent container.
java.util.Hashtable<java.lang.String,java.util.Vector<java.util.Vector<java.lang.Object>>>	lookup(java.lang.String identifier)
void	moveAgent(AgentHandle handle, AgentScapeID targetLocation) Migrate agent identified with 'handle' to location targetLocation.
void	moveAgent(AgentHandle handle, AgentScapeID location, java.lang.String leaseId) Migrate agent identified with 'handle' to location as contained in the (previously established) lease.
byte[]	readCodeSegment(AgentHandle handle, AgentCodeSegment codeSeg) Read code segment.
byte[]	readDataSegment(AgentHandle handle, AgentDataSegment dataSeg) Read data segment.
Envelope	receiveMessage(AgentHandle handle, boolean block) Receive a message from a single handle only.
Envelope	receiveMessage(AgentHandle handle, java.util.List<AgentHandle> handles, boolean block) Receive message from queue, addressed to a set of the handles that the agent owns.
Envelope[]	receiveMessages(AgentHandle handle, java.util.List<AgentHandle> handles, boolean block) Receive messages from queue, addressed to some of the handles that the agent owns.
long	register(java.lang.String identifier, java.lang.String key, java.lang.String value, float duration)
void	removeAgentHandle(AgentHandle handle) Shortcut for removeAgentHandle(handle, false).
java.util.List<Envelope>	removeAgentHandle(AgentHandle handle, boolean pickup) Remove a handle from an existing agent.
AgreementOffer	requestLease(AgentScapeID location, AgreementOffer leaseRequest) Pass on lease request for given resource request to location manager on the location location.
TemplateList	requestTemplates(AgentScapeID location) Request a list of available templates from a location.
void	sendMessage(Envelope envelope) Send a message to another agent.
void	sendMessages(java.util.List<Envelope> envelopes)
void	setDefaultCodeSegment(AgentHandle handle, AgentCodeSegment code) Set which code segment to run next time the agent starts or moves.
void	startAgent(AgentHandle handle, boolean collect, java.lang.String... args) Start running the agent.
void	startAgent(AgentHandle handle, java.lang.String... args) Shortcut for startAgent(handle,false,args)
AgentArchive	waitForAgent(AgentHandle handle, boolean pickup) Wait for agent to be finished, then export it back to the owner as an agent archive.
AgentCodeSegment	writeCodeSegment(AgentHandle handle, AgentCodeSegment codeSegment, byte[] code) Write contents of a code segment to the agent container.
AgentCodeSegment	writeCodeSegment(AgentHandle handle, java.lang.String description, Language language, byte[] code) Shortcut for writeCodeSegment(handle,new AgentCodeSegment(description, language), code).
AgentDataSegment	writeDataSegment(AgentHandle handle, AgentDataSegment dataSegment, byte[] data) Write bytes to a data segment.
AgentDataSegment	writeDataSegment(AgentHandle handle, java.lang.String description, java.lang.String subtype, byte[] data) Shortcut for writeDataSegment(handle,new AgentDataSegment( description, subtype), data).

Field Detail

SVCNAME

static final java.lang.String SVCNAME

See Also:

Constant Field Values

RMINAME

static final java.lang.String RMINAME

See Also:

Constant Field Values

Method Detail

createAgent

AgentInfo createAgent(AgentScapeID location,
                      AgentArchive arch)
                      throws java.rmi.RemoteException,
                             LocationUnknownException,
                             AgentArchiveException,
                             NegotiationLibException,
                             AgentCreationException

Create new agent from agent archive, without lease negotiation.

This automatically creates a new handle (and ID) for the new agent, and fills its agent container with the contents of the archive. After this call returns successfully, it is possible to start the agent, if the contents of the archive results in a runnable agent.

Lease negotiation is done automatically (if the archive has a default code segment) to select a suitable host on the target location.

Note that (in theory) it is also possible to add code and data segments to the agent even after this call is done. The AgentArchive provided is merely a starting point for the filling in of these segment. Depending on the contents of the archive and the needs of the agent programmer, this may or may not be enough to start the agent. It is however, a little problematic to alter things like (default) code segments after creating the agent, so treat with care.

Parameters:

location - The target location to run the agent on.

arch - The contents of the new agent.

Returns:

A structure containing the agent information. This information contains the owner and primary handles for communication with the agent.

Throws:

LocationUnknownException - Location not found.

AgentArchiveException - Problem with interpreting archive, or no (default) code segment found in the archive.

NegotiationLibException - No environment for required language on the target location.

java.rmi.RemoteException - Error performing remote method invocation.

AgentCreationException

createAgent

AgentInfo createAgent(AgentScapeID location,
                      Language lang)
                      throws java.rmi.RemoteException,
                             LocationUnknownException,
                             AgentCreationException

Create a new agent.

The newly created agent will be placed on a host in 'location'. An agent server is selected according to the preferred language for the new agent.

Parameters:

location - Target location of the new agent.

lang - Language requirement of the new agent.

Returns:

A structure with handle information of the newly created agent.

Throws:

LocationUnknownException - Target location unknown.

NegotiationLibException - No environment for required language on the target location.

java.rmi.RemoteException - Error performing remote method invocation.

AgentCreationException

createAgent

AgentInfo createAgent(java.lang.String lease,
                      AgentArchive arch)
                      throws java.rmi.RemoteException,
                             NegotiationLibException,
                             AgentArchiveException

Create a new agent from archive and pre-negotiated lease.

I don't know if this case is really useful, because one has to create a lease before starting the archive. Currently, negotiation deals with environment resources (i.e. agent server) only.

NOTE: this will only be implemented if it is possible to negotiate a lease before creating an agent ID.

Parameters:

lease - Pre-negotiated lease for agent.

arch - The contents of the new agent.

Returns:

Information concerning the newly created AgentHandles.

Throws:

AgentArchiveException - Problem with interpreting archive.

NegotiationLibException - Lease negotiation error.

java.rmi.RemoteException - Error performing remote method invocation.

createAgentHandle

AgentHandle createAgentHandle(AgentHandle handle)
                              throws java.rmi.RemoteException,
                                     AgentUnknownException

Creates new handle (alias) for an existing agent.

Parameters:

handle - Agent handle to create alias for.

Returns:

New alias AgentHandle for the agent.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException - Error performing remote method invocation.

removeAgentHandle

java.util.List<Envelope> removeAgentHandle(AgentHandle handle,
                                           boolean pickup)
                                           throws java.rmi.RemoteException,
                                                  AgentUnknownException

Remove a handle from an existing agent.

Parameters:

handle - The handle to remove

pickup - If this is true then all pending undelivered messages are returned. Otherwise these are discarded.

Returns:

A list containing all pending message for the removed handle.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException - Error performing remote method invocation.

removeAgentHandle

void removeAgentHandle(AgentHandle handle)
                       throws java.rmi.RemoteException,
                              AgentUnknownException

Shortcut for removeAgentHandle(handle, false). As such this method never returns any pending undelivered messages.

Throws:

java.rmi.RemoteException

AgentUnknownException

See Also:

removeAgentHandle

getAgentHandles

AgentHandle[] getAgentHandles(AgentHandle handle)
                              throws java.rmi.RemoteException,
                                     AgentUnknownException

Get agent handles belonging to an agent.

Obtains a list of all handles belonging to an agent. Each agent has at least two handles: owner and primary handle.

Parameters:

handle - An already existing AgentHandle.

Returns:

A newly created AgentHandle associated with this agent.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException - Error performing remote method invocation.

requestTemplates

TemplateList requestTemplates(AgentScapeID location)
                              throws java.rmi.RemoteException,
                                     NegotiationLibException,
                                     LocationUnknownException

Request a list of available templates from a location.

Parameters:

location - The location to request the templates from.

Returns:

A list of templates to be used for lease negotiation.

Throws:

NegotiationLibException - Any negotiation library exception.

LocationUnknownException - Location unknown.

java.rmi.RemoteException - Error performing remote method invocation.

requestLease

AgreementOffer requestLease(AgentScapeID location,
                            AgreementOffer leaseRequest)
                            throws java.rmi.RemoteException,
                                   NegotiationLibException,
                                   LocationUnknownException

Pass on lease request for given resource request to location manager on the location location.

Parameters:

location - Target location which to request lease from.

leaseRequest - Filled in lease request document.

Returns:

Agreement offer with reply from location manager. This offer contains a lease identifier containing that can be used to refer to this offer.

Throws:

NegotiationLibException - Error with lease negotiation.

LocationUnknownException - Target location unknown.

java.rmi.RemoteException - Error performing remote method invocation.

acceptLease

AgreementOffer acceptLease(AgentScapeID location,
                           java.lang.String leaseId)
                           throws java.rmi.RemoteException,
                                  NegotiationLibException,
                                  LocationUnknownException

Accept lease.

Accept lease offer at location manager.

Parameters:

location - Target location which to accept lease from.

leaseId - The leaseid of the offer that is accepted.

Returns:

the final agreed upon lease.

Throws:

NegotiationLibException - Lease negotiation error.

LocationUnknownException - Target location unknown.

java.rmi.RemoteException - Error performing remote method invocation.

startAgent

void startAgent(AgentHandle handle,
                boolean collect,
                java.lang.String... args)
                throws java.rmi.RemoteException,
                       AgentUnknownException,
                       AgentStartupException

Start running the agent.

The hostmanager running this agent is informed that it can now startup the agent belonging to this agenthandle.

Parameters:

handle - The agent to run.

collect - Intention to collect agent once it is done.

args - Optional arguments to the agent.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

AgentStartupException - If there is no (appropriate) code segment to start the agent on the (negotiated) host/agentserver.

java.rmi.RemoteException - Error performing remote method invocation.

startAgent

void startAgent(AgentHandle handle,
                java.lang.String... args)
                throws java.rmi.RemoteException,
                       AgentUnknownException,
                       AgentStartupException

Shortcut for startAgent(handle,false,args)

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentStartupException

See Also:

startAgent

writeCodeSegment

AgentCodeSegment writeCodeSegment(AgentHandle handle,
                                  AgentCodeSegment codeSegment,
                                  byte[] code)
                                  throws java.rmi.RemoteException,
                                         AgentUnknownException,
                                         AgentContainerException

Write contents of a code segment to the agent container.

If no segment existed with the given code segment ID then it is created. Otherwise the previous contents are overwritten by the code passed to this method.

Parameters:

handle - The AgentHandle of the agent to store code for.

codeSegment - Segment identifier to store code.

code - The new contents of the code segment.

Throws:

AgentContainerException - Problem storing data in agent container.

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException - Error performing remote method invocation.

writeCodeSegment

AgentCodeSegment writeCodeSegment(AgentHandle handle,
                                  java.lang.String description,
                                  Language language,
                                  byte[] code)
                                  throws java.rmi.RemoteException,
                                         AgentUnknownException,
                                         AgentContainerException

Shortcut for writeCodeSegment(handle,new AgentCodeSegment(description, language), code).

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentContainerException

See Also:

writeCodeSegment

writeDataSegment

AgentDataSegment writeDataSegment(AgentHandle handle,
                                  AgentDataSegment dataSegment,
                                  byte[] data)
                                  throws java.rmi.RemoteException,
                                         AgentUnknownException,
                                         AgentContainerException

Write bytes to a data segment.

After this method, the bytes are stored in the agent container of the agent belonging to this agent. If a segment with a similar AgentDataSegment existed before this call, then the contents were overwritten with bytes. Data is part of the agent container during its entire lifetime (including migration), except when data is deleted using deleteDataSegment(org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.agent.AgentDataSegment).

Parameters:

handle - The AgentHandle of the agent to write the data to.

dataSegment - Description of the segment to write the data to.

data - The data to write to the segment.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

AgentContainerException - Problem writing data to the agent container.

java.rmi.RemoteException - Error performing remote method invocation.

writeDataSegment

AgentDataSegment writeDataSegment(AgentHandle handle,
                                  java.lang.String description,
                                  java.lang.String subtype,
                                  byte[] data)
                                  throws java.rmi.RemoteException,
                                         AgentUnknownException,
                                         AgentContainerException

Shortcut for writeDataSegment(handle,new AgentDataSegment( description, subtype), data).

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentContainerException

See Also:

writeDataSegment

readCodeSegment

byte[] readCodeSegment(AgentHandle handle,
                       AgentCodeSegment codeSeg)
                       throws java.rmi.RemoteException,
                              SegmentUnknownException,
                              AgentUnknownException,
                              AgentContainerException

Read code segment.

Data is read from the agent container of the agent associated with handle. The data from segment codeSeg is read.

Parameters:

handle - An AgentHandle of the agent to read data from.

codeSeg - Description of the segment to read from.

Returns:

Contents of the segment.

Throws:

AgentContainerException - Problem reading code segment.

SegmentUnknownException - If segment is not known for this agent.

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException - Error performing remote method invocation.

readDataSegment

byte[] readDataSegment(AgentHandle handle,
                       AgentDataSegment dataSeg)
                       throws java.rmi.RemoteException,
                              SegmentUnknownException,
                              AgentUnknownException,
                              AgentContainerException

Read data segment.

Data is read from the agent container of the agent associated with handle. The data from segment dataSeg is read.

Parameters:

handle - An AgentHandle of the agent to read data from.

dataSeg - Description of the segment to read from.

Returns:

Contents of the segment.

Throws:

AgentContainerException - Problem reading data segment.

SegmentUnknownException - If segment is not known for this agent.

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException - Error performing remote method invocation.

setDefaultCodeSegment

void setDefaultCodeSegment(AgentHandle handle,
                           AgentCodeSegment code)
                           throws java.rmi.RemoteException,
                                  AgentUnknownException,
                                  SegmentUnknownException,
                                  AgentContainerException

Set which code segment to run next time the agent starts or moves.

The agent will continue running normally independent of the setting of code segment, but the automatic lease negotiation is dependent on the currently active code segment. So, if you want to move and startup as a different code segment, first call setDefaultCodeSegment and then call move().

By default, if an agent is just created, the first code segment that was written to an agent is set as the default code segment. That is usually good enough. In case you have more code segments, or you want to be sure that the correct one has been set, use this method.

Parameters:

handle - An AgentHandle of the agent to set the code segment.

code - Agent code segment identifier of new active segment.

Throws:

SegmentUnknownException - If segment is not known for this agent.

AgentUnknownException - The AgentHandle is not known in this world.

AgentContainerException - Problem setting default code segment.

java.rmi.RemoteException - Error performing remote method invocation.

listCodeSegments

AgentCodeSegment[] listCodeSegments(AgentHandle handle)
                                    throws java.rmi.RemoteException,
                                           AgentUnknownException,
                                           AgentContainerException

Obtain a list of all code segments stored in the agent container.

Parameters:

handle - Agent identifier.

Returns:

list of all readable code segments of this agent.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException

AgentContainerException

listDataSegments

AgentDataSegment[] listDataSegments(AgentHandle handle)
                                    throws java.rmi.RemoteException,
                                           AgentUnknownException,
                                           AgentContainerException

Obtain a list of all data segments stored in the agent container.

Parameters:

handle - Agent handle.

Returns:

Array of all readable data segments of this agent.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

java.rmi.RemoteException

AgentContainerException

deleteCodeSegment

void deleteCodeSegment(AgentHandle handle,
                       AgentCodeSegment code)
                       throws java.rmi.RemoteException,
                              AgentUnknownException,
                              SegmentUnknownException,
                              AgentContainerException

Delete code segment from agent.

After this call, the data in the deleted segment is not available to the agent anymore. If the default code segment was deleted then a new one must be set manually otherwise any subsequent migration or startup will (most likely) fail.

Parameters:

handle - Agent identifier.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

SegmentUnknownException - Segment unknown.

java.rmi.RemoteException

AgentContainerException

deleteDataSegment

void deleteDataSegment(AgentHandle handle,
                       AgentDataSegment segment)
                       throws java.rmi.RemoteException,
                              AgentUnknownException,
                              SegmentUnknownException,
                              AgentContainerException

Delete data segment from agent.

Throws:

java.rmi.RemoteException

AgentUnknownException

SegmentUnknownException

AgentContainerException

See Also:

deleteCodeSegment(org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.agent.AgentCodeSegment)

moveAgent

void moveAgent(AgentHandle handle,
               AgentScapeID targetLocation)
               throws java.rmi.RemoteException,
                      AgentUnknownException,
                      LocationUnknownException,
                      AgentStartupException,
                      MigrationFailedException

Migrate agent identified with 'handle' to location targetLocation.

Lease negotiation of the target host is done automatically. If the negotiation fails for some reason, then the migration cannot be done.

Parameters:

handle - Agent identifier.

targetLocation - Target location to move to.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

LocationUnknownException - Target location unknown.

NegotiationLibException - No suitable agent host on location.

java.rmi.RemoteException

AgentStartupException

MigrationFailedException

moveAgent

void moveAgent(AgentHandle handle,
               AgentScapeID location,
               java.lang.String leaseId)
               throws java.rmi.RemoteException,
                      NegotiationLibException,
                      AgentUnknownException,
                      AgentStartupException,
                      MigrationFailedException

Migrate agent identified with 'handle' to location as contained in the (previously established) lease.

Parameters:

handle - Agent identifier.

location - Target location to move to.

leaseId - Lease identifier indicating target location.

Throws:

NegotiationLibException - Problem with lease identifier.

AgentUnknownException - The AgentHandle is not known in this world.

AgentStartupException - Agent cannot run on target location.

java.rmi.RemoteException

MigrationFailedException

sendMessage

void sendMessage(Envelope envelope)
                 throws java.rmi.RemoteException,
                        MessageException

Send a message to another agent.

The receiving agent will see as message source the handle that was used to send this message, even though an agent can in practice have more than one handle.

This method is MT-Safe.

Parameters:

envelope - Envelope to send, containing information as to where the envelope should be sent from and to.

Throws:

java.rmi.RemoteException - Error performing remote method invocation.

AgentUnknownException - The AgentHandle is not known in this world.

MessageException - If sending an array of messages fails. The MessageException contains the index of the message that fails and the real exception as the cause. All messages after the exception has occurred will not have been sent; the ones before have been sent.

sendMessages

void sendMessages(java.util.List<Envelope> envelopes)
                  throws java.rmi.RemoteException,
                         MessageException

Throws:

java.rmi.RemoteException

MessageException

See Also:

sendMessage

receiveMessage

Envelope receiveMessage(AgentHandle handle,
                        java.util.List<AgentHandle> handles,
                        boolean block)
                        throws java.rmi.RemoteException,
                               AgentUnknownException

Receive message from queue, addressed to a set of the handles that the agent owns.

An agent can have various handles associated with it. Any handle that the agent owns can be used to call this method. The message that will be received is only one addressed to any one of the handles in the list handles.

This method is MT-safe. However, a message will only be delivered _once_ (i.e., to one thread only) even if multiple threads are trying to receive messages for that particular handle.

Parameters:

handle - Agent identifier to receive from.

handles - List of handles where to receive messages from. This can be used to do a single select for a number of aliases of a single handle.

block - Block waiting for incoming message.

Returns:

Envelope containing payload data and address information.

Throws:

AgentUnknownException - (One of the) agent handle(s) unknown, or not all handles refer to the same agent

java.rmi.RemoteException - Error performing remote method invocation.

receiveMessage

Envelope receiveMessage(AgentHandle handle,
                        boolean block)
                        throws java.rmi.RemoteException,
                               AgentUnknownException

Receive a message from a single handle only.

Throws:

java.rmi.RemoteException

AgentUnknownException

See Also:

receiveMessage(AgentHandle,List,boolean)

receiveMessages

Envelope[] receiveMessages(AgentHandle handle,
                           java.util.List<AgentHandle> handles,
                           boolean block)
                           throws java.rmi.RemoteException,
                                  AgentUnknownException

Receive messages from queue, addressed to some of the handles that the agent owns.

An agent can have various handles associated with it. Any handle that the agent owns can be used to call this method. The messages that will be received are only the ones sent to any of the handles in the list handles.

This method is MT-safe. However, a message will only be delivered _once_ (i.e., to one thread only) even if multiple threads are trying to receive messages for that particular handle.

Parameters:

handle - Agent identifier to receive from.

handles - List of handles where to receive messages from.

block - Block waiting for incoming message.

Returns:

Envelopes containing payload data and address information.

Throws:

AgentUnknownException - (One of the) agent handle(s) unknown, or not all handles refer to the same agent.

java.rmi.RemoteException - Error performing remote method invocation.

exportAgent

AgentArchive exportAgent(AgentHandle handle)
                         throws java.rmi.RemoteException,
                                AgentUnknownException,
                                AgentContainerException

Export current agent state (from agent container) to an AgentArchive.

The current state of the agent segments are stored in the archive, so that we now have a snapshot of the user data and code segments of the agent. This is not the same as finalizing an agent container, but merely a dump of the current state of the agent, so that its contents can be inspected offline. It may even be possible to start a new agent again using the archive obtained from this call.

If possible, also meta information like currently active code segment will be put in the archive. If this information is not found in the agent container, this call will still succeed.

Any changes done to the agent container after this call will not be noticed in the resulting archive.

Parameters:

handle - Agent identifier.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

AgentUnknownException - Agent handle unknown.

java.rmi.RemoteException - Error performing remote method invocation.

AgentContainerException

waitForAgent

AgentArchive waitForAgent(AgentHandle handle,
                          boolean pickup)
                          throws java.rmi.RemoteException,
                                 AgentUnknownException,
                                 AgentContainerException

Wait for agent to be finished, then export it back to the owner as an agent archive.

Parameters:

handle - Agent to wait for.

pickup - If true then the AgentArchive is exported back. Otherwise, this method returns null once the agent finishes.

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentContainerException

listAgents

java.util.HashMap<AgentScapeID,java.util.List<AgentID>> listAgents(AgentScapeID location)
                                                                   throws java.rmi.RemoteException,
                                                                          LocationUnknownException

List all agents running on a particular location.

Note: Only for administrative/debugging purposes.

Parameters:

location - AgentScape location

Returns:

hashmap containing a list of all agents running on a particular location

Throws:

java.rmi.RemoteException

LocationUnknownException

killAgent

void killAgent(AgentHandle handle)
               throws java.rmi.RemoteException,
                      AgentUnknownException

Kill a specific agent.

Parameters:

handle - handle of agent to kill.

Throws:

java.rmi.RemoteException

AgentUnknownException

killAgent

void killAgent(AgentID id)
               throws java.rmi.RemoteException,
                      AgentIDUnknownException

Note: Only for administrative/debugging purposes.

Throws:

java.rmi.RemoteException

AgentIDUnknownException

See Also:

killAgent

listAgentHandles

java.util.List<AgentHandle> listAgentHandles(AgentID id)
                                             throws java.rmi.RemoteException,
                                                    AgentIDUnknownException

List all agenthandles of this agent. Note: Only for administrative/debugging purposes.

Asking an agent handles is actually only permitted by the agent itself (or its owner). AgentID's are not publicly known.

Parameters:

id - AgentID of agent.

Returns:

list of all agent's handles

Throws:

java.rmi.RemoteException

AgentIDUnknownException

register

long register(java.lang.String identifier,
              java.lang.String key,
              java.lang.String value,
              float duration)
              throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException

lookup

java.util.Hashtable<java.lang.String,java.util.Vector<java.util.Vector<java.lang.Object>>> lookup(java.lang.String identifier)
                                                                                                  throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException

find

java.util.Hashtable<java.lang.String,java.util.Hashtable<java.lang.String,java.util.Vector<java.util.Vector<java.lang.Object>>>> find(java.lang.String key,
                                                                                                                                      java.lang.String value)
                                                                                                                                      throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException

list

java.util.Hashtable<java.lang.String,java.util.Hashtable<java.lang.String,java.util.Vector<java.util.Vector<java.lang.Object>>>> list(java.lang.String key)
                                                                                                                                      throws java.rmi.RemoteException

Throws:

java.rmi.RemoteException