Interface Environment

All Superinterfaces:
AutoCloseable, Closeable, Executor
public interface Environment extends Closeable, Executor
Sharable environment for connecting and accepting remote sessions.

  • Method Details

    • create

      static Environment create()
      Returns a new Environment instance which uses a default Executor. When the Environment is closed, the Executor is also closed.

    • create

      static Environment create(Executor executor)
      Returns a new Environment instance which uses the given Executor. When the Environment is closed, the Executor is not closed.

    • create

      static Environment create(Executor executor, boolean closeExecutor)
      Returns a new Environment instance which uses the given Executor.
      Parameters:
      closeExecutor - when true, the Executor is closed when the Environment is closed
      Throws:
      IllegalArgumentException - if closeExecutor is true and the given Executor doesn't implement Closeable or ExecutorService

    • export

      Object export(Object name, Object obj) throws IOException
      Export a named server-side object. If replacing an existing object, then the previously exported instance is disposed of. Pass a null object to remove an export completely. Replacing or removing an exported object has no effect on sessions which already exported it.
      Parameters:
      name - serializable name
      obj - remote object
      Returns:
      the previously exported object or null if none
      Throws:
      IllegalArgumentException - if the name isn't serializable or if the object to export isn't remote.
      IOException

    • acceptAll

      default Closeable acceptAll(ServerSocket ss) throws IOException
      Accept all server-side connections from the given ServerSocket. As long as the acceptor is still running, the JVM won't exit.
      Returns:
      an object which can be closed to stop accepting
      Throws:
      IllegalStateException - if already accepting connections from the socket
      IOException

    • acceptAll

      Closeable acceptAll(ServerSocket ss, Predicate<Socket> listener) throws IOException
      Accept all server-side connections from the given ServerSocket. As long as the acceptor is still running, the JVM won't exit.
      Parameters:
      listener - is called for each accepted socket; return false if socket is rejected
      Returns:
      an object which can be closed to stop accepting
      Throws:
      IllegalStateException - if already accepting connections from the socket
      IOException

    • acceptAll

      default Closeable acceptAll(ServerSocketChannel ss) throws IOException
      Accept all server-side connections from the given ServerSocketChannel. As long as the acceptor is still running, the JVM won't exit.
      Returns:
      an object which can be closed to stop accepting
      Throws:
      IllegalStateException - if already accepting connections from the socket channel
      IOException

    • acceptAll

      Closeable acceptAll(ServerSocketChannel ss, Predicate<SocketChannel> listener) throws IOException
      Accept all server-side connections from the given ServerSocketChannel. As long as the acceptor is still running, the JVM won't exit.
      Parameters:
      listener - is called for each accepted socket; return false if socket is rejected
      Returns:
      an object which can be closed to stop accepting
      Throws:
      IllegalStateException - if already accepting connections from the socket channel
      IOException

    • accepted

      default Session<?> accepted(Socket s) throws IOException
      Call when a server-side connection has been explicitly accepted. Any exception thrown from this method closes the socket.
      Returns:
      new or existing server-side session instance
      Throws:
      IOException - if a communication failure or if the client is requesting an object which isn't exported

    • accepted

      default Session<?> accepted(SocketChannel s) throws IOException
      Call when a server-side connection has been explicitly accepted. Any exception thrown from this method closes the socket.
      Returns:
      new or existing server-side session instance
      Throws:
      IOException - if a communication failure or if the client is requesting an object which isn't exported

    • accepted

      Session<?> accepted(SocketAddress localAddr, SocketAddress remoteAddr, InputStream in, OutputStream out) throws IOException
      Call when a server-side connection has been explicitly accepted. Any exception thrown from this method closes the socket.
      Parameters:
      localAddr - local link address, or null if unknown or not applicable
      remoteAddr - remote link address, or null if unknown or not applicable
      Returns:
      new or existing server-side session instance
      Throws:
      IOException - if a communication failure or if the client is requesting an object which isn't exported

    • connect

      <R> Session<R> connect(Class<R> type, Object name, SocketAddress addr) throws IOException
      Call to establish a new client-side session. A remote server must be accepting connections, and it must also export the given named object.
      Parameters:
      type - the type of the root object which is exported by the remote server
      name - the name of the root object which is exported by the remote server
      addr - server address to connect to
      Returns:
      new or existing client-side session instance
      Throws:
      IllegalArgumentException - if the name isn't serializable or if the type isn't remote.
      IOException - if a communication failure or if no object is exported by the given type and name

    • connect

      default <R> Session<R> connect(Class<R> type, Object name, String host, int port) throws IOException
      Call to establish a new client-side session. A remote server must be accepting connections, and it must also export the given named object.
      Parameters:
      type - the type of the root object which is exported by the remote server
      name - the name of the root object which is exported by the remote server
      host - server host address to connect to
      port - server port to connect to
      Returns:
      new or existing client-side session instance
      Throws:
      IllegalArgumentException - if the name isn't serializable or if the type isn't remote.
      IOException - if a communication failure or if no object is exported by the given type and name

    • connector

      Connector connector(Connector c) throws IOException
      Assign a connector for establishing new client-side socket connections. By default, the direct connector is used.
      Parameters:
      c - non-null connector
      Returns:
      the previously assigned connector
      Throws:
      IOException

    • customSerializers

      void customSerializers(Serializer... serializers)
      Provide custom serializers for newly established sessions. If the set of serializers provided by the client and server sessions don't match, then null is serialized for classes which aren't customized on both sides.
      Throws:
      NullPointerException - if any serializers are null

    • reconnectDelayMillis

      void reconnectDelayMillis(int millis)
      Set the reconnect delay for newly established client sessions (±10%). Client sessions attempt to reconnect when the session is disconnected, and the delay is applied before each attempt. The default reconnect delay is 1 second. Pass a negative delay to disable reconnect, and instead the session is closed when it's disconnected. Disposing the root object also disables reconnect.

    • pingTimeoutMillis

      void pingTimeoutMillis(int millis)
      Set the ping timeout for newly established sessions (±33%). If no ping response is received from the remote endpoint in time, then the session is disconnected or closed. Server-side sessions are always closed, but client-side sessions are closed only when reconnect is disabled. The default ping timeout is 2 seconds. Pass a negative timeout to disable pings. The session can still close or be disconnected if communication over the control connection fails.

    • idleConnectionMillis

      void idleConnectionMillis(int millis)
      Set the maximum idle connection time for newly established sessions (±33%). This defines the maximum amount of time a connection can remain idle before it's automatically closed. The default idle time is 60 seconds. Pass a negative amount to disable the closing of idle connections.

    • classResolver

      void classResolver(ClassResolver resolver)
      Set the class resolver to use for newly established sessions. This affects the class loading behavior for Serialized methods.
      Parameters:
      resolver - resolver to use; pass null to use the default resolver

    • classLoader

      default void classLoader(ClassLoader loader)
      Convenience method to use a ClassLoader for resolving classes.
      Parameters:
      loader - loader to use to resolve classes; pass null to use the default resolver

    • uncaughtExceptionHandler

      void uncaughtExceptionHandler(BiConsumer<Session<?>, Throwable> h)
      Set the handler which is invoked for any uncaught exceptions within this environment instance. The session instance passed to the handler is null when not applicable. By default, uncaught exceptions are passed to the current thread's uncaught exception handler.
      Parameters:
      h - handler to use; pass null to use the default handler
      See Also:

    • close

      void close()
      Stops accepting new sessions, closes all acceptors, closes all sessions, and disposes of all exported objects.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable