RMIConnection

public final class RMIConnection implements AutoCloseable

saker.rmi.connection.RMIConnection

java.lang.Object

java.lang.AutoCloseable

Class representing an established RMI connection.

This class is the main enclosing coordinator for RMI connections.

An instance of this class can be created using the RMIOptions class.

The connection class holds information required for the RMI runtime to operate, and is the main representation of the local endpoint of a RMI connection.

Objects in an RMI connection can be used via the RMIVariables class which provide the functionality for creating remote objects and invoking methods. New or existing instances of variable contexts can be retrieved via the newVariables() or getVariables(String) functions.

Context variables can be added to an RMI connection, which are basically named global variables present in a connection. Clients of a connection can use these names to retrieve objects from the other endpoin. This is often useful when an RMI server provides a specific functionality via an interface and clients want to get the remote object to call the given functions on. See putContextVariable(String, Object) and RMIVariables.getRemoteContextVariable(String).

The RMI connections need to be closed after being used. The closing may be synchronous or asynchronous based on the caller. If the close() method is being called through and RMI invocation, then the connection will be closed asynchronously.

Nested types

public interface	CloseListener Event listener that is called when the RMIConnection is closed.
public interface	IOErrorListener I/O error listener interface to get notified about connection errors.

Fields

public static final int	PROTOCOL_VERSION_1 = 1 The protocol version of the first RMI library release.
public static final int	PROTOCOL_VERSION_2 = 2 Version 2.
public static final short	PROTOCOL_VERSION_LATEST = (short)2 The latest protocol version.

Methods

public void	addCloseListener(CloseListener listener) Adds a connection close listener to this connection.
public void	addErrorListener(IOErrorListener listener) Adds an I/O error listener to this connection.
public void	close() Marks the RMI connection as closed.
public void	closeWait() Closes the RMI connection and waits for the pending requests to be finished.
public ClassLoaderResolver	getClassLoaderResolver() Gets the ClassLoaderResolver instance used by this RMI connection.
public Object	getLocalContextVariable(String variablename) Gets a previously set named variable on this side of the RMI connection.
public RMIStatistics	getStatistics() Gets the RMI statistics that were collected.
public RMIVariables	getVariables(String name) Gets or creates a variables context for the given name.
public boolean	isAborting() Checks if this connection is about to be closed, and should no longer be used.
public boolean	isConnected() Check if the connection is still in a valid state.
public static boolean	isRemoteObject(Object obj) Checks if the argument is a remote proxy object.
public static boolean	isSameLocationRemoteObjects(Object obj1, Object obj2) Checks if the argument objects are both remote proxies and are used with the same RMI variables context.
public boolean	isStatisticsCollected() Gets if RMI statistics are being collected.
public RMIVariables	newVariables() Creates a new unnamed variables context in this connection.
public void	putContextVariable(String variablename, Object var) Sets a named variable for this RMI connection.
public void	removeCloseListener(CloseListener listener) Removes a previously added close listener.
public void	removeErrorListener(IOErrorListener listener) Removes a previously added error listener.

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

public static final int PROTOCOL_VERSION_1 = 1

The protocol version of the first RMI library release.

public static final int PROTOCOL_VERSION_2 = 2

Version 2.

Modifies the object protocol to include the byte count of the transferred data in case of serializing wrapped objects and serializable objects.

saker.rmi 0.8.3

public static final short PROTOCOL_VERSION_LATEST = (short)2

The latest protocol version.

public void addCloseListener(CloseListener listener) throws NullPointerException, IllegalArgumentException, RMIListenerException

Adds a connection close listener to this connection.

The listener is called when the connection is being closed. It may be called asynchronously, and even before this method finishes.

listenerThe listener.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the listener is a remote object.

RMIListenerExceptionIf the connection is closed, therefore the argument listener is called, and it threw an exception.

saker.rmi 0.8.2

public void addErrorListener(IOErrorListener listener) throws NullPointerException, IllegalArgumentException, RMIListenerException

Adds an I/O error listener to this connection.

The listener is called when I/O errors are detected in the connection.

If an I/O error was already detected, then the listener will be called before this method returns.

Listeners are kept until they are explicitly remoeved. They may be called concurrently, and multiple times.

listenerThe listener.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the listener is a remote object.

RMIListenerExceptionIf an I/O error was detected therefore the argument listener is called, and it threw an exception.

public void close() throws IOException

Marks the RMI connection as closed.

Closing an RMI connection does not happen immediately, calling this method only signals the connection to be closed when the last pending request finishes.

To wait for the pending requests to finish, call closeWait().

If any request is made to any of the proxy objects in this connection after closing, the request may succeed, or an appropriate RMIRuntimeException may be thrown.

Callers should ensure that no requests are running in the system before calling this method. This often requires external synchronization by the user.

IOExceptionIn case of I/O error.

public void closeWait() throws IOException, InterruptedException

Closes the RMI connection and waits for the pending requests to be finished.

This method works the same way as close(), but waits for the requests to properly finish before returning.

IOExceptionIn case of I/O error.

InterruptedExceptionIf the current thread was interrupted.

public ClassLoaderResolver getClassLoaderResolver()

Gets the ClassLoaderResolver instance used by this RMI connection.

If it was set by RMIOptions then the specified instance else a defaulted resolver is returned.

The ClassLoaderResolver used to look up classes by this RMI connection.

public Object getLocalContextVariable(String variablename)

Gets a previously set named variable on this side of the RMI connection.

Only local variables are retrieved and no RMI request is made to the other endpoint.

variablenameThe name for the variable.

The variable with the name or null if it is not set.

putContextVariable(String, Object)

public RMIStatistics getStatistics()

Gets the RMI statistics that were collected.

This method returns non-null if and only if RMIOptions.collectStatistics(boolean) was set to true.

If the connection is still alive (i.e. not closed) then the returned statistics object may be modified if RMI calls are performed concurrently.

The statistics or null if none were collected.

saker.rmi 0.8.2

public RMIVariables getVariables(String name) throws RMIRuntimeException, IllegalArgumentException

Gets or creates a variables context for the given name.

Named variables are present on both endpoint with a specific name. They can be used to access predetermined variables to encapsulate different parts of code.

The returned variables instance need to be closed for each call of getVariables(String). The variables will only be closed after each client closed them, as their retrieval is reference counted. A named variables context will be finally closed if any of the endpoint closes the variables completely.

If a named variables has been retrieved, and later closed, a new instance for the name can be retrieved again. I.e. the names are reuseable.

nameThe name of the variables context.

The variables for the given name.

RMIRuntimeExceptionIf the operation failed.

IllegalArgumentExceptionIf the name is null or empty, or the given variables context name is too long, and cannot be encoded via UTF-8 into less than 65536 bytes.

public boolean isAborting()

Checks if this connection is about to be closed, and should no longer be used.

A connection is aborting, if there were any I/O errors, or it was explicitly closed, but the closing cannot be done synchronously.

true if the connection is aborting.

public boolean isConnected()

Check if the connection is still in a valid state.

This method will return false if any I/O errors are detected, or the connection has been closed.

If the connection is still alive.

public static boolean isRemoteObject(Object obj)

Checks if the argument is a remote proxy object.

This method checks if the object is created by the RMI library, and calls to it will be dispatched over an RMI connection. As this is a static method, it doesn't check if it belongs to any specific RMI connection, but only checks if the objects is remote.

Calling this method has the same performance cost as an instanceof expression.

objThe object to check

true if the argument is a remote proxy.

public static boolean isSameLocationRemoteObjects(Object obj1, Object obj2)

Checks if the argument objects are both remote proxies and are used with the same RMI variables context.

obj1The first object.

obj2The second object.

true if both objects are remote, and bound to the same RMI variables context.

RMIVariables

public boolean isStatisticsCollected()

Gets if RMI statistics are being collected.

true if getStatistics() will return non-null.

saker.rmi 0.8.2

public RMIVariables newVariables() throws RMIRuntimeException

Creates a new unnamed variables context in this connection.

The returned variables instance need to be closed by the caller when no longer used.

The created variables context.

RMIRuntimeExceptionIf the creation failed.

RMIVariables

public void putContextVariable(String variablename, Object var)

Sets a named variable for this RMI connection.

Named variables can be used to retrieve pre-defined objects remotely. If a connection is supposed to be utilized for a specific task then setting a variable on the server side can make it easy for the client to establish the communication.

The variables are retrivable on the remote endpoint using RMIVariables.getRemoteContextVariable(String).

Any previously set variable with the same name will be overwritten. Setting null will remove the variable.

It is recommended that context variables have an interface which can be used to retrieve on the other side.

variablenameThe name of the variable.

varThe variable object instance or null to remove the current object.

public void removeCloseListener(CloseListener listener) throws NullPointerException, IllegalArgumentException

Removes a previously added close listener.

listenerThe listener.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the listener is a remote object.

addCloseListener(CloseListener)

saker.rmi 0.8.2

public void removeErrorListener(IOErrorListener listener) throws NullPointerException, IllegalArgumentException

Removes a previously added error listener.

listenerThe listener.

NullPointerExceptionIf the argument is null.

IllegalArgumentExceptionIf the listener is a remote object.

addErrorListener(IOErrorListener)