saker.rmi Documentation TaskDoc JavaDoc Packages
public final class RMIOptions
Class for specifying different aspects of an RMI connection.

This class can be used in a builder pattern where the user specifies various options for the RMI connection and then requests the initiation of the connection via connect(SocketFactory, SocketAddress).

For more information see the public builder methods in this class.

Constructors
public
Creates a new instance with default values.
public
Creates a new instance with values copied from the parameter.
Methods
public RMIOptions
allowDirectRequests(boolean allowDirectRequests)
Sets whether the remote endpoint can issue direct requests through the RMI connection.
public RMIOptions
Simplified method for setting both the classloader resolver and null classloader.
public RMIOptions
Specifies the strategy for looking up classloaders during the connection.
public RMIOptions
collectStatistics(boolean collectStatistics)
Specifies if RMI statistics should be collected during the lifetime of the RMI connection.
public RMIConnection
Initiates the connection with the given parameters.
public RMIConnection
Initiates the connection to the given address with the specified socket configuration.
public RMIConnection
connect(SocketFactory socketfactory, SocketAddress address)
Initiates the connection with the given parameters.
public RMIOptions
executor(Executor executor)
Sets the Executor that should be used by the RMI connection when spawning new tasks.
public ClassLoaderResolver
Gets the currently set classloader resolver.
public ClassLoader
Gety the currently set null classloader.
public RMIOptions
maxStreamCount(int count)
Sets the maximum stream count to create when connecting to the remote endpoint.
public RMIOptions
Specifies the classloader to use if the remote endpoint passes null for the transferred classloader for a given class.
public RMIOptions
objectTransferByteChecks(boolean docheck)
Sets if byte boundary checks should be performed during RMI transfer.
public String
Returns a string representation of the object.
public RMIOptions
Specifies the transfer properties to use for the connection.
public RMIOptions
Specifies the thread group to use for worker threads in the connection.
public RMIOptions()
Creates a new instance with default values.
Creates a new instance with values copied from the parameter.
copyThe options to copy the values from.
NullPointerExceptionIf the argument is null.
public RMIOptions allowDirectRequests(boolean allowDirectRequests)
Sets whether the remote endpoint can issue direct requests through the RMI connection.

Direct requests are any constructor calls, or static method calls, or basically any method calls which are not called through remote proxy objects. If the other endpoint tries to call a constructor, a static method or a non-remote proxy method, an RMICallForbiddenException will be thrown.

This option can ensure that the client doesn't instantiate any objects inside this JVM. Setting this to false will ensure that only such methods are called which have an appropriate remote proxy subject.

Note, that if this options is set to false, the client won't be able to call anything through the RMI connection, unless it is able to retrieve a context variable from the connection.

This options should be set to false when any side can expect that the other endpoint may work in a malicious way.

Note, that special care must be done when designing security sensitive applications. Setting this flag to false is not enough for designing secure applications.

allowDirectRequeststrue to allow direct requests from the other endpoint.
this
Simplified method for setting both the classloader resolver and null classloader.

The parameter classloader will be used for the null lookup, and it will be used as a single and only classloader to lookup the used classloaders.

clThe classloader to use.
this
Specifies the strategy for looking up classloaders during the connection.

An instance of ClassLoaderResolver is used to derive String based identifiers from the transferred classloaders and look them up on the remote endpoint.

resolverThe resolver to use.
this
public RMIOptions collectStatistics(boolean collectStatistics)
Specifies if RMI statistics should be collected during the lifetime of the RMI connection.

The default value is false.

collectStatisticstrue to collect statistics.
this
saker.rmi 0.8.2
Initiates the connection with the given parameters.

Same as connect(SocketFactory, SocketAddress) with null socket factory.

This instance can be reused after calling this method.

addressThe address to connect to.
The initiated connection.
IOExceptionIn case of connection failure.
NullPointerExceptionIf the address is null.
Initiates the connection to the given address with the specified socket configuration.
addressThe address to connect to.
socketconfigThe socket configuration.
The initiated connection.
IOExceptionIn case of connection failure.
NullPointerExceptionIf any of the arguments are null.
saker.rmi 0.8.2
Initiates the connection with the given parameters.

This instance can be reused after calling this method.

socketfactoryThe socket factory to use or null.
addressThe address to connect to.
The initiated connection.
IOExceptionIn case of connection failure.
NullPointerExceptionIf the address is null.
public RMIOptions executor(Executor executor)
Sets the Executor that should be used by the RMI connection when spawning new tasks.

Important: In newer releases of Java, thread locals can be disabled for threads. Saker.rmi doesn't support executors that disable thread locals. (This may change in the future when Extent-Local Variables are introduced.)

The concurrency factor of the used executor should be unbounded, meaning that all tasks submitted should be able to run in parallel. Otherwise the RMI connection and its streams could get deadlocked.

Setting an executor will unset the worker thread group, as in this case the RMI library won't spawn its own threads.

executorThe executor to use.
this
saker.rmi 0.8.3
Gets the currently set classloader resolver.
The currently set classloader resolver or null if it was not set.
Gety the currently set null classloader.
The currently set null classloader or null if not set.
public RMIOptions maxStreamCount(int count)
Sets the maximum stream count to create when connecting to the remote endpoint.

Higher values can result in lower latency, as the congestion might decrease. Choosing too large values can result in thrashing, therefore users should choose an optimal value based on available CPU and network conditions.

The default value is chosen based on the current environment. (Currently equals to Runtime.getRuntime().availableProcessors(), may be modified in the future.)

Values less than 0 represent the default value, 0 will be normalized to 1, any other value will result in creation of that many streams.

countThe stream count to use during connection. -1 to reset to the default value.
this
Specifies the classloader to use if the remote endpoint passes null for the transferred classloader for a given class.

When classes are transmitted over the connection an identifier is used to locate the classloader of the corresponding class. Some classes can have null as their classloader. This can happen for example if the class was loaded using the bootstrap classloader on JRE 8. (E.g. Runnable.class.getClassLoader() returns null)

In these cases the user can specify a given classloader so the classes a properly resolved between JRE versions.

Other example use-case for this is:

On JDK8 a class returns null classloader. (SQLException.class.getClassLoader() is null on JDK8)
On JDK9+ a class return non-null classloader. (SQLException.class.getClassLoader() is non-null and is the same as ClassLoader.getPlatformClassLoader() on JDK9)

In this case if the communcation is between JDK8 and 9 processes, then specifying the platform classloader as the null classloader on the JDK9 endpoint will result in correct operation, while leaving it unset will result in a ClassNotFoundException when looking up e.g. SQLException class.

clThe classloader to use for class lookup.
this
public RMIOptions objectTransferByteChecks(boolean docheck)
Sets if byte boundary checks should be performed during RMI transfer.

If checks are enabled, then the object deserialization will fail in case of Externalizable or wrapped objects when the deserializing doesn't read all bytes that were written during serialization.

The default value is false.

dochecktrue to enable byte checks.
this
saker.rmi 0.8.3
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.
Specifies the transfer properties to use for the connection.
propertiesThe properties to use.
this
Specifies the thread group to use for worker threads in the connection.

Note: since saker.rmi version 0.8.3 if you set the worker thread group, the executor will be unset.

Any created thread that is used to manage the connection will have this thread group as an ancestor.
Worker threads include:

  • Handling requests.
  • Garbage collection of RMI objects.
  • Initiating connection for new streams.
  • Connection stream I/O.
threadgroupThe thread group to use.
this