org.cojen.dirmi

Class Environment

java.lang.Object

org.cojen.dirmi.Environment

All Implemented Interfaces:

Closeable, AutoCloseable

public class Environment
extends Object
implements Closeable

Sharable environment for connecting and accepting remote sessions. All sessions established from the same environment instance share an executor.

Author:

Brian S O'Neill

Constructor Summary

Constructors

Constructor and Description
Environment() Construct environment which uses up to 1000 threads.
Environment(int maxThreads) Construct environment with the given maximum number of threads.
Environment(int maxThreads, String threadNamePrefix, Thread.UncaughtExceptionHandler handler) Construct environment with the given maximum number of threads, thread name prefix, and uncaught exception handler.
Environment(ScheduledExecutorService executor) Construct environment with a custom executor.

Method Summary

Modifier and Type	Method and Description
void	close() Closes all existing sessions and then shuts down the thread pool.
ScheduledExecutorService	executor() Returns the executor used by this environment.
Session	newSession(ChannelBroker broker) Attempts to connect using given broker, blocking until session is established.
Session	newSession(ChannelBroker broker, long timeout, TimeUnit unit) Attempts to connect using given broker, blocking until session is established.
SessionAcceptor	newSessionAcceptor(int port) Returns an acceptor of sessions.
SessionAcceptor	newSessionAcceptor(SocketAddress localAddress) Returns an acceptor of sessions.
SessionConnector	newSessionConnector(SocketAddress remoteAddress) Returns a session connector for a remote endpoint.
SessionConnector	newSessionConnector(SocketAddress remoteAddress, SocketAddress localAddress) Returns a session connector for a remote endpoint.
SessionConnector	newSessionConnector(String host, int port) Returns a session connector for a remote endpoint.
Session[]	newSessionPair() Returns two locally connected sessions.
Environment	withClassLoader(ClassLoader classLoader) Returns an environment instance which uses the provided classloader for all established sessions.
Environment	withClientSocketFactory(SocketFactory sf) Returns an environment instance which connects using the given client socket factory.
Environment	withServerSocketFactory(ServerSocketFactory ssf) Returns an environment instance which accepts using the given server socket factory.
Environment	withSocketSelector() Returns an environment instance which uses selectable sockets, reducing the amount of idle threads.

Methods inherited from class java.lang.Object

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

Constructor Detail

Environment

public Environment()

Construct environment which uses up to 1000 threads.

Environment

public Environment(int maxThreads)

Construct environment with the given maximum number of threads.

Parameters:

maxThreads - maximum number of threads in pool

Environment

public Environment(int maxThreads,
                   String threadNamePrefix,
                   Thread.UncaughtExceptionHandler handler)

Construct environment with the given maximum number of threads, thread name prefix, and uncaught exception handler.

Parameters:

maxThreads - maximum number of threads in pool

threadNamePrefix - prefix given to thread name; pass null for default

handler - handler for uncaught exceptions; pass null for default

Environment

public Environment(ScheduledExecutorService executor)

Construct environment with a custom executor.

See Also:

ThreadPool

Method Detail

withClientSocketFactory

public Environment withClientSocketFactory(SocketFactory sf)

Returns an environment instance which connects using the given client socket factory. The returned environment is linked to this one, and closing either environment closes both.

Throws:

IllegalStateException - if environment uses a selector

withServerSocketFactory

public Environment withServerSocketFactory(ServerSocketFactory ssf)

Returns an environment instance which accepts using the given server socket factory. The returned environment is linked to this one, and closing either environment closes both.

Throws:

IllegalStateException - if environment uses a selector

withSocketSelector

public Environment withSocketSelector()
                               throws IOException

Returns an environment instance which uses selectable sockets, reducing the amount of idle threads. The returned environment is linked to this one, and closing either environment closes both.

Overall performance is lower with selectable sockets, but scalability is improved. Remote call overhead is about 2 to 4 times higher, which is largely due to the inefficient design of the nio library.

Throws:

IllegalStateException - if environment uses a socket factory

IOException

withClassLoader

public Environment withClassLoader(ClassLoader classLoader)

Returns an environment instance which uses the provided classloader for all established sessions. The returned environment is linked to this one, and closing either environment closes both.

newSessionConnector

public SessionConnector newSessionConnector(String host,
                                            int port)

Returns a session connector for a remote endpoint. Call connect to immediately establish a session.

Parameters:

host - required name of remote endpoint

port - remote port

newSessionConnector

public SessionConnector newSessionConnector(SocketAddress remoteAddress)

Returns a session connector for a remote endpoint. Call connect to immediately establish a session.

Parameters:

remoteAddress - required address of remote endpoint

newSessionConnector

public SessionConnector newSessionConnector(SocketAddress remoteAddress,
                                            SocketAddress localAddress)

Returns a session connector for a remote endpoint. Call connect to immediately establish a session.

Parameters:

remoteAddress - required address of remote endpoint

localAddress - optional address of local bindpoint

newSessionAcceptor

public SessionAcceptor newSessionAcceptor(int port)
                                   throws IOException

Returns an acceptor of sessions. Call acceptAll to start automatically accepting sessions.

Parameters:

port - port for accepting socket connections; pass zero to choose any available port

Throws:

IOException

newSessionAcceptor

public SessionAcceptor newSessionAcceptor(SocketAddress localAddress)
                                   throws IOException

Returns an acceptor of sessions. Call acceptAll to start automatically accepting sessions.

Parameters:

localAddress - address for accepting socket connections; use null to automatically select a local address and any available port

Throws:

IOException

newSession

public Session newSession(ChannelBroker broker)
                   throws IOException

Attempts to connect using given broker, blocking until session is established. Only one session can be created per broker instance.

Parameters:

broker - required broker for establishing connections; must always connect to same remote endpoint

Throws:

IOException

newSession

public Session newSession(ChannelBroker broker,
                          long timeout,
                          TimeUnit unit)
                   throws IOException

Attempts to connect using given broker, blocking until session is established. Only one session can be created per broker instance.

Parameters:

broker - required broker for establishing connections; must always connect to same remote endpoint

Throws:

RemoteTimeoutException

IOException

newSessionPair

public Session[] newSessionPair()
                         throws RejectedException

Returns two locally connected sessions.

Returns:

two Session objects connected to each other

Throws:

RejectedException - if thread pool is full or shutdown

executor

public ScheduledExecutorService executor()

Returns the executor used by this environment.

close

public void close()
           throws IOException

Closes all existing sessions and then shuts down the thread pool. New sessions cannot be established.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException