springs.access
Class AgentReference

java.lang.Object
  |
  +--springs.access.AgentReference

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class AgentReference

extends java.lang.Object

implements java.io.Serializable, java.lang.Cloneable

A reference to an agent.

Author:

Sergio Ilarri Artigas

See Also:

Serialized Form

Field Summary

private java.lang.Object	_agent An RMI interface to the remote object.
private boolean	_agentIsMoving A boolean indicating whether the agent is moving (in this case, the reference should not be used until updated).
private java.lang.String	_agentName The name of the agent.
private springs.context.ContextAddress	_contextAddress The address of the agent context.
private boolean	_isLocationServer A boolean indicating whether the reference can be removed from the local references to agents.
private long	_millisMustBeRemoved
private long	_millisWhenCreated
private boolean	_mustBeRemoved A boolean indicating whether the reference should be removed.
private int	_seqNum A number to identify the sequence number for the current address of the agent.

Constructor Summary

AgentReference(springs.context.ContextAddress contextAddress, java.lang.String agentName, int seqNum, boolean isLocationServer, boolean mustBeRemoved, long millisWhenCreated)
Constructor.

Method Summary

static java.lang.Object	callAgentMethod(java.lang.String agentName, java.lang.String methodName, java.lang.Object[] args, boolean cacheRef, java.lang.String caller) This method invokes a method of the agent.
static springs.communication.FutureResult	callAgentMethodAsynchronously(java.lang.String agentName, java.lang.String methodName, java.lang.Object[] args, boolean cacheRef, java.lang.String caller) This method invokes a method of the agent.
java.lang.Object	callOnReference(java.lang.String methodName, java.lang.Object[] args, java.lang.String caller) This method invokes a method of the agent.
java.lang.Object	clone()
boolean	getAgentIsMoving() Checks whether the agent is moving.
java.lang.String	getAgentName() Obtains the name of the agent pointed to by this reference.
java.lang.Object	getAgentObject() Obtains the object that refers to the agent.
springs.context.ContextAddress	getContextAddress() Gets the address of the context pointed to by the reference.
boolean	getIsLocationServer() Obtains whether the reference can be removed from the local references to agents.
long	getMillisWhenCreated() Gets the milliseconds when the agent this reference points to was created.
private static java.lang.Object	getResultOfRetryingAgentInvoking(springs.access.RetryingAgentInvoking retrying) Obtains the result of the retrying task.
int	getSeqNum() Gets the sequence number.
boolean	mustBeRemoved() Checks whether the reference must be removed.
void	nullifyAgentObject() Nullifies the agent object.
static java.lang.Object	sendMessage(java.lang.String agentName, springs.communication.Message message, boolean asynchronous, boolean cacheRef, java.lang.String caller) This method sends a message to the agent.
void	setAgentIsMoving(boolean moving) Sets whether the agent is moving.
private void	setAgentObject() Sets the object that refers to the agent.
void	setIsLocationServer(boolean isLocationServer) Sets whether the reference can be removed from the local references to agents.
void	setMustBeRemoved(boolean must) Marks the reference as a reference that should be removed.
void	update(int seqNum, springs.context.ContextAddress ca, long millisWhenCreated) Updates the reference with the given data.
void	waitUntilUpdated(int seqNum, long timeout) Blocks until the reference is updated.

Methods inherited from class java.lang.Object

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

Field Detail

_contextAddress

private springs.context.ContextAddress _contextAddress

The address of the agent context.

See Also:

ContextAddress

_agentName

private java.lang.String _agentName

The name of the agent. Also the time instant (in millis) when the agent was created.

See Also:

String

_millisWhenCreated

private long _millisWhenCreated

_agent

private java.lang.Object _agent

An RMI interface to the remote object.

See Also:

Object

_seqNum

private int _seqNum

A number to identify the sequence number for the current address of the agent.

_isLocationServer

private boolean _isLocationServer

A boolean indicating whether the reference can be removed from the local references to agents.

_mustBeRemoved

private boolean _mustBeRemoved

A boolean indicating whether the reference should be removed.

_millisMustBeRemoved

private long _millisMustBeRemoved

_agentIsMoving

private boolean _agentIsMoving

A boolean indicating whether the agent is moving (in this case, the reference should not be used until updated).

Constructor Detail

AgentReference

public AgentReference(springs.context.ContextAddress contextAddress,
                      java.lang.String agentName,
                      int seqNum,
                      boolean isLocationServer,
                      boolean mustBeRemoved,
                      long millisWhenCreated)

Constructor.

Parameters:

contextAddress - the context address.

agentName - the agent's name.

seqNum - a number to identify the sequence number for the current address of the agent.

isLocationServer - a boolean indicating whether the reference can be removed from the local references to agents.

mustBeRemoved - a boolean indicating whether the reference must be removed.

millisWhenCreated - the time instant (in millis) when the agent was created.

See Also:

ContextAddress, String

Method Detail

getMillisWhenCreated

public long getMillisWhenCreated()

Gets the milliseconds when the agent this reference points to was created.

Returns:

the milliseconds.

setMustBeRemoved

public void setMustBeRemoved(boolean must)

Marks the reference as a reference that should be removed.

mustBeRemoved

public boolean mustBeRemoved()

Checks whether the reference must be removed.

Returns:

a boolean indicating that.

getIsLocationServer

public boolean getIsLocationServer()

Obtains whether the reference can be removed from the local references to agents.

Returns:

a boolean indicating that.

setIsLocationServer

public void setIsLocationServer(boolean isLocationServer)

Sets whether the reference can be removed from the local references to agents.

Parameters:

isLocationServer - a boolean indicating that.

getAgentName

public java.lang.String getAgentName()

Obtains the name of the agent pointed to by this reference.

Returns:

the name of the agent.

See Also:

String

getContextAddress

public springs.context.ContextAddress getContextAddress()

Gets the address of the context pointed to by the reference.

Returns:

the address of the context.

See Also:

ContextAddress

callOnReference

public java.lang.Object callOnReference(java.lang.String methodName,
                                        java.lang.Object[] args,
                                        java.lang.String caller)
                                 throws CommunicationException

This method invokes a method of the agent.

Parameters:

methodName - the name of the method.

args - the arguments to the method.

caller - the name of the caller agent.

Returns:

the result of the method invocation.

Throws:

CommunicationException - if the invocation fails.

See Also:

String, Object, CommunicationException

callAgentMethod

public static java.lang.Object callAgentMethod(java.lang.String agentName,
                                               java.lang.String methodName,
                                               java.lang.Object[] args,
                                               boolean cacheRef,
                                               java.lang.String caller)
                                        throws CommunicationException

This method invokes a method of the agent.

Parameters:

agentName - the name of the agent.

methodName - the name of the method.

args - the arguments to the method.

cacheRef - a boolean indicating whether the reference to the agent should be cached.

caller - the name of the caller agent.

Returns:

the result of the method invocation.

Throws:

CommunicationException - if the invocation fails.

See Also:

String, Object, CommunicationException

callAgentMethodAsynchronously

public static springs.communication.FutureResult callAgentMethodAsynchronously(java.lang.String agentName,
                                                                               java.lang.String methodName,
                                                                               java.lang.Object[] args,
                                                                               boolean cacheRef,
                                                                               java.lang.String caller)
                                                                        throws AgentReferenceException

This method invokes a method of the agent.

Parameters:

agentName - the name of the agent.

methodName - the name of the method.

args - the arguments to the method.

cacheRef - a boolean indicating whether the reference to the agent should be cached.

caller - the name of the caller agent.

Returns:

a placeholder for the future result of the invocation.

Throws:

AgentReferenceException - if error.

See Also:

FutureResult, String, Object, AgentReferenceException

sendMessage

public static java.lang.Object sendMessage(java.lang.String agentName,
                                           springs.communication.Message message,
                                           boolean asynchronous,
                                           boolean cacheRef,
                                           java.lang.String caller)
                                    throws CommunicationException

This method sends a message to the agent.

Parameters:

agentName - the agent's name.

message - the message.

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

cacheRef - a boolean indicating whether the reference to the agent should be cached.

caller - the name of the caller agent.

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 the message cannot be sent.

See Also:

Object, Message, CommunicationException

update

public void update(int seqNum,
                   springs.context.ContextAddress ca,
                   long millisWhenCreated)

Updates the reference with the given data.

Parameters:

seqNum - the new sequence number.

ca - the new context address.

millisWhenCreated - the time instant (in millis) when the agent was created.

See Also:

ContextAddress

waitUntilUpdated

public void waitUntilUpdated(int seqNum,
                             long timeout)

Blocks until the reference is updated.

Parameters:

seqNum - the initial sequence number.

timeout - the maximum number of milliseconds to wait.

setAgentIsMoving

public void setAgentIsMoving(boolean moving)

Sets whether the agent is moving.

Parameters:

moving - a boolean indicating that.

getAgentIsMoving

public boolean getAgentIsMoving()

Checks whether the agent is moving.

Returns:

a boolean indicating that.

getAgentObject

public java.lang.Object getAgentObject()
                                throws AgentReferenceException

Obtains the object that refers to the agent. This method is private to avoid an acesss to the target object from outside. A direct access from outside would prevent the automatic retrying mechanism from working. By declaring this method private we also avoid having to deal with remote interfaces.

Returns:

the object that refers to the agent.

Throws:

AgentReferenceException - if error.

See Also:

Object, AgentReferenceException

nullifyAgentObject

public void nullifyAgentObject()

Nullifies the agent object.

getSeqNum

public int getSeqNum()

Gets the sequence number.

Returns:

the sequence number.

getResultOfRetryingAgentInvoking

private static java.lang.Object getResultOfRetryingAgentInvoking(springs.access.RetryingAgentInvoking retrying)
                                                          throws CommunicationException

Obtains the result of the retrying task.

Parameters:

retrying - the retrying task.

Returns:

the result.

Throws:

CommunicationException - if error.

See Also:

Object, CommunicationException

setAgentObject

private void setAgentObject()
                     throws AgentReferenceException

Sets the object that refers to the agent.

Throws:

AgentReferenceException - if error.

See Also:

AgentReferenceException

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Overrides:

clone in class java.lang.Object

java.lang.CloneNotSupportedException