org.iids.aos.kernel.mux
Class Mux

java.lang.Object
  org.iids.aos.kernel.mux.Mux

public final class Mux
extends java.lang.Object

The main part of the AOS kernel multiplexer implementation.

Author:

Patrick Verkaik, Arno Bakker

Field Summary

protected LocalDescriptorTable	_localDescriptorTable Table for allocating connection ports and listen ports from a single address space
protected static int	MAX_PAYLOAD Maximum number of bytes of user-provided payload that we can fit into a payload message.
protected static int	PROTO_HEADER_LENGTH Length in bytes of PROTO header V1
static int	VIRTUAL_BACKLOG

Constructor Summary

Mux(java.net.InetSocketAddress contactPoint, int backlog, int nthreads, boolean secureComm, java.security.KeyStore keyStore, java.lang.String keyStorePassphrase)
Creates a multiplexer listening on a specific TCP/IP contact point.

Method Summary

int	acceptVirtual(int listenPortNumber, boolean blocking) Returns the next connection waiting in a listen port.
void	checkOwnerOfConnectionPort(int connectionPort, Role r) Check ownership of connection port
void	checkOwnerOfListenPort(int listenPort, Role r) Check ownership of listen port
void	checkOwnerOfPortSets(SelectSets sets, Role r)
void	closeMultiplexer() Closes the base listener and base connections, and stops handler threads.
void	closeVirtual(int connectionPortNumber, int code) Closes a virtual connection.
void	closeVirtualContactPoint(int listenPortNumber, int code) Destroys a listen port and its virtual contact point, and closes any pending connections.
int	connectVirtual(Endpoint remote, java.lang.String[] userSecSuites) Establishes a virtual connection with a remote contact point.
int	createVirtualContactPoint(int listenPortNumber, java.lang.String[] secSuites) Creates a listen port and makes it available as a virtual contact point.
void	deletePortsOwnedBy(Role r) Deletes all connection and listen ports owned by role.
java.net.InetSocketAddress	getContactPoint() Returns the address of the base listener TCP/IP contact point.
static Mux	getInstance()
int	getRemoteConnectionPort(int connectionPortNumber) Asks for the remote connection port number of a virtual connection.
java.lang.String	getRemoteSCID(int connectionPortNumber) Asks for the remote SCID of a virtual connection.
java.net.InetSocketAddress	getRemoteSocketAddress(int connectionPortNumber) Asks for the remote TCP/IP connection socket address of the base connection of a virtual connection.
byte[]	peekVirtual(int connectionPort, int max, boolean blocking) As receiveVirtual() but leaves the data that was read in the connection port.
byte[]	receiveVirtual(int connectionPort, int max, boolean blocking) Reads available data from a connection port up to a specified maximum number of bytes.
SelectSets	select(SelectSets sets, boolean block, SelectRendezvous sr)
static void	sendMessage(BaseConnection bconn, org.acplt.oncrpc.XdrAble msg, int payloadSize) Sends a message over a base connection.
static void	sendOpenNack(BaseConnection bconn, int senderLport, int receiverCport, int errorCode, java.lang.String[] receiverSecSuites) Sends an 'open nack' message.
void	sendVirtual(int connectionPortNumber, byte[] buffer, int offset, int length) Writes data to a virtual connection.
void	setOwnerOfConnectionPort(int connectionPort, Role r) Set owner of connection port
void	setOwnerOfListenPort(int listenPort, Role r) Set owner of listen port
java.lang.String	toString() Returns a string representation of the mux

Methods inherited from class java.lang.Object

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

Field Detail

VIRTUAL_BACKLOG

public static final int VIRTUAL_BACKLOG

See Also:

Constant Field Values

MAX_PAYLOAD

protected static final int MAX_PAYLOAD

Maximum number of bytes of user-provided payload that we can fit into a payload message.

PROTO_HEADER_LENGTH

protected static final int PROTO_HEADER_LENGTH

Length in bytes of PROTO header V1

See Also:

Constant Field Values

_localDescriptorTable

protected LocalDescriptorTable _localDescriptorTable

Table for allocating connection ports and listen ports from a single address space

Constructor Detail

Mux

public Mux(java.net.InetSocketAddress contactPoint,
           int backlog,
           int nthreads,
           boolean secureComm,
           java.security.KeyStore keyStore,
           java.lang.String keyStorePassphrase)
    throws java.io.IOException,
           java.security.KeyStoreException,
           java.security.cert.CertificateException,
           java.security.NoSuchAlgorithmException,
           java.security.KeyManagementException,
           java.security.UnrecoverableKeyException,
           NoKnownSecuritySuiteException

Creates a multiplexer listening on a specific TCP/IP contact point.

Parameters:

contactPoint - the address of the TCP/IP contact point to listen on. If null, an address will be picked.

backlog - the listen backlog length. If <= 0, a default will be used

Throws:

java.io.IOException

java.security.KeyStoreException

java.security.cert.CertificateException

java.security.NoSuchAlgorithmException

java.security.KeyManagementException

java.security.UnrecoverableKeyException

NoKnownSecuritySuiteException

Method Detail

getInstance

public static Mux getInstance()

getContactPoint

public java.net.InetSocketAddress getContactPoint()

Returns the address of the base listener TCP/IP contact point.

connectVirtual

public int connectVirtual(Endpoint remote,
                          java.lang.String[] userSecSuites)
                   throws KernelException

Establishes a virtual connection with a remote contact point.

Parameters:

remote - the remote base endpoint

userSecSuites - a series of cipher suites acceptable to the caller, or null or empty to leave unspecified

Returns:

a local connection port number

Throws:

KernelException

createVirtualContactPoint

public int createVirtualContactPoint(int listenPortNumber,
                                     java.lang.String[] secSuites)
                              throws KernelException

Creates a listen port and makes it available as a virtual contact point. The port number can either be specified (explicit allocation) or left unspecified, in which case the multiplexer will pick an unused port number from the ephemeral range of port numbers. Explicit port numbers may be drawn from both the explicit and ephemeral ranges.

Parameters:

listenPortNumber - the listen port number to use, or 0 to leave unspecified

secSuites - a series of cipher suites acceptable to the caller, or null or empty to leave unspecified

Returns:

the listen port number allocated

Throws:

KernelException - if an attempt is made to explicitly allocate a listen port number that is already in use

acceptVirtual

public int acceptVirtual(int listenPortNumber,
                         boolean blocking)
                  throws KernelException

Returns the next connection waiting in a listen port. If blocking, waits until a connection becomes available.

Parameters:

listenPortNumber - the listen port number

blocking - whether to allow this method to block

Returns:

a local connection port number. 0 iff ! blocking and no connection was available

Throws:

UnknownEndpointDescrException - if the listen port number is non-existent or closed

KernelException

closeMultiplexer

public void closeMultiplexer()

Closes the base listener and base connections, and stops handler threads. This call renders the multiplexer unusable.

closeVirtualContactPoint

public void closeVirtualContactPoint(int listenPortNumber,
                                     int code)
                              throws KernelException

Destroys a listen port and its virtual contact point, and closes any pending connections.

Parameters:

listenPortNumber - the listen port number

Throws:

UnknownEndpointDescrException - if the listen port number is non-existent

KernelException

closeVirtual

public void closeVirtual(int connectionPortNumber,
                         int code)
                  throws KernelException

Closes a virtual connection. Pending unsent data will still be delivered (barring failures) as long as the remote endpoint does not close as well. sendVirtual() and receiveVirtual() calls on the virtual connection are illegal following this call.

Parameters:

connectionPortNumber - the local connection port number

Throws:

KernelException - if the connection port number is non-existent

sendVirtual

public void sendVirtual(int connectionPortNumber,
                        byte[] buffer,
                        int offset,
                        int length)
                 throws KernelException

Writes data to a virtual connection.

Parameters:

connectionPortNumber - the local connection port number

buffer - the buffer that holds the data

offset - where in the buffer the data begins

length - the length of the data

Throws:

PeerClosedConnectionException - the remote peer closed the connection

InputOutputException - an I/O error occurred (e.g. the base connection is broken or the call was illegal (e.g. port as already locally closed)

BadArgumentException - if buffer, offset or length does not make sense

UnknownConnectionIDException - if the connectionPortNumber is unknown

KernelException

receiveVirtual

public byte[] receiveVirtual(int connectionPort,
                             int max,
                             boolean blocking)
                      throws KernelException

Reads available data from a connection port up to a specified maximum number of bytes. If 'blocking', first blocks until at least one byte of data is available.

Parameters:

connectionPort - the connection port to read

max - maximum number of bytes to read

blocking - whether to allow this method to block

Returns:

the bytes read. Non-empty if blocking

Throws:

PeerClosedConnectionException - if no more data was available because the remote port was closed by the remote peer

InputOutputException - an I/O exception occurred (e.g. the base connection is closed) or the call was illegal (e.g. the port was already locally closed)

BadArgumentException - if 'max' is zero

UnknownConnectionIDException - if the connectionPortNumber is unknown

KernelException

peekVirtual

public byte[] peekVirtual(int connectionPort,
                          int max,
                          boolean blocking)
                   throws KernelException

As receiveVirtual() but leaves the data that was read in the connection port. The data will be read again by a subsequent receiveVirtual() or peekVirtual()

Throws:

KernelException

getRemoteConnectionPort

public int getRemoteConnectionPort(int connectionPortNumber)
                            throws UnknownConnectionIDException

Asks for the remote connection port number of a virtual connection.

Parameters:

connectionPortNumber - the local connection port number

Throws:

UnknownConnectionIDException - if the local connection port number is non-existent

getRemoteSocketAddress

public java.net.InetSocketAddress getRemoteSocketAddress(int connectionPortNumber)
                                                  throws KernelException

Asks for the remote TCP/IP connection socket address of the base connection of a virtual connection.

Parameters:

connectionPortNumber - the local connection port number

Throws:

UnknownConnectionIDException - if the local connection port number is non-existent

KernelException

getRemoteSCID

public java.lang.String getRemoteSCID(int connectionPortNumber)
                               throws UnknownConnectionIDException,
                                      AuthenticationException

Asks for the remote SCID of a virtual connection.

Parameters:

connectionPortNumber - the local connection port number

Throws:

UnknownConnectionIDException - if the local connection port number is non-existent

AuthenticationException - if the remoteSCID could not be established

sendOpenNack

public static void sendOpenNack(BaseConnection bconn,
                                int senderLport,
                                int receiverCport,
                                int errorCode,
                                java.lang.String[] receiverSecSuites)
                         throws KernelException

Sends an 'open nack' message. Closes the base connection on error.

Parameters:

bconn - the connection to send the message over

senderLport - message field: listen port of the sender

receiverCport - message field: connection port of the receiver

errorCode - message field: reason for closure

receiverSecSuites - message field (if applicable) acceptable set suites

Throws:

KernelException - a communication error occurred

sendMessage

public static void sendMessage(BaseConnection bconn,
                               org.acplt.oncrpc.XdrAble msg,
                               int payloadSize)
                        throws KernelException

Sends a message over a base connection. Closes the base connection on error.

Parameters:

payloadSize - the size of any user-provided payload data included in the message

Throws:

KernelException - a communication error occurred

setOwnerOfListenPort

public void setOwnerOfListenPort(int listenPort,
                                 Role r)
                          throws KernelException

Set owner of listen port

Parameters:

listenPort - the port in question

r - the prospective owner

Throws:

KernelException

checkOwnerOfListenPort

public void checkOwnerOfListenPort(int listenPort,
                                   Role r)
                            throws AccessDeniedException,
                                   UnknownEndpointDescrException

Check ownership of listen port

Parameters:

listenPort - the port in question

r - the expected owner

Throws:

AccessDeniedException

UnknownEndpointDescrException

setOwnerOfConnectionPort

public void setOwnerOfConnectionPort(int connectionPort,
                                     Role r)
                              throws KernelException

Set owner of connection port

Parameters:

connectionPort - the port in question

r - the prospective owner

Throws:

KernelException

checkOwnerOfConnectionPort

public void checkOwnerOfConnectionPort(int connectionPort,
                                       Role r)
                                throws AccessDeniedException,
                                       UnknownConnectionIDException

Check ownership of connection port

Parameters:

connectionPort - the port in question

r - the expected owner

Throws:

AccessDeniedException - if the port belongs to another role

UnknownConnectionIDException - if the port is unknown

deletePortsOwnedBy

public void deletePortsOwnedBy(Role r)

Deletes all connection and listen ports owned by role.

checkOwnerOfPortSets

public void checkOwnerOfPortSets(SelectSets sets,
                                 Role r)
                          throws AccessDeniedException,
                                 UnknownConnectionIDException,
                                 UnknownEndpointDescrException,
                                 BadArgumentException

Throws:

AccessDeniedException

UnknownConnectionIDException

UnknownEndpointDescrException

BadArgumentException

select

public SelectSets select(SelectSets sets,
                         boolean block,
                         SelectRendezvous sr)
                  throws KernelException

Throws:

KernelException

See Also:

AOSapi.select(org.iids.aos.kernel.Cookie, org.iids.aos.kernel.SelectSets, boolean)

toString

public java.lang.String toString()

Returns a string representation of the mux

Overrides:

toString in class java.lang.Object

Returns:

string representation