org.iids.aos.api
Class AgentScapeApiImpl

java.lang.Object
  org.iids.aos.systemservices.module.AbstractModule
      org.iids.aos.api.AgentScapeApiImpl

All Implemented Interfaces:

Module

public class AgentScapeApiImpl
extends AbstractModule

Implementation of the AgentScapeApi.

This class does not directly implement the AgentScapeApi interface (this is implemented by the AgentScapeApiRmiServer. The RMI server (or some other RPC mechanism, like a SunRpc server) receives incoming function calls, and forwards these to this AgentScapeApiImpl.

All functions in this class have exactly the same semantics as the functions in the AgentScapeApi, except for that methods do not throw a RemoteException. Therefore, the JavaDoc documentation can be found in that interface. The methods behave exactly the same.

Author:

rjtimmer

See Also:

AgentScapeApi

Method Summary

AgreementOffer	acceptLease(AgentScapeID location, java.lang.String leaseId)
AgentInfo	createAgent(AgentScapeID location, AgentArchive arch)
AgentInfo	createAgent(AgentScapeID location, Language lang)
AgentInfo	createAgent(AgentScapeID location, Language lang, byte[] code)
AgentInfo	createAgent(java.lang.String lease, AgentArchive arch)
AgentHandle	createAgentHandle(AgentHandle handle)
static AgentScapeApiImpl	createInstance(AgentScapeConfig config, Communicator comm, AsLookupService lookupService) Create instance of the API.
static AgentScapeApiImpl	createPrivateInstance(AgentScapeConfig config, Communicator comm, AsLookupService lookupService) Creates a 'private' instance of the agentscape api.
void	deleteCodeSegment(AgentHandle handle, AgentCodeSegment segment)
void	deleteDataSegment(AgentHandle handle, AgentDataSegment segment)
AgentArchive	exportAgent(AgentHandle handle)
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)
static AgentScapeApiImpl	getInstance() Obtain reference to the AgentScapeApiImpl instance in this JVM.
boolean	isStarted()
void	killAgent(AgentHandle handle)
void	killAgent(AgentID id)
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)
java.util.HashMap<AgentScapeID,java.util.List<AgentID>>	listAgents(AgentScapeID location)
AgentCodeSegment[]	listCodeSegments(AgentHandle handle)
AgentDataSegment[]	listDataSegments(AgentHandle handle)
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)
void	moveAgent(AgentHandle handle, AgentScapeID location, java.lang.String leaseId)
byte[]	readCodeSegment(AgentHandle handle, AgentCodeSegment segment)
byte[]	readDataSegment(AgentHandle handle, AgentDataSegment segment)
Envelope	receiveMessage(AgentHandle handle, boolean block)
Envelope	receiveMessage(AgentHandle handle, java.util.List<AgentHandle> handles, boolean block)
Envelope[]	receiveMessages(AgentHandle handle, java.util.List<AgentHandle> handles, boolean block)
long	register(java.lang.String identifier, java.lang.String key, java.lang.String value, float duration)
AgreementOffer	requestLease(AgentScapeID location, AgreementOffer leaseRequest)
TemplateList	requestTemplates(AgentScapeID location)
void	sendMessage(Envelope envelope)
void	sendMessages(java.util.List<Envelope> envelopes)
void	setDefaultCodeSegment(AgentHandle handle, AgentCodeSegment active)
void	start()
void	startAgent(AgentHandle handle, boolean collect, java.lang.String... args)
void	startAgent(AgentHandle handle, java.lang.String... args)
void	stop()
AgentArchive	waitForAgent(AgentHandle handle, boolean pickup)
AgentCodeSegment	writeCodeSegment(AgentHandle handle, AgentCodeSegment codeSegment, byte[] code)
AgentCodeSegment	writeCodeSegment(AgentHandle handle, java.lang.String description, Language language, byte[] code)
AgentDataSegment	writeDataSegment(AgentHandle handle, AgentDataSegment dataSegment, byte[] data)
AgentDataSegment	writeDataSegment(AgentHandle handle, java.lang.String description, java.lang.String subtype, byte[] data)

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

Method Detail

createInstance

public static AgentScapeApiImpl createInstance(AgentScapeConfig config,
                                               Communicator comm,
                                               AsLookupService lookupService)

Create instance of the API.

After an instance is created once, all threads in the JVM that created the instance can obtain the API by getInstance().

Creating this instance also creates two servers that listen for imcoming method calls, one using java rmi (AgentScapeApiRmiServer) and one using SunRpc (AgentScapeApiSunrpcDispatcher).

TODO: actually, the rmi/sunrpc dispatchers should be created independent of the API, no? I.e. the API should not really be the one to create these servers?

Parameters:

config - AgentScape configuration (from parameter map). Required for creating the rmi server. If it is null, then the rmi server will only be registered using the generic rmi url (which is AgentScapeApi.RMINAME)

comm - Communicator, required for lookup service, and for all AbstractModule implementations.

lookupService - Required for lookup calls (and lookup cache).

Returns:

If the instance was already created before, then the old instance is returned. Else this method returns the newly created instance.

createPrivateInstance

public static AgentScapeApiImpl createPrivateInstance(AgentScapeConfig config,
                                                      Communicator comm,
                                                      AsLookupService lookupService)

Creates a 'private' instance of the agentscape api. This allows you to create multiple instances of the API.

An api created with createInstance(org.iids.aos.systemservices.module.AgentScapeConfig, org.iids.aos.systemservices.communicator.Communicator, org.iids.aos.systemservices.lookupservice.AsLookupService) creates at most one instance (which will always be returned by subsequent calls to createInstance(org.iids.aos.systemservices.module.AgentScapeConfig, org.iids.aos.systemservices.communicator.Communicator, org.iids.aos.systemservices.lookupservice.AsLookupService) and getInstance(). However, this api instance is always bound to the same kernel and lookup service. Should you want to create a new api instance for another dedicated lookup service, then use this method.

This seems a little like a hack? Do not use it unless this is absoultely required?

Another option is to include the lookup server name in the URL that is registered in the AgentScape api. TODO think about this some more.. do we even want multiple lookup services??

getInstance

public static AgentScapeApiImpl getInstance()

Obtain reference to the AgentScapeApiImpl instance in this JVM.

Returns:

The single instance of the AgentScapeApiImpl, or null if the instance was not created before (using createInstance.

register

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

See Also:

AgentScapeApi.register(java.lang.String, java.lang.String, java.lang.String, float)

lookup

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

See Also:

AgentScapeApi.lookup(java.lang.String)

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)

See Also:

AgentScapeApi.find(java.lang.String, java.lang.String)

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)

See Also:

AgentScapeApi.list(java.lang.String)

start

public void start()

stop

public void stop()

isStarted

public boolean isStarted()

createAgent

public AgentInfo createAgent(AgentScapeID location,
                             AgentArchive arch)
                      throws LocationUnknownException,
                             AgentArchiveException,
                             NegotiationLibException,
                             AgentCreationException

Throws:

LocationUnknownException

AgentArchiveException

NegotiationLibException

AgentCreationException

See Also:

AgentScapeApi.createAgent(AgentScapeID,AgentArchive)

createAgent

public AgentInfo createAgent(AgentScapeID location,
                             Language lang)
                      throws LocationUnknownException,
                             AgentCreationException

Throws:

LocationUnknownException

AgentCreationException

See Also:

AgentScapeApi.createAgent(AgentScapeID,Language)

createAgent

public AgentInfo createAgent(AgentScapeID location,
                             Language lang,
                             byte[] code)
                      throws LocationUnknownException,
                             LocationUnknownException,
                             AgentCreationException

Throws:

LocationUnknownException

AgentCreationException

createAgent

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

Throws:

NegotiationLibException

AgentArchiveException

See Also:

AgentScapeApi.createAgent(String,AgentArchive)

createAgentHandle

public AgentHandle createAgentHandle(AgentHandle handle)
                              throws AgentUnknownException

Throws:

AgentUnknownException

See Also:

AgentScapeApi.createAgentHandle(org.iids.aos.systemservices.communicator.structs.AgentHandle)

getAgentHandles

public AgentHandle[] getAgentHandles(AgentHandle handle)
                              throws AgentUnknownException

Throws:

AgentUnknownException

See Also:

AgentScapeApi.getAgentHandles(org.iids.aos.systemservices.communicator.structs.AgentHandle)

requestTemplates

public TemplateList requestTemplates(AgentScapeID location)
                              throws NegotiationLibException,
                                     LocationUnknownException

Throws:

NegotiationLibException

LocationUnknownException

See Also:

AgentScapeApi.requestTemplates(org.iids.aos.systemservices.communicator.structs.AgentScapeID)

requestLease

public AgreementOffer requestLease(AgentScapeID location,
                                   AgreementOffer leaseRequest)
                            throws NegotiationLibException,
                                   LocationUnknownException

Throws:

NegotiationLibException

LocationUnknownException

See Also:

AgentScapeApi.requestLease(org.iids.aos.systemservices.communicator.structs.AgentScapeID, org.iids.aos.systemservices.datatypes.wsagreement.AgreementOffer)

acceptLease

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

Throws:

NegotiationLibException

LocationUnknownException

See Also:

AgentScapeApi.acceptLease(org.iids.aos.systemservices.communicator.structs.AgentScapeID, java.lang.String)

startAgent

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

Throws:

AgentUnknownException

AgentStartupException

See Also:

AgentScapeApi.startAgent(AgentHandle,boolean,String[])

startAgent

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

Throws:

AgentUnknownException

AgentStartupException

See Also:

AgentScapeApi.startAgent(AgentHandle,String[])

writeCodeSegment

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

Throws:

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.writeCodeSegment(AgentHandle,AgentCodeSegment,byte[])

writeCodeSegment

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

Throws:

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.writeCodeSegment(AgentHandle,String,Language,byte[])

writeDataSegment

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

Throws:

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.writeDataSegment(AgentHandle,AgentDataSegment,byte[])

writeDataSegment

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

Throws:

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.writeDataSegment(AgentHandle,String,String,byte[])

readCodeSegment

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

Throws:

SegmentUnknownException

AgentUnknownException

AgentContainerException

See Also:

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

readDataSegment

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

Throws:

SegmentUnknownException

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.readDataSegment(org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.agent.AgentDataSegment)

setDefaultCodeSegment

public void setDefaultCodeSegment(AgentHandle handle,
                                  AgentCodeSegment active)
                           throws AgentUnknownException,
                                  SegmentUnknownException,
                                  AgentContainerException

Throws:

AgentUnknownException

SegmentUnknownException

AgentContainerException

See Also:

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

listCodeSegments

public AgentCodeSegment[] listCodeSegments(AgentHandle handle)
                                    throws AgentUnknownException,
                                           AgentContainerException

Throws:

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.listCodeSegments(org.iids.aos.systemservices.communicator.structs.AgentHandle)

listDataSegments

public AgentDataSegment[] listDataSegments(AgentHandle handle)
                                    throws AgentUnknownException,
                                           AgentContainerException

Throws:

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.listDataSegments(org.iids.aos.systemservices.communicator.structs.AgentHandle)

deleteCodeSegment

public void deleteCodeSegment(AgentHandle handle,
                              AgentCodeSegment segment)
                       throws AgentUnknownException,
                              SegmentUnknownException,
                              AgentContainerException

Throws:

AgentUnknownException

SegmentUnknownException

AgentContainerException

See Also:

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

deleteDataSegment

public void deleteDataSegment(AgentHandle handle,
                              AgentDataSegment segment)
                       throws AgentUnknownException,
                              SegmentUnknownException,
                              AgentContainerException

Throws:

AgentUnknownException

SegmentUnknownException

AgentContainerException

See Also:

AgentScapeApi.deleteDataSegment(org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.agent.AgentDataSegment)

moveAgent

public void moveAgent(AgentHandle handle,
                      AgentScapeID targetLocation)
               throws AgentUnknownException,
                      LocationUnknownException,
                      AgentStartupException,
                      MigrationFailedException

Throws:

AgentUnknownException

LocationUnknownException

AgentStartupException

MigrationFailedException

See Also:

AgentScapeApi.moveAgent(AgentHandle,AgentScapeID)

moveAgent

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

Throws:

NegotiationLibException

AgentUnknownException

AgentStartupException

MigrationFailedException

See Also:

AgentScapeApi.moveAgent(AgentHandle,AgentScapeID,String)

sendMessage

public void sendMessage(Envelope envelope)
                 throws MessageException

Throws:

MessageException

See Also:

AgentScapeApi.sendMessage(org.iids.aos.messagecenter.Envelope)

sendMessages

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

Throws:

MessageException

See Also:

AgentScapeApi.sendMessages(java.util.List)

receiveMessage

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

Throws:

AgentUnknownException

See Also:

AgentScapeApi.receiveMessage(org.iids.aos.systemservices.communicator.structs.AgentHandle, java.util.List, boolean)

receiveMessage

public Envelope receiveMessage(AgentHandle handle,
                               boolean block)
                        throws AgentUnknownException

Throws:

AgentUnknownException

receiveMessages

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

Throws:

AgentUnknownException

See Also:

AgentScapeApi.receiveMessages(org.iids.aos.systemservices.communicator.structs.AgentHandle, java.util.List, boolean)

waitForAgent

public AgentArchive waitForAgent(AgentHandle handle,
                                 boolean pickup)
                          throws AgentUnknownException,
                                 AgentContainerException

Throws:

AgentUnknownException

AgentContainerException

See Also:

AgentScapeApi.waitForAgent(org.iids.aos.systemservices.communicator.structs.AgentHandle, boolean)

exportAgent

public AgentArchive exportAgent(AgentHandle handle)
                         throws AgentUnknownException,
                                AgentContainerException

Throws:

AgentUnknownException

AgentContainerException

listAgents

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

Throws:

LocationUnknownException

See Also:

AgentScapeApi.listAgents(org.iids.aos.systemservices.communicator.structs.AgentScapeID)

killAgent

public void killAgent(AgentHandle handle)
               throws AgentUnknownException

Throws:

AgentUnknownException

See Also:

AgentScapeApi.killAgent(AgentHandle)

killAgent

public void killAgent(AgentID id)
               throws AgentIDUnknownException

Throws:

AgentIDUnknownException

See Also:

AgentScapeApi.killAgent(AgentID)

listAgentHandles

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

Throws:

AgentIDUnknownException

See Also:

AgentScapeApi.listAgentHandles(AgentID)