com.sun.jini.jeri.internal.mux
Class Mux

java.lang.Object
  extended by com.sun.jini.jeri.internal.mux.Mux
Direct Known Subclasses:
MuxClient, MuxServer

abstract class Mux
extends Object

Mux is the abstract superclass of both client-side and server-side multiplexed connections.

Author:
Sun Microsystems, Inc.

Nested Class Summary
private static class Mux.SessionShutdownTask
           
 
Field Summary
(package private) static int Abort
           
(package private) static int Abort_partial
           
(package private) static int Acknowledgment
           
(package private)  BitSet busySessions
           
(package private) static int CLIENT
           
(package private) static int ClientConnectionHeader_negotiate
           
private  boolean clientConnectionReady
           
(package private) static int Close
           
private  ConnectionIO connectionIO
           
private  ByteBuffer currentDataBuffer
           
private  int currentLengthRemaining
           
private  int currentOp
           
private  int currentSessionID
           
(package private) static int Data
           
(package private) static int Data_ackRequired
           
(package private) static int Data_close
           
(package private) static int Data_eof
           
(package private) static int Data_open
           
private  boolean directBuffersUseful
           
(package private) static int Error
           
private  int expectedPingCookie
           
(package private) static int IncrementRation
           
(package private) static int IncrementRation_shift
           
(package private)  int initialInboundRation
           
(package private)  int initialOutboundRation
           
private static Logger logger
          mux logger
private static byte[] magic
           
static int MAX_REQUESTS
           
(package private) static int MAX_SESSION_ID
           
(package private)  int maxFragmentSize
           
(package private)  boolean muxDown
           
(package private)  Throwable muxDownCause
           
(package private)  String muxDownMessage
           
(package private)  Object muxLock
          lock guarding all mutable instance state (below)
(package private) static int NoOperation
           
(package private) static int Ping
           
(package private) static int PingAck
           
private static int READ_CLIENT_CONNECTION_HEADER
           
private static int READ_MESSAGE_BODY
           
private static int READ_MESSAGE_HEADER
           
private static int READ_SERVER_CONNECTION_HEADER
           
private  int readState
           
private  Object readStateLock
           
(package private)  int role
           
(package private) static int SERVER
           
(package private)  boolean serverConnectionReady
           
(package private)  Map sessions
           
private static LinkedList sessionShutdownQueue
          session shutdown tasks to be executed asynchronously
(package private) static int Shutdown
           
private  long startTimeout
           
private static Executor systemThreadPool
          pool of threads for executing tasks in system thread group: used for shutting down sessions when a connection goes down
private static int VERSION
           
 
Constructor Summary
Mux(OutputStream out, InputStream in, int role, int initialInboundRation, int maxFragmentSize)
          Constructs a new Mux instance for a connection accessible through standard (blocking) I/O streams.
Mux(SocketChannel channel, int role, int initialInboundRation, int maxFragmentSize)
           
 
Method Summary
(package private)  void addSession(int sessionID, Session session)
          This method is intended to be invoked by subclasses only.
(package private)  void asyncSendAbort(int op, int sessionID, ByteBuffer data)
          Sends an Abort message for the specified "sessionID" with the contents of the specified buffer as the data.
(package private)  void asyncSendAcknowledgment(int sessionID)
          Sends an Acknowledgment message for the specified "sessionID".
(package private)  void asyncSendClientConnectionHeader()
          Sends the ClientConnectionHeader message for this connection.
(package private)  void asyncSendClose(int sessionID)
          Sends a Close message for the specified "sessionID".
(package private)  void asyncSendData(int op, int sessionID, ByteBuffer data)
          Sends a Data message for the specified "sessionID" with the contents of the supplied buffer as the data.
(package private)  void asyncSendError(String message)
          Sends an Error message with the UTF-8 encoding of the supplied message as the data.
(package private)  void asyncSendIncrementRation(int sessionID, int increment)
          Sends an IncrementRation message for the specified "sessionID" and the specified "increment".
(package private)  void asyncSendNoOperation(ByteBuffer buffer)
          Sends a NoOperation message with the contents of the supplied buffer as the data.
(package private)  void asyncSendPing(int cookie)
          Sends a Ping message with the specified "cookie".
(package private)  void asyncSendPingAck(int cookie)
          Sends a PingAck message with the specified "cookie".
(package private)  void asyncSendServerConnectionHeader()
          Sends the ServerConnectionHeader message for this connection.
(package private)  void asyncSendShutdown(String message)
          Sends a Shutdown message with the UTF-8 encoding of the supplied message as the data.
(package private)  boolean directBuffersUseful()
          Returns true if it would be useful to pass direct buffers to this instance's *Send* methods (because the underlying I/O implementation will pass such buffers directly to channel write operations); returns false otherwise.
private  void dispatchCurrentMessage()
           
(package private)  IOFuture futureSendData(int op, int sessionID, ByteBuffer data)
          Sends a Data message for the specified sessionID with the contents of the supplied buffer as the data.
(package private)  IOFuture futureSendError(String message)
          Sends an Error message with the UTF-8 encoding of the supplied message as the data.
private  Session getSession(int sessionID)
           
private static String getStringFromUTF8Buffer(ByteBuffer buffer)
           
private static ByteBuffer getUTF8BufferFromString(String s)
           
private  void handleAbort(int sessionID, boolean partial, String message)
           
private  void handleAcknowledgment(int sessionID)
           
private  void handleClose(int sessionID)
           
private  void handleData(int sessionID, boolean open, boolean close, boolean eof, boolean ackRequired, ByteBuffer data)
           
protected  void handleDown()
          Handles indication that this multiplexed connection has gone down, either through normal operation or failure.
private  void handleError(String message)
           
private  void handleIncrementRation(int sessionID, int increment)
           
private  void handleNoOperation()
           
(package private)  void handleOpen(int sessionID)
          This method is invoked internally and is intended to be overridden by subclasses.
private  void handlePing(int cookie)
           
private  void handlePingAck(int cookie)
           
private  void handleShutdown(String message)
           
(package private)  void processIncomingData(ByteBuffer buffer)
           
private  boolean readClientConnectionHeader(ByteBuffer buffer)
           
private  boolean readMessageBody(ByteBuffer buffer)
           
private  boolean readMessageHeader(ByteBuffer buffer)
           
private  boolean readServerConnectionHeader(ByteBuffer buffer)
           
(package private)  void removeSession(int sessionID)
          Removes the identified session from the session table.
(package private)  void setDown(String message, Throwable cause)
          This method is intended to be invoked by this class and subclasses only.
 void setStartTimeout(long timeout)
          Time in milliseconds for client-side connections to wait for the server to acknowledge an opening handshake.
 void start()
          Starts I/O processing.
private static char toHexChar(int x)
           
private static String toHexString(byte x)
           
private static String toHexString(byte[] b)
           
private static String toHexString(int x)
           
private  void validatePartialMagicNumber(ByteBuffer buffer)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLIENT

static final int CLIENT
See Also:
Constant Field Values

SERVER

static final int SERVER
See Also:
Constant Field Values

MAX_SESSION_ID

static final int MAX_SESSION_ID
See Also:
Constant Field Values

MAX_REQUESTS

public static final int MAX_REQUESTS
See Also:
Constant Field Values

NoOperation

static final int NoOperation
See Also:
Constant Field Values

Shutdown

static final int Shutdown
See Also:
Constant Field Values

Ping

static final int Ping
See Also:
Constant Field Values

PingAck

static final int PingAck
See Also:
Constant Field Values

Error

static final int Error
See Also:
Constant Field Values

IncrementRation

static final int IncrementRation
See Also:
Constant Field Values

Abort

static final int Abort
See Also:
Constant Field Values

Close

static final int Close
See Also:
Constant Field Values

Acknowledgment

static final int Acknowledgment
See Also:
Constant Field Values

Data

static final int Data
See Also:
Constant Field Values

IncrementRation_shift

static final int IncrementRation_shift
See Also:
Constant Field Values

Abort_partial

static final int Abort_partial
See Also:
Constant Field Values

Data_open

static final int Data_open
See Also:
Constant Field Values

Data_close

static final int Data_close
See Also:
Constant Field Values

Data_eof

static final int Data_eof
See Also:
Constant Field Values

Data_ackRequired

static final int Data_ackRequired
See Also:
Constant Field Values

ClientConnectionHeader_negotiate

static final int ClientConnectionHeader_negotiate
See Also:
Constant Field Values

magic

private static final byte[] magic

VERSION

private static final int VERSION
See Also:
Constant Field Values

systemThreadPool

private static final Executor systemThreadPool
pool of threads for executing tasks in system thread group: used for shutting down sessions when a connection goes down


sessionShutdownQueue

private static final LinkedList sessionShutdownQueue
session shutdown tasks to be executed asynchronously


logger

private static final Logger logger
mux logger


role

final int role

initialInboundRation

final int initialInboundRation

maxFragmentSize

final int maxFragmentSize

connectionIO

private final ConnectionIO connectionIO

directBuffersUseful

private final boolean directBuffersUseful

muxLock

final Object muxLock
lock guarding all mutable instance state (below)


initialOutboundRation

int initialOutboundRation

clientConnectionReady

private boolean clientConnectionReady

serverConnectionReady

boolean serverConnectionReady

muxDown

boolean muxDown

muxDownMessage

String muxDownMessage

muxDownCause

Throwable muxDownCause

busySessions

final BitSet busySessions

sessions

final Map sessions

expectedPingCookie

private int expectedPingCookie

startTimeout

private long startTimeout

READ_CLIENT_CONNECTION_HEADER

private static final int READ_CLIENT_CONNECTION_HEADER
See Also:
Constant Field Values

READ_SERVER_CONNECTION_HEADER

private static final int READ_SERVER_CONNECTION_HEADER
See Also:
Constant Field Values

READ_MESSAGE_HEADER

private static final int READ_MESSAGE_HEADER
See Also:
Constant Field Values

READ_MESSAGE_BODY

private static final int READ_MESSAGE_BODY
See Also:
Constant Field Values

readStateLock

private final Object readStateLock

readState

private int readState

currentOp

private int currentOp

currentSessionID

private int currentSessionID

currentLengthRemaining

private int currentLengthRemaining

currentDataBuffer

private ByteBuffer currentDataBuffer
Constructor Detail

Mux

Mux(OutputStream out,
    InputStream in,
    int role,
    int initialInboundRation,
    int maxFragmentSize)
throws IOException
Constructs a new Mux instance for a connection accessible through standard (blocking) I/O streams.

Throws:
IOException

Mux

Mux(SocketChannel channel,
    int role,
    int initialInboundRation,
    int maxFragmentSize)
throws IOException
Throws:
IOException
Method Detail

setStartTimeout

public void setStartTimeout(long timeout)
Time in milliseconds for client-side connections to wait for the server to acknowledge an opening handshake. The default value is 15000 milliseconds (15 seconds).

This method is not thread-safe. It is expected to be called immediately after a constructor.

Parameters:
timeout - positive value in milliseconds

start

public void start()
           throws IOException
Starts I/O processing. This method should be invoked only after this instance has been completely initialized, so that subclasses will not see uninitialized state.

Throws:
IOException

handleDown

protected void handleDown()
Handles indication that this multiplexed connection has gone down, either through normal operation or failure. This method should be overridden by subclasses that want to implement custom behavior when this connection has gone down.


handleOpen

void handleOpen(int sessionID)
          throws ProtocolException
This method is invoked internally and is intended to be overridden by subclasses.

Throws:
ProtocolException

addSession

final void addSession(int sessionID,
                      Session session)
This method is intended to be invoked by subclasses only. This method must ONLY be invoked while synchronized on muxLock and while muxDown is false.


setDown

final void setDown(String message,
                   Throwable cause)
This method is intended to be invoked by this class and subclasses only. This method MAY be invoked while synchronized on muxLock.


removeSession

final void removeSession(int sessionID)
Removes the identified session from the session table. This method is intended to be invoked by the associated Session object only.


directBuffersUseful

final boolean directBuffersUseful()
Returns true if it would be useful to pass direct buffers to this instance's *Send* methods (because the underlying I/O implementation will pass such buffers directly to channel write operations); returns false otherwise.


asyncSendClientConnectionHeader

final void asyncSendClientConnectionHeader()
Sends the ClientConnectionHeader message for this connection.


asyncSendServerConnectionHeader

final void asyncSendServerConnectionHeader()
Sends the ServerConnectionHeader message for this connection.


asyncSendNoOperation

final void asyncSendNoOperation(ByteBuffer buffer)
Sends a NoOperation message with the contents of the supplied buffer as the data. The "length" of the NoOperation message will be the number of bytes remaining in the buffer, and the data sent will be the contents of the buffer between its current position and its limit. Or if the buffer argument is null, "length" will simply be zero... REMIND: split into two methods instead? The actual writing to the underlying connection, including access to the buffer's content and other state, is asynchronous with the invocation of this method; therefore, the supplied buffer must not be mutated even after this method has returned.


asyncSendShutdown

final void asyncSendShutdown(String message)
Sends a Shutdown message with the UTF-8 encoding of the supplied message as the data. If message is null, then zero bytes of data will be sent with the message header.


asyncSendPing

final void asyncSendPing(int cookie)
Sends a Ping message with the specified "cookie".


asyncSendPingAck

final void asyncSendPingAck(int cookie)
Sends a PingAck message with the specified "cookie".


asyncSendError

final void asyncSendError(String message)
Sends an Error message with the UTF-8 encoding of the supplied message as the data. If message is null, then zero bytes of data will be sent with the message header.


futureSendError

final IOFuture futureSendError(String message)
Sends an Error message with the UTF-8 encoding of the supplied message as the data. If message is null, then zero bytes of data will be sent with the message header.


asyncSendIncrementRation

final void asyncSendIncrementRation(int sessionID,
                                    int increment)
Sends an IncrementRation message for the specified "sessionID" and the specified "increment".


asyncSendAbort

final void asyncSendAbort(int op,
                          int sessionID,
                          ByteBuffer data)
Sends an Abort message for the specified "sessionID" with the contents of the specified buffer as the data. The "length" of the Abort message will be the number of bytes remaining in the buffer, and the data sent will be the contents of the buffer between its current position and its limit. Or if the buffer argument is null, "length" will simply be zero... REMIND: split into two methods instead? For efficiency, the caller is responsible for pre-computing the first byte of the message, including any control flags if appropriate.


asyncSendClose

final void asyncSendClose(int sessionID)
Sends a Close message for the specified "sessionID".


asyncSendAcknowledgment

final void asyncSendAcknowledgment(int sessionID)
Sends an Acknowledgment message for the specified "sessionID".


asyncSendData

final void asyncSendData(int op,
                         int sessionID,
                         ByteBuffer data)
Sends a Data message for the specified "sessionID" with the contents of the supplied buffer as the data. The "length" of the Data message will be the number of bytes remaining in the buffer, and the data sent will be the contents of the buffer between its current position and its limit. Or if the buffer argument is null, "length" will simply be zero... REMIND: split into two methods instead? For efficiency, the caller is responsible for pre-computing the first byte of the Data message, including any control flags if appropriate. The actual writing to the underlying connection, including access to the buffer's content and other state, is asynchronous with the invocation of this method; therefore, the supplied buffer must not be mutated even after this method has returned.


futureSendData

final IOFuture futureSendData(int op,
                              int sessionID,
                              ByteBuffer data)
Sends a Data message for the specified sessionID with the contents of the supplied buffer as the data. The "length" of the Data message will be the number of bytes remaining in the buffer, and the data sent will be the contents of the buffer between its current position and its limit. For efficiency, the caller is responsible for pre-computing the first byte of the Data message, including any control flags if appropriate. The actual writing to the underlying connection, including access to the buffer's content and other state, is asynchronous with the invocation of this method; therefore, the supplied buffer must not be mutated even after this method has returned, until it is guaranteed that use of the buffer has completed. The returned IOFuture object can be used to wait until the write has definitely completed (or will definitely not complete due to some failure). After the write has completed, the buffer's position will have been incremented to its limit (which will not have changed).


processIncomingData

void processIncomingData(ByteBuffer buffer)
                   throws ProtocolException
Throws:
ProtocolException

readClientConnectionHeader

private boolean readClientConnectionHeader(ByteBuffer buffer)
                                    throws ProtocolException
Throws:
ProtocolException

readServerConnectionHeader

private boolean readServerConnectionHeader(ByteBuffer buffer)
                                    throws ProtocolException
Throws:
ProtocolException

validatePartialMagicNumber

private void validatePartialMagicNumber(ByteBuffer buffer)
                                 throws ProtocolException
Throws:
ProtocolException

readMessageHeader

private boolean readMessageHeader(ByteBuffer buffer)
                           throws ProtocolException
Throws:
ProtocolException

readMessageBody

private boolean readMessageBody(ByteBuffer buffer)
                         throws ProtocolException
Throws:
ProtocolException

dispatchCurrentMessage

private void dispatchCurrentMessage()
                             throws ProtocolException
Throws:
ProtocolException

handleNoOperation

private void handleNoOperation()
                        throws ProtocolException
Throws:
ProtocolException

handleShutdown

private void handleShutdown(String message)
                     throws ProtocolException
Throws:
ProtocolException

handlePing

private void handlePing(int cookie)
                 throws ProtocolException
Throws:
ProtocolException

handlePingAck

private void handlePingAck(int cookie)
                    throws ProtocolException
Throws:
ProtocolException

handleError

private void handleError(String message)
                  throws ProtocolException
Throws:
ProtocolException

handleIncrementRation

private void handleIncrementRation(int sessionID,
                                   int increment)
                            throws ProtocolException
Throws:
ProtocolException

handleAbort

private void handleAbort(int sessionID,
                         boolean partial,
                         String message)
                  throws ProtocolException
Throws:
ProtocolException

handleClose

private void handleClose(int sessionID)
                  throws ProtocolException
Throws:
ProtocolException

handleAcknowledgment

private void handleAcknowledgment(int sessionID)
                           throws ProtocolException
Throws:
ProtocolException

handleData

private void handleData(int sessionID,
                        boolean open,
                        boolean close,
                        boolean eof,
                        boolean ackRequired,
                        ByteBuffer data)
                 throws ProtocolException
Throws:
ProtocolException

getSession

private Session getSession(int sessionID)
                    throws ProtocolException
Throws:
ProtocolException

getUTF8BufferFromString

private static ByteBuffer getUTF8BufferFromString(String s)

getStringFromUTF8Buffer

private static String getStringFromUTF8Buffer(ByteBuffer buffer)

toHexString

private static String toHexString(byte x)

toHexString

private static String toHexString(int x)

toHexString

private static String toHexString(byte[] b)

toHexChar

private static char toHexChar(int x)


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.