org.iids.aos.agent.proxy
Class AgentProxy<T>

java.lang.Object
  org.iids.aos.agent.proxy.AgentProxy<T>

Type Parameters:

T -

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.reflect.InvocationHandler

Direct Known Subclasses:

AuthAgentProxy

public class AgentProxy<T>
extends java.lang.Object
implements java.lang.reflect.InvocationHandler, java.io.Externalizable

Proxy for implementing a class on top of agent messages. Can be used to delegate various services implementations by (remote) agents. Functionally the same as the SystemServiceProxy. This class uses a dynamic proxy to dynamically generate an object the implements the interface for the class.

Note: Only in parameters are supported. In/out and out parameters are not supported.

To bind to a service use the bind(java.lang.Class, org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.systemservices.communicator.structs.AgentHandle, boolean) method. Examples can be found in src/examples/proxy.

Author:

Reinier Timmer (rjtimmer@cs.vu.nl), Michel Oey (michel@cs.vu.nl)

See Also:

Serialized Form

Constructor Summary

	AgentProxy()
protected	AgentProxy(AgentHandle local, AgentHandle remote)
protected	AgentProxy(AgentHandle local, AgentHandle remote, boolean assignNewHandle)

Method Summary

static <T> T	bind(java.lang.Class<T> itfClass, AgentHandle local, AgentHandle remote) The same as bind(itfClass, local, remote, false)
static <T> T	bind(java.lang.Class<T> itfClass, AgentHandle local, AgentHandle remote, boolean assignNewLocal) Bind to a remote agent implementing the interface itfClass.
void	close()
protected void	finalize()
static <T> AgentProxy<T>	getAgentProxy(T proxy) Obtain the underlying AgentProxy of an object that is created through bind(java.lang.Class, org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.systemservices.communicator.structs.AgentHandle, boolean).
AgentHandle	getLocalHandle() Get the handle that is used to connect to the agent service.
AgentHandle	getRemoteHandle() Get the handle of the service this proxy is connected to.
java.lang.Object	invoke(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args) Implementation of InvocationHandler interface.
boolean	isRunning() See if the proxy is still active.
void	readExternal(java.io.ObjectInput in)
void	setCacheableMethod(java.lang.String methodName) This method is similar to setCacheableMethod(methodName, false)
void	setCacheableMethod(java.lang.String methodName, boolean prefetch) Indicate that the results of a method can be cached.
void	setCachedResult(java.lang.String mName, java.lang.Object result)
protected void	setItfClass(java.lang.Class<?> clazz)
protected void	setLocalHandle(AgentHandle local)
protected void	setLocalHandle(AgentHandle local, boolean assignNewHandle)
void	silentClose()
java.lang.String	toString()
void	waitForClose() Wait for someone to close the proxy.
void	writeExternal(java.io.ObjectOutput out)

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AgentProxy

public AgentProxy()

AgentProxy

protected AgentProxy(AgentHandle local,
                     AgentHandle remote)

AgentProxy

protected AgentProxy(AgentHandle local,
                     AgentHandle remote,
                     boolean assignNewHandle)

Method Detail

setLocalHandle

protected void setLocalHandle(AgentHandle local)

setLocalHandle

protected void setLocalHandle(AgentHandle local,
                              boolean assignNewHandle)

getRemoteHandle

public AgentHandle getRemoteHandle()

Get the handle of the service this proxy is connected to.

Returns:

The remote handle this proxy is connected to.

getLocalHandle

public AgentHandle getLocalHandle()

Get the handle that is used to connect to the agent service.

Returns:

The local handle the proxy uses to invoke the handler.

close

public void close()

silentClose

public void silentClose()

isRunning

public boolean isRunning()

See if the proxy is still active. If it is, then it can be used to send invocation requests to the service.

Returns:

true if the proxy is not closed yet, otherwise this method return false.

waitForClose

public void waitForClose()

Wait for someone to close the proxy. Returns only after the proxy is closed.

invoke

public java.lang.Object invoke(java.lang.Object proxy,
                               java.lang.reflect.Method method,
                               java.lang.Object[] args)
                        throws java.lang.Throwable

Implementation of InvocationHandler interface. Sends message invocation to an AgentHandle and waits for result to come back (synchronous invocation model).

Specified by:

invoke in interface java.lang.reflect.InvocationHandler

Throws:

java.lang.Throwable - If the method invocation fails for some reason, the exception of this method is thrown on by this method.

bind

public static <T> T bind(java.lang.Class<T> itfClass,
                         AgentHandle local,
                         AgentHandle remote,
                         boolean assignNewLocal)

Bind to a remote agent implementing the interface itfClass. Communication goes through the supplied agent handles.

This method is encouraged over creating an AgentProxy directly. An object that implements the interface T is returned. Whenever a method is invoked on this object, the message invocation is sent to the remote agent, after which the proxy waits for the reply. When a program uses bind() to connect to the agent, then this is completely transparent.

Once the proxied interface goes out of scope the object is automatically cleaned up. This includes removing of the handle used for the proxy, but only if the handle was automatically assigned by the proxy.

Type Parameters:

T - The type

Parameters:

itfClass - The interface for the proxy to bind to.

local - The local agent handle to use for communication

remote - The remote handle on which the service runs.

assignNewLocal - If true then a local handle is automatically derived from the local handle, and cleaned up after the proxy exits. This is convenient for the times when you don't want to keep track of all the proxied objects. Once the garbage collector cleans up a proxy, the handle is removed.

Returns:

A proxy object which inherits from the given interface class and which forwards the method invocations to the server agent implementing the class.

bind

public static <T> T bind(java.lang.Class<T> itfClass,
                         AgentHandle local,
                         AgentHandle remote)

The same as bind(itfClass, local, remote, false)

Type Parameters:

T - The type of class to bind to.

Parameters:

itfClass - The interface type this proxy will bind to.

local - The local handle used to send invocations.

remote - The remote handle to send invocations to.

Returns:

A proxy using local to invoke remote. The type of the interface the proxy is bound to is of type T.

setItfClass

protected void setItfClass(java.lang.Class<?> clazz)

getAgentProxy

public static <T> AgentProxy<T> getAgentProxy(T proxy)

Obtain the underlying AgentProxy of an object that is created through bind(java.lang.Class, org.iids.aos.systemservices.communicator.structs.AgentHandle, org.iids.aos.systemservices.communicator.structs.AgentHandle, boolean). This may be useful to observe some properties of the proxy, such as the local handle of the proxy.

Type Parameters:

T -

Parameters:

proxy - The proxied object to inspect.

Returns:

The proxy (if any) underlying the object.

setCacheableMethod

public void setCacheableMethod(java.lang.String methodName,
                               boolean prefetch)
                        throws java.lang.Throwable

Indicate that the results of a method can be cached. This only works for parameterless methods. If caching is enabled for a certain method, then the server is contacted only once for the value. Subsequent calls will always be obtained from the cache.

Parameters:

methodName - The name of the method to cache

prefetch - If true then the result value is immediately obtained from the server.

Throws:

java.lang.Throwable

setCacheableMethod

public void setCacheableMethod(java.lang.String methodName)

This method is similar to setCacheableMethod(methodName, false)

Parameters:

methodName -

setCachedResult

public void setCachedResult(java.lang.String mName,
                            java.lang.Object result)

finalize

protected void finalize()

Overrides:

finalize in class java.lang.Object

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException

Specified by:

writeExternal in interface java.io.Externalizable

Throws:

java.io.IOException

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException

Specified by:

readExternal in interface java.io.Externalizable

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object