springs.agent
Interface SpringsAgent

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

SpringsAgent_RMIImpl

public interface SpringsAgent

extends java.io.Serializable

Interface to a Springs agent.

Author:

Sergio Ilarri Artigas

Field Summary

static java.lang.String

METHOD_MESSAGE_RECEPTION

Method Summary

void	addTaskToSchedule(java.lang.String method) Add a task consisting of calling a certain method.
void	addTaskToSchedule(java.lang.String targetURL, int targetPort) Adds a task to travel to another context.
void	addTaskToSchedule(java.lang.String targetURL, int targetPort, java.lang.String callbackMethod) Adds a task to travel to another context.
void	addTaskToSchedule(java.lang.String targetURL, int targetPort, java.lang.String callbackMethod, java.lang.Object[] args) Adds a task to travel to another context.
void	addTaskToSchedule(java.lang.String method, java.lang.Object[] args) Add a task consisting of calling a certain method.
void	afterCreation() Method called just after creating the agent on a certain context.
void	afterRemoval() Method called just after removing the agent from a certain context.
boolean	atHome() Gets if the agent is at home.
void	beforeCreation() Method called just before creating the agent on a certain context.
void	beforeRemoval() Method called just before removing the agent from a certain context.
java.lang.Object	callAgentMethod(java.lang.String targetAgent, java.lang.String methodName) This method invokes a method of the agent.
java.lang.Object	callAgentMethod(java.lang.String targetAgent, java.lang.String methodName, java.lang.Object[] args) This method invokes a method of the agent.
springs.communication.FutureResult	callAgentMethodAsynchronously(java.lang.String targetAgent, java.lang.String methodName) This method invokes a method of the agent asynchronously.
springs.communication.FutureResult	callAgentMethodAsynchronously(java.lang.String targetAgent, java.lang.String methodName, java.lang.Object[] args) This method invokes a method of the agent asynchronously.
void	callback() It executes the callback method after a travel to a new computer.
void	checkpoint() Checkpoints the agent.
springs.context.ContextAddress	getAddress() Gets the address of the agent.
long	getAgentInitializationTime() Gets the millis elapsed in the initialization of the agent.
boolean	getAgentMoving() Gets whether the agent is moving.
java.lang.String	getCodebase() Gets the codebase for the agent, used if the agent travels to another context and some of the classes it uses there are not available.
springs.context.ContextInterfaceForAgents	getContextInterfaceForAgents() Gets an interface to the local context.
java.lang.String	getContextName() Gets the name of the agent's context.
springs.context.ContextAddress	getHomeAddress() Gets the home address of the agent.
java.lang.String	getHostname() Gets the hostname of the agent.
java.util.Vector	getLocationServers() Gets the locationServers for the agent.
long	getMillisStay()
long	getMillisWhenCreated()
java.lang.String	getName() Gets the name of the agent.
java.lang.String	getNameWithContext() Gets the name of the agent, with information about the context.
int	getNumObservers() Gets the number of observers of the agent.
java.util.Vector	getObservers() Gets the observers of the agent.
java.util.Vector	getObserversAddresses() Obtains the addresses of the observers of this agent.
int	getPort() Gets the port of the agent.
springs.agent.Schedule	getSchedule() Return the agent's schedule.
int	getSequenceNumberForAddressUpdateMessages() Obtains a relative indicator used to timestamp messages that update the address of the agent.
java.lang.String	getURL() Gets the URL of the agent.
void	goHome() Moves the agent to its home context (the context where it was created the first time).
void	goHome(java.lang.String callbackMethod) Moves the agent to its home context (the context where it was created the first time).
void	goHome(java.lang.String callbackMethod, java.lang.Object[] args) Moves the agent to its home context (the context where it was created the first time).
java.lang.Object	handleMessage(springs.communication.Message msg) Handles the reception of a message.
void	increaseSequenceNumberForAddressUpdateMessages(int increase) Increases the relative indicator used to timestamp messages that update the address of the agent.
void	initialization() This method is executed only the first time the agent is created.
void	initializationAfterMovement() This method is executed every time after a movement of the agent.
boolean	isSuspended() Obtains if the agent is suspended.
boolean	justCreatedForTheFirstTime() Checks if the agent has just been created for the first time.
void	main() Default callback method.
boolean	moreTasksInSchedule() Checks if the agent has more tasks in its schedule.
void	moveTo(springs.context.ContextAddress contextAddress) Moves the agent to another context.
void	moveTo(springs.context.ContextAddress contextAddress, java.lang.String callbackMethod) Moves the agent to another context.
void	moveTo(springs.context.ContextAddress contextAddress, java.lang.String callbackMethod, java.lang.Object[] args) Moves the agent to another context.
void	moveTo(java.lang.String contextName) Moves the agent to another context.
void	moveTo(java.lang.String contextName, java.lang.String callbackMethod) Moves the agent to another context.
void	moveTo(java.lang.String contextName, java.lang.String callbackMethod, java.lang.Object[] args) Moves the agent to another context.
void	moveToURL(java.lang.String url) Moves the agent to another context.
void	moveToURL(java.lang.String url, int port) Moves the agent to another context.
void	moveToURL(java.lang.String url, int port, java.lang.String callbackMethod) Moves the agent to another context.
void	moveToURL(java.lang.String url, int port, java.lang.String callbackMethod, java.lang.Object[] args) Moves the agent to another context.
void	postArrival() It executes after the agent has arrived at the destination.
void	postDeparture() It executes on the original stale object at the source, and is typically defined to perform activities such as removing the stale object from persistence.
void	preArrival() This method is executed on the copy of the object at the destination.
void	preDeparture(java.lang.String originContext, java.lang.String targetContext) This method is executed on the original object at the source.
java.lang.Object	receiveMethodCall(java.lang.String methodName, java.lang.Object[] args)
void	recordEndStay()
void	recordStartStay()
void	remove() Removes the agent.
void	removeObserver(java.lang.String observer)
springs.communication.FutureResult	sendAsynchronousMessage(java.lang.String targetAgent, springs.communication.Message message) This method sends a message to the agent, asynchronously.
java.lang.Object	sendMessage(java.lang.String targetAgent, springs.communication.Message message) This method sends a message to the agent, synchronously.
java.lang.Object	sendMessage(java.lang.String targetAgent, springs.communication.Message message, boolean asynchronous) This method sends a message to the agent.
void	setAgentInitializationTime(long millis) Sets the millis elapsed in the initialization of the agent.
void	setAgentMoving(boolean moving) Sets whether the agent is moving.
void	setCacheReferences(boolean cacheRefs) Sets whether references to agents should be cached.
void	setCodebase(java.lang.String codebase) Sets the codebase for the agent, that it will be used if the agent travels to another context and some of the classes it uses there are not available.
void	setContextInterfaceForAgents(springs.context.ContextInterfaceForAgents contextInterface) Sets the interface to the agent's context.
void	setHomeAddress(springs.context.ContextAddress homeAddress) Sets the home address of the agent.
void	setLocationServers(java.util.Vector locationServers) Sets the location servers for the agent.
void	setName(java.lang.String name) Sets the name of the agent.
void	start() Starts the agent execution.
void	suspend() Suspends the agent execution.
springs.agent.Task	takeNextTask() Obtains the next task to be executed by the agent, from the schedule.

Field Detail

METHOD_MESSAGE_RECEPTION

public static final java.lang.String METHOD_MESSAGE_RECEPTION

See Also:

Constant Field Values

Method Detail

getMillisWhenCreated

public long getMillisWhenCreated()

recordStartStay

public void recordStartStay()

recordEndStay

public void recordEndStay()

getMillisStay

public long getMillisStay()

setAgentInitializationTime

public void setAgentInitializationTime(long millis)

Sets the millis elapsed in the initialization of the agent.

Parameters:

millis - the millis.

getAgentInitializationTime

public long getAgentInitializationTime()

Gets the millis elapsed in the initialization of the agent.

Returns:

the millis.

setLocationServers

public void setLocationServers(java.util.Vector locationServers)

Sets the location servers for the agent.

getLocationServers

public java.util.Vector getLocationServers()

Gets the locationServers for the agent.

Returns:

the names of the locationServer contexts.

See Also:

Vector

getObservers

public java.util.Vector getObservers()

Gets the observers of the agent.

Returns:

the names of the observer contexts.

See Also:

Vector

getNumObservers

public int getNumObservers()

Gets the number of observers of the agent.

Returns:

the number of observers.

increaseSequenceNumberForAddressUpdateMessages

public void increaseSequenceNumberForAddressUpdateMessages(int increase)

Increases the relative indicator used to timestamp messages that update the address of the agent.

Parameters:

increase - the increase.

getSequenceNumberForAddressUpdateMessages

public int getSequenceNumberForAddressUpdateMessages()

Obtains a relative indicator used to timestamp messages that update the address of the agent.

Returns:

the indicator.

initialization

public void initialization()
                    throws java.lang.Exception

This method is executed only the first time the agent is created. The programmer can override this method to include initialization code. However, make sure to call first the method in the superclass!

Throws:

java.lang.Exception - if error.

See Also:

Exception

initializationAfterMovement

public void initializationAfterMovement()
                                 throws java.lang.Exception

This method is executed every time after a movement of the agent. The programmer can override this method to include initialization code required after a movement. However, make sure to call first the method in the superclass!

Throws:

java.lang.Exception - if error.

See Also:

Exception

justCreatedForTheFirstTime

public boolean justCreatedForTheFirstTime()

Checks if the agent has just been created for the first time.

Returns:

a boolean indicating that.

setCodebase

public void setCodebase(java.lang.String codebase)
                 throws java.net.MalformedURLException

Sets the codebase for the agent, that it will be used if the agent travels to another context and some of the classes it uses there are not available.

Parameters:

codebase - the codebase.

Throws:

java.net.MalformedURLException - if the format of the codebase is incorrect.

See Also:

MalformedURLException

getCodebase

public java.lang.String getCodebase()

Gets the codebase for the agent, used if the agent travels to another context and some of the classes it uses there are not available.

Returns:

codebase the codebase.

See Also:

String

getContextInterfaceForAgents

public springs.context.ContextInterfaceForAgents getContextInterfaceForAgents()

Gets an interface to the local context.

Returns:

an interface to the context.

See Also:

ContextInterfaceForAgents

setContextInterfaceForAgents

public void setContextInterfaceForAgents(springs.context.ContextInterfaceForAgents contextInterface)

Sets the interface to the agent's context.

Parameters:

contextInterface - an interface to the agent's context.

See Also:

ContextInterfaceForAgents

setHomeAddress

public void setHomeAddress(springs.context.ContextAddress homeAddress)

Sets the home address of the agent.

Parameters:

homeAddress - the home address of the agent.

See Also:

ContextAddress

getHomeAddress

public springs.context.ContextAddress getHomeAddress()

Gets the home address of the agent.

Returns:

the home address of the agent.

See Also:

ContextAddress

getAddress

public springs.context.ContextAddress getAddress()

Gets the address of the agent.

Returns:

the address of the agent.

See Also:

ContextAddress

getURL

public java.lang.String getURL()

Gets the URL of the agent.

Returns:

the URL of the agent.

See Also:

String

getContextName

public java.lang.String getContextName()

Gets the name of the agent's context.

Returns:

the name of the agent's context.

See Also:

String

getHostname

public java.lang.String getHostname()

Gets the hostname of the agent.

Returns:

the hostname of the agent.

See Also:

String

getPort

public int getPort()

Gets the port of the agent.

Returns:

the port of the agent's context.

See Also:

ContextAddress

getName

public java.lang.String getName()

Gets the name of the agent.

Returns:

the name of the agent.

See Also:

String

getNameWithContext

public java.lang.String getNameWithContext()

Gets the name of the agent, with information about the context.

Returns:

the name of the agent, with information about the context.

See Also:

String

setName

public void setName(java.lang.String name)

Sets the name of the agent.

Parameters:

name - the name.

See Also:

String

atHome

public boolean atHome()

Gets if the agent is at home.

Returns:

a boolean that indicates whether the agent is at its home context or not.

setCacheReferences

public void setCacheReferences(boolean cacheRefs)

Sets whether references to agents should be cached.

Parameters:

cacheRefs - a boolean indicating that.

getAgentMoving

public boolean getAgentMoving()

Gets whether the agent is moving.

Returns:

a boolean indicating whether the agent is moving or not.

setAgentMoving

public void setAgentMoving(boolean moving)

Sets whether the agent is moving.

Parameters:

moving - a boolean indicating whether the agent is moving or not.

moveTo

public void moveTo(springs.context.ContextAddress contextAddress)
            throws AgentMovementException

Moves the agent to another context. After the movement, the callback method main() will be called.

Parameters:

contextAddress - the address of the target context.

Throws:

AgentMovementException - if the agent cannot be moved to the target address.

See Also:

ContextAddress, AgentMovementException

moveTo

public void moveTo(springs.context.ContextAddress contextAddress,
                   java.lang.String callbackMethod)
            throws AgentMovementException

Moves the agent to another context.

Parameters:

contextAddress - the address of the target context.

callbackMethod - the method to execute on arrival.

Throws:

AgentMovementException - if the agent cannot be moved to the target address.

See Also:

ContextAddress, AgentMovementException, String

moveTo

public void moveTo(springs.context.ContextAddress contextAddress,
                   java.lang.String callbackMethod,
                   java.lang.Object[] args)
            throws AgentMovementException

Moves the agent to another context.

Parameters:

contextAddress - the address of the target context.

callbackMethod - the method to execute on arrival.

args - the arguments of the callback method.

Throws:

AgentMovementException - if the agent cannot be moved to the target address.

See Also:

ContextAddress, AgentMovementException, String, Object

moveToURL

public void moveToURL(java.lang.String url)
               throws AgentMovementException

Moves the agent to another context. After the movement, the callback method main() will be called.

Parameters:

url - the URL of the target context, including the port number.

Throws:

AgentMovementException - if the agent cannot move to the target address.

See Also:

ContextAddress, AgentMovementException

moveToURL

public void moveToURL(java.lang.String url,
                      int port)
               throws AgentMovementException

Moves the agent to another context. After the movement, the callback method main() will be called.

Parameters:

url - the URL of the target context.

port - the port of the target context.

Throws:

AgentMovementException - if the agent cannot move to the target address.

See Also:

ContextAddress, AgentMovementException

moveToURL

public void moveToURL(java.lang.String url,
                      int port,
                      java.lang.String callbackMethod)
               throws AgentMovementException

Moves the agent to another context.

Parameters:

url - the URL of the target context.

port - the port of the target context.

callbackMethod - the method to execute on arrival.

Throws:

AgentMovementException - if the agent cannot move to the target address.

See Also:

ContextAddress, AgentMovementException, String

moveToURL

public void moveToURL(java.lang.String url,
                      int port,
                      java.lang.String callbackMethod,
                      java.lang.Object[] args)
               throws AgentMovementException

Moves the agent to another context.

Parameters:

url - the URL of the target context.

port - the port of the target context.

callbackMethod - the method to execute on arrival.

args - the arguments of the callback method.

Throws:

AgentMovementException - if the agent cannot move to the target address.

See Also:

ContextAddress, AgentMovementException, String, Object

moveTo

public void moveTo(java.lang.String contextName)
            throws AgentMovementException

Moves the agent to another context. After the movement, the callback method main() will be called.

Parameters:

contextName - the name of the context.

Throws:

AgentMovementException - if the agent cannot move to the target context.

See Also:

String, AgentMovementException

moveTo

public void moveTo(java.lang.String contextName,
                   java.lang.String callbackMethod)
            throws AgentMovementException

Moves the agent to another context.

Parameters:

contextName - the name of the context.

callbackMethod - the method to execute on arrival.

Throws:

AgentMovementException - if the agent cannot move to the target context.

See Also:

String, AgentMovementException

moveTo

public void moveTo(java.lang.String contextName,
                   java.lang.String callbackMethod,
                   java.lang.Object[] args)
            throws AgentMovementException

Moves the agent to another context.

Parameters:

contextName - the name of the context.

callbackMethod - the method to execute on arrival.

args - the arguments of the callback method.

Throws:

AgentMovementException - if the agent cannot move to the target context.

See Also:

String, AgentMovementException

goHome

public void goHome()
            throws AgentMovementException

Moves the agent to its home context (the context where it was created the first time). After the movement, the callback method main() will be called.

Throws:

AgentMovementException - if the agent cannot move to the target address.

See Also:

AgentMovementException

goHome

public void goHome(java.lang.String callbackMethod)
            throws AgentMovementException

Moves the agent to its home context (the context where it was created the first time).

Parameters:

callbackMethod - the method to execute on arrival.

Throws:

AgentMovementException - if the agent cannot move to the target address.

See Also:

String, AgentMovementException

goHome

public void goHome(java.lang.String callbackMethod,
                   java.lang.Object[] args)
            throws AgentMovementException

Moves the agent to its home context (the context where it was created the first time).

Parameters:

callbackMethod - the method to execute on arrival.

args - the arguments of the callback method.

Throws:

AgentMovementException - if the agent cannot move to the target address.

See Also:

String, Object, AgentMovementException

callback

public void callback()
              throws MethodCallException

It executes the callback method after a travel to a new computer. If no callback method has been set, the method main() will be called.

Throws:

MethodCallException - if the callback method cannot be invoked.

See Also:

MethodCallException

handleMessage

public java.lang.Object handleMessage(springs.communication.Message msg)

Handles the reception of a message.

Parameters:

msg - the message.

Returns:

the result of handling the message.

See Also:

Object, Message

removeObserver

public void removeObserver(java.lang.String observer)

receiveMethodCall

public java.lang.Object receiveMethodCall(java.lang.String methodName,
                                          java.lang.Object[] args)
                                   throws MethodCallException

MethodCallException

main

public void main()

Default callback method.

start

public void start()

Starts the agent execution.

remove

public void remove()
            throws RemovalException

Removes the agent.

Throws:

RemovalException - if error.

See Also:

RemovalException

getObserversAddresses

public java.util.Vector getObserversAddresses()

Obtains the addresses of the observers of this agent.

Returns:

the addresses of the observers.

See Also:

Vector

beforeCreation

public void beforeCreation()

Method called just before creating the agent on a certain context.

afterCreation

public void afterCreation()

Method called just after creating the agent on a certain context.

beforeRemoval

public void beforeRemoval()

Method called just before removing the agent from a certain context.

afterRemoval

public void afterRemoval()

Method called just after removing the agent from a certain context.

postArrival

public void postArrival()

It executes after the agent has arrived at the destination. At this point the movement is deemed successful.

postDeparture

public void postDeparture()

It executes on the original stale object at the source, and is typically defined to perform activities such as removing the stale object from persistence.

preArrival

public void preArrival()

This method is executed on the copy of the object at the destination.

preDeparture

public void preDeparture(java.lang.String originContext,
                         java.lang.String targetContext)

This method is executed on the original object at the source.

Parameters:

originContext - the origin context.

targetContext - the target context.

See Also:

String

suspend

public void suspend()

Suspends the agent execution.

isSuspended

public boolean isSuspended()

Obtains if the agent is suspended.

Returns:

a boolean indicating whether the agent is suspended.

checkpoint

public void checkpoint()

Checkpoints the agent.

addTaskToSchedule

public void addTaskToSchedule(java.lang.String targetURL,
                              int targetPort)

Adds a task to travel to another context.

Parameters:

targetURL - the target URL.

targetPort - the target port.

See Also:

String

addTaskToSchedule

public void addTaskToSchedule(java.lang.String targetURL,
                              int targetPort,
                              java.lang.String callbackMethod)

Adds a task to travel to another context.

Parameters:

targetURL - the target URL.

targetPort - the target port.

callbackMethod - the callback method.

See Also:

String

addTaskToSchedule

public void addTaskToSchedule(java.lang.String targetURL,
                              int targetPort,
                              java.lang.String callbackMethod,
                              java.lang.Object[] args)

Adds a task to travel to another context.

Parameters:

targetURL - the target URL.

targetPort - the target port.

callbackMethod - the callback method.

args - the arguments for the callback method.

See Also:

String, Object

addTaskToSchedule

public void addTaskToSchedule(java.lang.String method)

Add a task consisting of calling a certain method.

Parameters:

method - the method.

See Also:

String

addTaskToSchedule

public void addTaskToSchedule(java.lang.String method,
                              java.lang.Object[] args)

Add a task consisting of calling a certain method.

Parameters:

method - the method.

args - the arguments for the method.

See Also:

String, Object

moreTasksInSchedule

public boolean moreTasksInSchedule()

Checks if the agent has more tasks in its schedule.

Returns:

a boolean indicating that.

takeNextTask

public springs.agent.Task takeNextTask()

Obtains the next task to be executed by the agent, from the schedule.

Returns:

the next task.

See Also:

Task

getSchedule

public springs.agent.Schedule getSchedule()

Return the agent's schedule.

Returns:

the schedule.

See Also:

Schedule

callAgentMethod

public java.lang.Object callAgentMethod(java.lang.String targetAgent,
                                        java.lang.String methodName,
                                        java.lang.Object[] args)
                                 throws MethodCallException,
                                        CommunicationException

This method invokes a method of the agent.

Parameters:

targetAgent - the name of the target agent.

methodName - the name of the method.

args - the arguments to the method.

Returns:

the result of the method invocation.

Throws:

MethodCallException - if the invocation fails.

CommunicationException - if there is a communication error.

See Also:

MethodCallException, CommunicationException, String, Object

callAgentMethod

public java.lang.Object callAgentMethod(java.lang.String targetAgent,
                                        java.lang.String methodName)
                                 throws MethodCallException,
                                        CommunicationException

This method invokes a method of the agent.

Parameters:

targetAgent - the name of the target agent.

methodName - the name of the method.

Returns:

the result of the method invocation.

Throws:

MethodCallException - if the invocation fails.

CommunicationException - if there is a communication error.

See Also:

CommunicationException, MethodCallException, String, Object

callAgentMethodAsynchronously

public springs.communication.FutureResult callAgentMethodAsynchronously(java.lang.String targetAgent,
                                                                        java.lang.String methodName,
                                                                        java.lang.Object[] args)
                                                                 throws AgentReferenceException

This method invokes a method of the agent asynchronously.

Parameters:

targetAgent - the name of the target agent.

methodName - the name of the method.

args - the arguments to the method.

Returns:

a placeholder for the future result of the invocation.

Throws:

AgentReferenceException - if error.

See Also:

FutureResult, AgentReferenceException, String, Object

callAgentMethodAsynchronously

public springs.communication.FutureResult callAgentMethodAsynchronously(java.lang.String targetAgent,
                                                                        java.lang.String methodName)
                                                                 throws AgentReferenceException

This method invokes a method of the agent asynchronously.

Parameters:

targetAgent - the name of the target agent.

methodName - the name of the method.

Returns:

a placeholder for the future result of the invocation.

Throws:

AgentReferenceException - if error.

See Also:

FutureResult, AgentReferenceException, String, Object

sendMessage

public java.lang.Object sendMessage(java.lang.String targetAgent,
                                    springs.communication.Message message)
                             throws CommunicationException

This method sends a message to the agent, synchronously.

Parameters:

targetAgent - the name of the target agent.

message - the message.

Returns:

a possible result from the target agent.

Throws:

CommunicationException - if there is a communication error.

See Also:

Message, if there is a communication error.

sendAsynchronousMessage

public springs.communication.FutureResult sendAsynchronousMessage(java.lang.String targetAgent,
                                                                  springs.communication.Message message)
                                                           throws CommunicationException

This method sends a message to the agent, asynchronously.

Parameters:

targetAgent - the name of the target agent.

message - the message.

Returns:

a placeholder for the future result from the target agent.

Throws:

CommunicationException - if there is a communication error.

See Also:

FutureResult, Message

sendMessage

public java.lang.Object sendMessage(java.lang.String targetAgent,
                                    springs.communication.Message message,
                                    boolean asynchronous)
                             throws CommunicationException

This method sends a message to the agent.

Parameters:

targetAgent - the name of the target agent.

message - the message.

asynchronous - a boolean indicating whether the message should be sent asynchronously or not.

Returns:

a possible result from the target agent if the message is sent synchronously; a placeholder for the future result if it is sent asynchronously.

Throws:

CommunicationException - if there is a communication error.

See Also:

Message