org.iids.aos.api
Class AgentScapeApiRmiServer

java.lang.Object
  java.rmi.server.RemoteObject
      java.rmi.server.RemoteServer
          java.rmi.server.UnicastRemoteObject
              org.iids.aos.api.AgentScapeApiRmiServer

All Implemented Interfaces:

java.io.Serializable, java.rmi.Remote, AgentScapeApi

public class AgentScapeApiRmiServer
extends java.rmi.server.UnicastRemoteObject
implements AgentScapeApi

See Also:

Serialized Form

Field Summary

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface org.iids.aos.api.AgentScapeApi

RMINAME, 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 segment) 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.
static java.lang.String	getGenericRmiUrl()
static java.lang.String	getHostRmiUrl(AgentScapeConfig config) Will return the host specific RMI url.
static AgentScapeApiRmiServer	getInstance()
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 lease) Migrate agent identified with 'handle' to location as contained in the (previously established) lease.
byte[]	readCodeSegment(AgentHandle handle, AgentCodeSegment segment) Read code segment.
byte[]	readDataSegment(AgentHandle handle, AgentDataSegment segment) 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 active) 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 collect) 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 lang, 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).

Methods inherited from class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getInstance

public static AgentScapeApiRmiServer getInstance()

getGenericRmiUrl

public static java.lang.String getGenericRmiUrl()

getHostRmiUrl

public static java.lang.String getHostRmiUrl(AgentScapeConfig config)

Will return the host specific RMI url. This url is based on the configuration specification: this contains the service type and name to be used in the URL.

Parameters:

config - Configuration to generate host specific URL from

Returns:

A new URL, or null if config == null.

createAgent

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

Description copied from interface: AgentScapeApi

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.

Specified by:

createAgent in interface AgentScapeApi

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:

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

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.

AgentCreationException

createAgent

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

Description copied from interface: AgentScapeApi

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.

Specified by:

createAgent in interface AgentScapeApi

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:

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

LocationUnknownException - Target location unknown.

AgentCreationException

createAgent

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

Description copied from interface: AgentScapeApi

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.

Specified by:

createAgent in interface AgentScapeApi

Parameters:

lease - Pre-negotiated lease for agent.

arch - The contents of the new agent.

Returns:

Information concerning the newly created AgentHandles.

Throws:

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

NegotiationLibException - Lease negotiation error.

AgentArchiveException - Problem with interpreting archive.

createAgentHandle

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

Description copied from interface: AgentScapeApi

Creates new handle (alias) for an existing agent.

Specified by:

createAgentHandle in interface AgentScapeApi

Parameters:

handle - Agent handle to create alias for.

Returns:

New alias AgentHandle for the agent.

Throws:

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

AgentUnknownException - The AgentHandle is not known in this world.

removeAgentHandle

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

Description copied from interface: AgentScapeApi

Remove a handle from an existing agent.

Specified by:

removeAgentHandle in interface AgentScapeApi

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:

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

AgentUnknownException - The AgentHandle is not known in this world.

removeAgentHandle

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

Description copied from interface: AgentScapeApi

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

Specified by:

removeAgentHandle in interface AgentScapeApi

Throws:

java.rmi.RemoteException

AgentUnknownException

See Also:

removeAgentHandle

getAgentHandles

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

Description copied from interface: AgentScapeApi

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.

Specified by:

getAgentHandles in interface AgentScapeApi

Parameters:

handle - An already existing AgentHandle.

Returns:

A newly created AgentHandle associated with this agent.

Throws:

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

AgentUnknownException - The AgentHandle is not known in this world.

requestTemplates

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

Description copied from interface: AgentScapeApi

Request a list of available templates from a location.

Specified by:

requestTemplates in interface AgentScapeApi

Parameters:

location - The location to request the templates from.

Returns:

A list of templates to be used for lease negotiation.

Throws:

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

NegotiationLibException - Any negotiation library exception.

LocationUnknownException - Location unknown.

requestLease

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

Description copied from interface: AgentScapeApi

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

Specified by:

requestLease in interface AgentScapeApi

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:

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

NegotiationLibException - Error with lease negotiation.

LocationUnknownException - Target location unknown.

acceptLease

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

Description copied from interface: AgentScapeApi

Accept lease.

Accept lease offer at location manager.

Specified by:

acceptLease in interface AgentScapeApi

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:

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

NegotiationLibException - Lease negotiation error.

LocationUnknownException - Target location unknown.

startAgent

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

Description copied from interface: AgentScapeApi

Start running the agent.

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

Specified by:

startAgent in interface AgentScapeApi

Parameters:

handle - The agent to run.

collect - Intention to collect agent once it is done.

args - Optional arguments to the agent.

Throws:

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

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.

startAgent

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

Description copied from interface: AgentScapeApi

Shortcut for startAgent(handle,false,args)

Specified by:

startAgent in interface AgentScapeApi

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentStartupException

See Also:

startAgent

killAgent

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

Description copied from interface: AgentScapeApi

Kill a specific agent.

Specified by:

killAgent in interface AgentScapeApi

Parameters:

handle - handle of agent to kill.

Throws:

java.rmi.RemoteException

AgentUnknownException

writeCodeSegment

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

Description copied from interface: AgentScapeApi

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.

Specified by:

writeCodeSegment in interface AgentScapeApi

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:

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

AgentUnknownException - The AgentHandle is not known in this world.

AgentContainerException - Problem storing data in agent container.

writeCodeSegment

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

Description copied from interface: AgentScapeApi

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

Specified by:

writeCodeSegment in interface AgentScapeApi

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentContainerException

See Also:

writeCodeSegment

writeDataSegment

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

Description copied from interface: AgentScapeApi

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 AgentScapeApi.deleteDataSegment(org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.agent.AgentDataSegment).

Specified by:

writeDataSegment in interface AgentScapeApi

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:

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

AgentUnknownException - The AgentHandle is not known in this world.

AgentContainerException - Problem writing data to the agent container.

writeDataSegment

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

Description copied from interface: AgentScapeApi

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

Specified by:

writeDataSegment in interface AgentScapeApi

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentContainerException

See Also:

writeDataSegment

readCodeSegment

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

Description copied from interface: AgentScapeApi

Read code segment.

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

Specified by:

readCodeSegment in interface AgentScapeApi

Parameters:

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

segment - Description of the segment to read from.

Returns:

Contents of the segment.

Throws:

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

SegmentUnknownException - If segment is not known for this agent.

AgentUnknownException - The AgentHandle is not known in this world.

AgentContainerException - Problem reading code segment.

readDataSegment

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

Description copied from interface: AgentScapeApi

Read data segment.

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

Specified by:

readDataSegment in interface AgentScapeApi

Parameters:

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

segment - Description of the segment to read from.

Returns:

Contents of the segment.

Throws:

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

SegmentUnknownException - If segment is not known for this agent.

AgentUnknownException - The AgentHandle is not known in this world.

AgentContainerException - Problem reading data segment.

setDefaultCodeSegment

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

Description copied from interface: AgentScapeApi

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.

Specified by:

setDefaultCodeSegment in interface AgentScapeApi

Parameters:

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

active - Agent code segment identifier of new active segment.

Throws:

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

AgentUnknownException - The AgentHandle is not known in this world.

SegmentUnknownException - If segment is not known for this agent.

AgentContainerException - Problem setting default code segment.

listCodeSegments

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

Description copied from interface: AgentScapeApi

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

Specified by:

listCodeSegments in interface AgentScapeApi

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

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

Description copied from interface: AgentScapeApi

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

Specified by:

listDataSegments in interface AgentScapeApi

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

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

Description copied from interface: AgentScapeApi

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.

Specified by:

deleteCodeSegment in interface AgentScapeApi

Parameters:

handle - Agent identifier.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

SegmentUnknownException - Segment unknown.

java.rmi.RemoteException

AgentContainerException

deleteDataSegment

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

Description copied from interface: AgentScapeApi

Delete data segment from agent.

Specified by:

deleteDataSegment in interface AgentScapeApi

Throws:

java.rmi.RemoteException

AgentUnknownException

SegmentUnknownException

AgentContainerException

See Also:

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

moveAgent

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

Description copied from interface: AgentScapeApi

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.

Specified by:

moveAgent in interface AgentScapeApi

Parameters:

handle - Agent identifier.

targetLocation - Target location to move to.

Throws:

AgentUnknownException - The AgentHandle is not known in this world.

LocationUnknownException - Target location unknown.

java.rmi.RemoteException

AgentStartupException

MigrationFailedException

moveAgent

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

Description copied from interface: AgentScapeApi

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

Specified by:

moveAgent in interface AgentScapeApi

Parameters:

handle - Agent identifier.

location - Target location to move to.

lease - 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

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

Description copied from interface: AgentScapeApi

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.

Specified by:

sendMessage in interface AgentScapeApi

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.

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

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

Specified by:

sendMessages in interface AgentScapeApi

Throws:

java.rmi.RemoteException

MessageException

See Also:

sendMessage

receiveMessage

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

Description copied from interface: AgentScapeApi

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.

Specified by:

receiveMessage in interface AgentScapeApi

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:

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

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

receiveMessage

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

Description copied from interface: AgentScapeApi

Receive a message from a single handle only.

Specified by:

receiveMessage in interface AgentScapeApi

Throws:

java.rmi.RemoteException

AgentUnknownException

See Also:

AgentScapeApi.receiveMessage(AgentHandle,List,boolean)

receiveMessages

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

Description copied from interface: AgentScapeApi

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.

Specified by:

receiveMessages in interface AgentScapeApi

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:

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

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

waitForAgent

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

Description copied from interface: AgentScapeApi

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

Specified by:

waitForAgent in interface AgentScapeApi

Parameters:

handle - Agent to wait for.

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

Throws:

java.rmi.RemoteException

AgentUnknownException

AgentContainerException

exportAgent

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

Description copied from interface: AgentScapeApi

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.

Specified by:

exportAgent in interface AgentScapeApi

Parameters:

handle - Agent identifier.

Throws:

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

AgentUnknownException - The AgentHandle is not known in this world.

AgentContainerException

listAgents

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

Description copied from interface: AgentScapeApi

List all agents running on a particular location.

Note: Only for administrative/debugging purposes.

Specified by:

listAgents in interface AgentScapeApi

Parameters:

location - AgentScape location

Returns:

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

Throws:

java.rmi.RemoteException

LocationUnknownException

killAgent

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

Description copied from interface: AgentScapeApi

Note: Only for administrative/debugging purposes.

Specified by:

killAgent in interface AgentScapeApi

Throws:

java.rmi.RemoteException

AgentIDUnknownException

See Also:

killAgent

listAgentHandles

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

Description copied from interface: AgentScapeApi

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.

Specified by:

listAgentHandles in interface AgentScapeApi

Parameters:

id - AgentID of agent.

Returns:

list of all agent's handles

Throws:

java.rmi.RemoteException

AgentIDUnknownException

register

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

Specified by:

register in interface AgentScapeApi

Throws:

java.rmi.RemoteException

lookup

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

Specified by:

lookup in interface AgentScapeApi

Throws:

java.rmi.RemoteException

find

public 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

Specified by:

find in interface AgentScapeApi

Throws:

java.rmi.RemoteException

list

public 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

Specified by:

list in interface AgentScapeApi

Throws:

java.rmi.RemoteException