org.cojen.dirmi

Interface Session

All Superinterfaces:

AutoCloseable, Closeable, Flushable, Link

All Known Implementing Classes:

StandardSession

public interface Session
extends Closeable, Flushable, Link

Remote method invocation session. Basic communication between sessions is provided by the send and receive methods, which behave like a blocking queue with a capacity of one. Object transport via this interface is intended for handshaking and authentication. After an initial exchange, remote objects should be used for most communication between endpoints.

The send/receive methods follow the pull model rather than the push model. Calling send locally enqueues an object, but receive makes a remote call. This behavior allows a ClassResolver to be installed prior to its first use, avoiding race conditions.

Author:

Brian S O'Neill

See Also:

Environment

Method Summary

Modifier and Type	Method and Description
void	addCloseListener(SessionCloseListener listener) Add a listener which receives notification when this session is closed.
void	close() Closes the session.
void	flush() Flushes all channels of this session, including channels used for batch calls and eventual asynchronous methods.
Object	getLocalAddress()
Object	getRemoteAddress()
Object	receive() Receives a Remote or Serializable object sent by the remote session.
Object	receive(long timeout, TimeUnit unit) Receives a Remote or Serializable object sent by the remote session.
void	send(Object obj) Sends a Remote or Serializable object to be received by the remote session.
void	send(Object obj, long timeout, TimeUnit unit) Sends a Remote or Serializable object to be received by the remote session.
void	setClassLoader(ClassLoader loader) Convenience method to use a ClassLoader for resolving classes.
void	setClassResolver(ClassResolver resolver) Can be called at most once to control how deserialized classes and remote interfaces are resolved.

Method Detail

getLocalAddress

Object getLocalAddress()

Specified by:

getLocalAddress in interface Link

Returns:

local session address or null if unknown or not applicable

getRemoteAddress

Object getRemoteAddress()

Specified by:

getRemoteAddress in interface Link

Returns:

remote session address or null if unknown or not applicable

send

void send(Object obj)
   throws RemoteException

Sends a Remote or Serializable object to be received by the remote session. Any failure during the send forces the session to be closed.

Parameters:

obj - remote or serializable object to send; can be null

Throws:

RemoteException

send

void send(Object obj,
          long timeout,
          TimeUnit unit)
   throws RemoteException

Sends a Remote or Serializable object to be received by the remote session. Any failure or timeout during the send forces the session to be closed.

Parameters:

obj - remote or serializable object to send; can be null

timeout - how long to wait before timing out, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Throws:

RemoteTimeoutException - if timeout elapses

RemoteException

receive

Object receive()
        throws RemoteException

Receives a Remote or Serializable object sent by the remote session. Any failure during the receive forces the session to be closed.

Returns:

remote or serializable object from remote session; can be null

Throws:

RemoteException

receive

Object receive(long timeout,
               TimeUnit unit)
        throws RemoteException

Receives a Remote or Serializable object sent by the remote session. Any failure or timeout during the receive forces the session to be closed.

Parameters:

timeout - how long to wait before timing out, in units of unit

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

remote or serializable object from remote session; can be null

Throws:

RemoteTimeoutException - if timeout elapses

RemoteException

addCloseListener

void addCloseListener(SessionCloseListener listener)

Add a listener which receives notification when this session is closed. Listener is called at most once, and then it is unregistered.

Throws:

IllegalArgumentException - if listener is null

setClassResolver

void setClassResolver(ClassResolver resolver)

Can be called at most once to control how deserialized classes and remote interfaces are resolved. If the implemention chooses to remotely download classes, it is strongly recommended that a security manager be installed. Resolver implementation may choose to enforce this restriction.

Parameters:

resolver - resolves deserialized classes and interfaces; pass null to always use default resolver

Throws:

IllegalStateException - if resolver cannot be changed

setClassLoader

void setClassLoader(ClassLoader loader)

Convenience method to use a ClassLoader for resolving classes.

Parameters:

loader - resolves deserialized classes and interfaces; pass null to always use default resolver

Throws:

IllegalStateException - if resolver cannot be changed

flush

void flush()
    throws IOException

Flushes all channels of this session, including channels used for batch calls and eventual asynchronous methods.

Specified by:

flush in interface Flushable

Throws:

IOException

close

void close()
    throws IOException

Closes the session.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException