RMIVariables

package saker.build.thirdparty.saker.rmi.connection

public class RMIVariables implements AutoCloseable

saker.build.thirdparty.saker.rmi.connection.RMIVariables

java.lang.Object

java.lang.AutoCloseable

Class for enclosing RMI proxies, referenced objects, and providing invocation functionality for the RMI runtime.

The resposibility of the variables context is to provide access to the objects present in the RMI connection. Each remote object can be bound to only a specific variables context, and any method invocation on it will be done through its context.

The purpose of this class is to enclose series of requests and operations in a container and providing functionality in regards with these objects. By enclosing them in a container, the callers are able to simply release the resources after a series of requests. E.g. a client connects to a server, and makes method calls on given proxy objects. After the client is done, it can close the used variables context, and all associated resource can be freed both on the client and on the server. This means that the connection will no longer hold references to no longer used remote objects, and this can speed up the freeing of objects for persistent connections.

The variables context provides distributed GC (Garbage Collection) features, which means that if a proxy object is no longer referenced on the other endpoint, then it may be garbage collected by the JVM on the local endpoint. The variables context will reference the passed objects strongly, until it is no longer referenced on the other endpoint.

The variables context will create the proxy objects by generating appropriate bytecode based on the configured RMITransferProperties. These classes are defined in an internal classloader. Interfaces used in an RMI connection should always have public visibility.

The variables need to be closed after they've been used. Calling close() will flag the variables as closed, and the closing will happen when there are no more running requests in it.

RMIConnection

RMITransferProperties

Methods

public void	close() Closes this RMI variables.
public RMIConnection	getConnection() Gets the RMI connection this variables context is used with.
public Object	getRemoteContextVariable(String variablename) Gets a named remote variable from the other RMI endpoint.
public Object	invokeContextVariableMethod(String variablename, Method method, Object... arguments) Invokes the given method on the remote context variable with the specified name.
public Object	invokeContextVariableMethod(String variablename, MethodTransferProperties method, Object... arguments) Invokes the given method on the remote context variable with the specified name.
public static Object	invokeMethod(Object remoteobject, Method method, Object... arguments) Invokes the specified method on the given remote object with the passed arguments.
public static Object	invokeMethod(Object remoteobject, MethodTransferProperties method, Object... arguments) Invokes the specified method on the given remote object with the passed arguments.
public static Object	invokeRemoteMethod(Object remoteobject, Method method, Object... arguments) Invokes the specified method remotely on the given remote object with the passed arguments.
public static Object	invokeRemoteMethod(Object remoteobject, MethodTransferProperties method, Object... arguments) Invokes the specified method remotely on the given remote object with the passed arguments.
public static void	invokeRemoteMethodAsync(Object remoteobject, Method method, Object... arguments) Asynchronously invokes the speified method remotely on the given remote object with the passed arguments.
public static void	invokeRemoteMethodAsync(Object remoteobject, MethodTransferProperties method, Object... arguments) Asynchronously invokes the speified method remotely on the given remote object with the passed arguments.
public static void	invokeRemoteMethodAsyncOrLocal(Object object, Method method, Object... arguments) Same as invokeRemoteMethodAsync(Object, Method, Object...), but handles if the object is not remote.
public static void	invokeRemoteMethodAsyncOrLocal(Object object, MethodTransferProperties method, Object... arguments) Same as invokeRemoteMethodAsync(Object, MethodTransferProperties, Object...), but handles if the object is not remote.
public Object	invokeRemoteStaticMethod(Method method, Object... arguments) Invokes a static method with the given arguments.
public Object	invokeRemoteStaticMethod(MethodTransferProperties method, Object... arguments) Invokes a static method with the given arguments.
public boolean	isAborting() Checks if this variables context is aborting.
public boolean	isClosed() Checks if this variables context is closed.
public Object	newRemoteInstance(Class<?> type) Creates a new instance of the given class on the remote endpoint, and returns it as a remote object.
public Object	newRemoteInstance(Constructor<?> constructor, Object... arguments) Creates a new instance on the remote endpoint, and returns it as a remote object.
public Object	newRemoteInstance(ConstructorTransferProperties<?> constructor, Object... arguments) Creates a new instance on the remote endpoint, and returns it as a remote object.
public Object	newRemoteOnlyInstance(Object remoteclassloader, String classname) Creates a new object on the remote endpoint and returns it as a remote proxy object.
public Object	newRemoteOnlyInstance(Object remoteclassloader, String classname, String[] constructorargumentclasses, Object[] constructorarguments) Creates a new object on the remote endpoint and returns it as a remote proxy object.
public Object	newRemoteOnlyInstance(String classname) Creates a new object on the remote endpoint and returns it as a remote proxy object.
public Object	newRemoteOnlyInstance(String classname, String[] constructorargumentclasses, Object[] constructorarguments) Creates a new object on the remote endpoint and returns it as a remote proxy object.
public String	toString() Returns a string representation of the object.
public void	waitClosure() Waits for this RMI variables to get closed, and all request to be finished.

Inherited methods
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

public void close()

Closes this RMI variables.

Closing of a variables context occurs asynchronously. All concurrent requests will be finished, and then the variables will be completely closed. When that occurs, no more remote method calls can be instantiated through it.

Closing this instance will cause the corresponding RMIVariables to be closed on the other endpoint as well.

This method never throws an exception.

public RMIConnection getConnection()

Gets the RMI connection this variables context is used with.

The connection.

public Object getRemoteContextVariable(String variablename) throws RMIIOFailureException, IllegalArgumentException

Gets a named remote variable from the other RMI endpoint.

The remote variable is always retrieved as a remote proxy. No exceptions to this, transfer properties are not taken into account.

The RMIVariables instance doesn't cache the remote context variables by name. This function will always make a request to the remote endpoint to get the variable.

variablenameThe name of the variable.

The found remote variable or null if it is not set.

RMIIOFailureExceptionIn case of I/O error.

IllegalArgumentExceptionIf the given variable name is too long, and cannot be encoded via UTF-8 into less than 65536 bytes.

RMIConnection.putContextVariable(String, Object)

public Object invokeContextVariableMethod(String variablename, Method method, Object... arguments) throws RMIRuntimeException, InvocationTargetException, RMIContextVariableNotFoundException

Invokes the given method on the remote context variable with the specified name.

The method will invoke a remote method on the given context variable. The advantage of this is that it can be done in a single rather than first retrieving the variable using getRemoteContextVariable(String) and later calling the method, which would require two request to the other endpoint.

In addition, this method will not take the behavioural configuration of the given method into account. That is, only the object transfer properties from the method configuration are relevant.
Default implementations are not called, method redirections are not invoked, call results are not cached, and exceptions are not rethrown. The method is not checked if it is forbidden, and will be called remotely regardless.

variablenameThe name of the variable.

methodThe method to call.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

RMIContextVariableNotFoundExceptionIf the context variable with the given name was not found on the other endpoint

invokeContextVariableMethod(String, MethodTransferProperties, Object...)

saker.rmi 0.8.3

public Object invokeContextVariableMethod(String variablename, MethodTransferProperties method, Object... arguments) throws RMIRuntimeException, InvocationTargetException, RMIContextVariableNotFoundException, IllegalArgumentException

Invokes the given method on the remote context variable with the specified name.

variablenameThe name of the variable.

methodThe method to call.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

RMIContextVariableNotFoundExceptionIf the context variable with the given name was not found on the other endpoint.

IllegalArgumentExceptionIf the given variable name is too long, and cannot be encoded via UTF-8 into less than 65536 bytes.

saker.rmi 0.8.3

public static Object invokeMethod(Object remoteobject, Method method, Object... arguments) throws RMIRuntimeException, InvocationTargetException, IllegalArgumentException

Invokes the specified method on the given remote object with the passed arguments.

The method transfer properties will be determined based on the RMI connection configuration. Default implementations are not called, call results are not cached, and exceptions are not rethrown.

Method redirections are invoked accordingly, and if the method is forbidden to be called remotely, an exception will be thrown.

The return value will be transferred based on the associated method transfer properties for the other endpoint.

remoteobjectThe remote object.

methodThe method to call.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

IllegalArgumentExceptionIf the argument is not a remote object.

invokeMethod(Object, MethodTransferProperties, Object...)

RMIOptions.allowDirectRequests(boolean)

public static Object invokeMethod(Object remoteobject, MethodTransferProperties method, Object... arguments) throws RMIRuntimeException, InvocationTargetException, IllegalArgumentException

Invokes the specified method on the given remote object with the passed arguments.

The passed transfer properties will be used when transferring the objects. Default implementations are not called, call results are not cached, and exceptions are not rethrown.

Method redirections are invoked accordingly, and if the method is forbidden to be called remotely, an exception will be thrown.

The return value will be transferred based on the associated method transfer properties for the other endpoint.

remoteobjectThe remote object.

methodThe method to call.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

IllegalArgumentExceptionIf the argument is not a remote object.

RMIOptions.allowDirectRequests(boolean)

public static Object invokeRemoteMethod(Object remoteobject, Method method, Object... arguments) throws RMIRuntimeException, InvocationTargetException, IllegalArgumentException

Invokes the specified method remotely on the given remote object with the passed arguments.

The method transfer properties will be determined based on the RMI connection configuration. Default implementations are not called, method redirections are not invoked, call results are not cached, and exceptions are not rethrown.

If the method is forbidden to be called remotely, an exception will be thrown.

The return value will be transferred based on the associated method transfer properties for the other endpoint.

remoteobjectThe remote object.

methodThe method to call.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

IllegalArgumentExceptionIf the argument is not a remote object.

invokeRemoteMethod(Object, MethodTransferProperties, Object...)

RMIOptions.allowDirectRequests(boolean)

public static Object invokeRemoteMethod(Object remoteobject, MethodTransferProperties method, Object... arguments) throws RMIRuntimeException, InvocationTargetException, IllegalArgumentException

Invokes the specified method remotely on the given remote object with the passed arguments.

The passed transfer properties will be used when transferring the objects. Default implementations are not called, method redirections are not invoked, call results are not cached, and exceptions are not rethrown.

If the method is forbidden to be called remotely, an exception will be thrown.

The return value will be transferred based on the associated method transfer properties for the other endpoint.

remoteobjectThe remote object.

methodThe method to call.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

IllegalArgumentExceptionIf the argument is not a remote object.

RMIOptions.allowDirectRequests(boolean)

public static void invokeRemoteMethodAsync(Object remoteobject, Method method, Object... arguments) throws RMIIOFailureException, RMIObjectTransferFailureException, IllegalArgumentException

Asynchronously invokes the speified method remotely on the given remote object with the passed arguments.

Asynchronous invocation means that this method will not wait for the remote method execution to complete, and may return before the invocation request even arrives at the other endpoint. The return value of the invocation will not be transferred back to the caller. There will be no notification if the method invocation finished, completed, or failed.

The caller cannot be sure that the method was ever invoked at any point during the lifetime of the RMI connection. It may happen that the invocation request never arrives before the closing or abrupt disconnection of this connection.

If the remote endpoint fails to read the argument objects or the method execution fails, the resulting exception is silently ignored.

However, if the asynchronous method invocation fails due to the network connection breaking up, then the client can be sure that any pending, or subsequent invocations will eventually throw an appropriate RMI exception signalling the abrupt disconnection.

It is recommended that clients use asynchronous invocation only for notification purposes, where it is unnecessary to block the caller by waiting for the response. It is recommended to externally synchronize on some state to ensure that the asynchronous invocation actually went through. It is also recommended to properly test and debug any transfer errors that might occur during invocations. In order to avoid transfer errors, it is recommended to only use void no-arg methods.

If the method is forbidden to be called remotely, an exception will be thrown.

The return value or exceptions are not transferred.

remoteobjectThe remote object to invoke the method on.

methodThe method to invoke.

argumentsThe arguments to pass to the invoked method.

RMIIOFailureExceptionIn case of I/O error.

RMIObjectTransferFailureExceptionIf writing the arguments fail.

IllegalArgumentExceptionIf the object is not a remote proxy.

public static void invokeRemoteMethodAsync(Object remoteobject, MethodTransferProperties method, Object... arguments) throws RMIIOFailureException, RMIObjectTransferFailureException, IllegalArgumentException

Asynchronously invokes the speified method remotely on the given remote object with the passed arguments.

See invokeRemoteMethodAsync(Object, Method, Object...) for more information.

remoteobjectThe remote object to invoke the method on.

methodThe method to invoke.

argumentsThe arguments to pass to the invoked method.

RMIIOFailureExceptionIn case of I/O error.

RMIObjectTransferFailureExceptionIf writing the arguments fail.

IllegalArgumentExceptionIf the object is not a remote proxy.

public static void invokeRemoteMethodAsyncOrLocal(Object object, Method method, Object... arguments) throws RMIIOFailureException, RMIObjectTransferFailureException, InvocationTargetException, IllegalAccessException, IllegalArgumentException

Same as invokeRemoteMethodAsync(Object, Method, Object...), but handles if the object is not remote.

If the object is not remote, then the method will be called without any RMI transferring.

objectThe object to invoke the method on.

methodThe method to invoke.

argumentsThe arguments to pass to the invoked method.

RMIIOFailureExceptionIn case of I/O error.

RMIObjectTransferFailureExceptionIf writing the arguments fail.

InvocationTargetExceptionIf the local method invocation throws an exception.

IllegalAccessExceptionIf the local method invocation throws an exception.

IllegalArgumentExceptionIf the local method invocation throws an exception.

public static void invokeRemoteMethodAsyncOrLocal(Object object, MethodTransferProperties method, Object... arguments) throws RMIIOFailureException, RMIObjectTransferFailureException, InvocationTargetException, IllegalAccessException, IllegalArgumentException

Same as invokeRemoteMethodAsync(Object, MethodTransferProperties, Object...), but handles if the object is not remote.

If the object is not remote, then the method will be called without any RMI transferring.

objectThe object to invoke the method on.

methodThe method to invoke.

argumentsThe arguments to pass to the invoked method.

RMIIOFailureExceptionIn case of I/O error.

RMIObjectTransferFailureExceptionIf writing the arguments fail.

InvocationTargetExceptionIf the local method invocation throws an exception.

IllegalAccessExceptionIf the local method invocation throws an exception.

IllegalArgumentExceptionIf the local method invocation throws an exception.

public Object invokeRemoteStaticMethod(Method method, Object... arguments) throws RMIRuntimeException, InvocationTargetException

Invokes a static method with the given arguments.

The method transfer properties based on the connection configuration will be used when transferring the objects.

The return value will be transferred based on the associated method transfer properties for the other endpoint.

methodThe method to invoke.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

invokeRemoteStaticMethod(MethodTransferProperties, Object...)

RMIOptions.allowDirectRequests(boolean)

public Object invokeRemoteStaticMethod(MethodTransferProperties method, Object... arguments) throws RMIRuntimeException, InvocationTargetException

Invokes a static method with the given arguments.

The passed transfer properties will be used when transferring the objects. Every invocation property is ignored.

The return value will be transferred based on the associated method transfer properties for the other endpoint.

methodThe method to invoke.

argumentsThe arguments to pass to the invoked method.

The result of the invocation.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the method threw an exception.

RMIOptions.allowDirectRequests(boolean)

public boolean isAborting()

Checks if this variables context is aborting.

The variables context is aborting, if it is closed, or closing is in process, but some requests are still ongoing.

This always return true if isClosed() returns true.

true if aborting.

saker.rmi 0.8.3

public boolean isClosed()

Checks if this variables context is closed.

true if closed.

public Object newRemoteInstance(Class<?> type) throws RMIRuntimeException, InvocationTargetException, NoSuchMethodException

Creates a new instance of the given class on the remote endpoint, and returns it as a remote object.

The no-arg constructor will be used when creating the object.

The return value of this method should be only casted to interfaces which are implemented by the constructed object.

typeThe type to create an instance of.

The created object as a remote proxy.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the constructor threw an exception.

NoSuchMethodExceptionIf a no-arg constructor was not found.

RMIOptions.allowDirectRequests(boolean)

public Object newRemoteInstance(Constructor<?> constructor, Object... arguments) throws RMIRuntimeException, InvocationTargetException

Creates a new instance on the remote endpoint, and returns it as a remote object.

The passed constructor will be invoked with the specified arguments. The constructor transfer properties based on the connection configuration will be used when transferring the arguments.

The return value of this method should be only casted to interfaces which are implemented by the constructed object.

constructorThe constructor to use when creating the object.

argumentsThe arguments to pass to the constructor.

The created object as a remote proxy.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the constructor threw an exception.

RMIOptions.allowDirectRequests(boolean)

public Object newRemoteInstance(ConstructorTransferProperties<?> constructor, Object... arguments) throws RMIRuntimeException, InvocationTargetException

Creates a new instance on the remote endpoint, and returns it as a remote object.

The passed constructor with its transfer properties will be invoked with the specified arguments.

The return value of this method should be only casted to interfaces which are implemented by the constructed object.

constructorThe constructor to use when creating the object.

argumentsThe arguments to pass to the constructor.

The created object as a remote proxy.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the constructor threw an exception.

RMIOptions.allowDirectRequests(boolean)

public Object newRemoteOnlyInstance(Object remoteclassloader, String classname) throws RMIRuntimeException, InvocationTargetException, NullPointerException

Creates a new object on the remote endpoint and returns it as a remote proxy object.

This method works the same way as newRemoteOnlyInstance(Object, String, String[], Object[]), with null arguments.

The no-arg constructor will be used to instantiate the object.

remoteclassloaderThe remote classloader or null. Must be bound to this variables context.

classnameThe name of the class to instantiate.

The created object.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the constructor threw an exception.

NullPointerExceptionIf the class name is null.

RMIOptions.allowDirectRequests(boolean)

public Object newRemoteOnlyInstance(Object remoteclassloader, String classname, String[] constructorargumentclasses, Object[] constructorarguments) throws RMIRuntimeException, InvocationTargetException, NullPointerException

Creates a new object on the remote endpoint and returns it as a remote proxy object.

This method should be used when the class of the constructed object is not present on this side of the connection. The actual object class is determined based on the passed remote classloader and the string representation of the class and argument class names.

The constructed object will be returned by casting it to the passed proxy type. The proxy type should be an interface that is knowingly implemented by the constructed object. The proxy type may be null, in which case the object will be returned without downcasting.

The method takes a remote classloader as its first argument. It should either be null, or a remote proxy object to a classloader on the remote endpoint. As classloaders usually doesn't implement any interfaces, any interfaces, it is passed as an raw object to this method. It is the responsibility of the caller to correctly retrieve the remote classloader from the other endpoint.

If the passed classloader is null, then the no classloader will be used. Class.forName(String, boolean, ClassLoader) with null ClassLoader argument will be used to lookup the classes, not the null classloader defined by the RMI options.

remoteclassloaderThe remote classloader or null. Must be bound to this variables context.

classnameThe name of the class to instantiate.

constructorargumentclassesThe class names of the constructor arguments. Passing null is the same as empty array.

constructorargumentsThe arguments to pass to the constructor. Passing null is the same as empty array.

The created object.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the constructor threw an exception.

NullPointerExceptionIf the class name is null.

RMIOptions.allowDirectRequests(boolean)

public Object newRemoteOnlyInstance(String classname) throws RMIRuntimeException, InvocationTargetException, NullPointerException

Creates a new object on the remote endpoint and returns it as a remote proxy object.

This method works the same way as newRemoteOnlyInstance(Object, String, String[], Object[]), with null classloader, and arguments.

The no-arg constructor will be used to instantiate the object.

classnameThe name of the class to instantiate.

The created object.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the constructor threw an exception.

NullPointerExceptionIf the class name is null.

RMIOptions.allowDirectRequests(boolean)

public Object newRemoteOnlyInstance(String classname, String[] constructorargumentclasses, Object[] constructorarguments) throws RMIRuntimeException, InvocationTargetException, NullPointerException

Creates a new object on the remote endpoint and returns it as a remote proxy object.

This method works the same way as newRemoteOnlyInstance(Object, String, String[], Object[]), with null classloader.

classnameThe name of the class to instantiate.

constructorargumentclassesThe class names of the constructor arguments. Passing null is the same as empty array.

constructorargumentsThe arguments to pass to the constructor. Passing null is the same as empty array.

The created object.

RMIRuntimeExceptionIf the RMI call failed.

InvocationTargetExceptionIf the constructor threw an exception.

NullPointerExceptionIf the class name is null.

RMIOptions.allowDirectRequests(boolean)

public String toString()

Overridden from: Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())

a string representation of the object.

public void waitClosure() throws InterruptedException

Waits for this RMI variables to get closed, and all request to be finished.

This method doesn't close the variables, only waits for it to get closed, and the ongoing request to be finished.

You need to call close() in some other way, otherwise this method may wait indefinitely.

InterruptedExceptionIf the current thread is interrupted while waiting.

saker.rmi 0.8.3