org.exolab.jms.net.multiplexer
Class Multiplexer

java.lang.Object
  |
  +--org.exolab.jms.net.multiplexer.Multiplexer

All Implemented Interfaces:

org.exolab.jms.net.multiplexer.Constants, java.lang.Runnable

public class Multiplexer

extends java.lang.Object

implements org.exolab.jms.net.multiplexer.Constants, java.lang.Runnable

This class multiplexes data over a physical connection.

Version:

$Revision: 1.9 $ $Date: 2006/12/16 12:37:17 $

Author:

Tim Anderson

Field Summary

static byte	AUTH_BASIC Indicates that the client is supplying user/password authentication details.
static byte	AUTH_DENIED Indicates that connection has been refused.
static byte	AUTH_NONE Indicates that a client is supplying no authentication details.
static byte	AUTH_OK Indicates that connection has been accepted.
static byte	CLOSE Indicates that a packet is a request to close an existing channel.
static byte	DATA Indicates the continuation of a stream of data packets.
static byte	FLOW_READ Indicates the no.
static int	MAGIC Magic no.
static byte	OPEN Indicates that a packet is a request to open a new channel.
static byte	PING_REQUEST Indicates that a packet is a ping request.
static byte	PING_RESPONSE Indicates that a packet is a ping response.
static byte	REQUEST Indicates the start of an invocation request.
static byte	RESPONSE Indicates the start of an invocation return.
static byte	SHUTDOWN Indicates to close the connection.
static int	VERSION Indicates that the packet contains protocol version.

Constructor Summary

protected	Multiplexer() Construct a new Multiplexer.
	Multiplexer(MultiplexerListener listener, Endpoint endpoint, Authenticator authenticator) Construct a new server-side Multiplexer.
	Multiplexer(MultiplexerListener listener, Endpoint endpoint, java.security.Principal principal) Construct a new client-side Multiplexer.

Method Summary

protected void	authenticate(Authenticator authenticator) Performs authentication on initial connection.
protected void	authenticate(java.security.Principal principal) Perform authentication on initial connection.
void	close() Close the multiplexer, releasing any resources.
void	close(org.exolab.jms.net.multiplexer.Channel channel) Close a channel.
org.exolab.jms.net.multiplexer.Channel	getChannel() Returns a free channel from the pool, opening a new one if none are available.
java.security.Principal	getPrincipal() Returns the principal that owns the connection.
protected void	handshake(java.io.DataOutputStream out, java.io.DataInputStream in) Perform handshaking on initial connection, to verify protocol.
protected void	initialise(MultiplexerListener listener, Endpoint endpoint, boolean client) Initialise the multiplexer.
boolean	isClient() Determines if this is a client-side instance.
boolean	isClosed() Determines if the multiplexer is closed.
protected org.exolab.jms.net.multiplexer.Channel	open() Opens a new channel.
void	ping(int token) Ping the connection.
void	release(org.exolab.jms.net.multiplexer.Channel channel) Releases a channel back to the pool.
void	run() Start multiplexing.
void	send(byte type) Send a message.
void	send(byte type, int channelId) Send a message.
void	send(byte type, int channelId, byte[] data, int offset, int length) Send a message.
void	send(byte type, int channelId, int data) Send a message.

Methods inherited from class java.lang.Object

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

Field Detail

MAGIC

public static final int MAGIC

Magic no. used in stream verification.

VERSION

public static final int VERSION

Indicates that the packet contains protocol version.

OPEN

public static final byte OPEN

Indicates that a packet is a request to open a new channel.

CLOSE

public static final byte CLOSE

Indicates that a packet is a request to close an existing channel.

REQUEST

public static final byte REQUEST

Indicates the start of an invocation request.

RESPONSE

public static final byte RESPONSE

Indicates the start of an invocation return.

DATA

public static final byte DATA

Indicates the continuation of a stream of data packets.

AUTH_BASIC

public static final byte AUTH_BASIC

Indicates that the client is supplying user/password authentication details.

AUTH_NONE

public static final byte AUTH_NONE

Indicates that a client is supplying no authentication details.

AUTH_OK

public static final byte AUTH_OK

Indicates that connection has been accepted.

AUTH_DENIED

public static final byte AUTH_DENIED

Indicates that connection has been refused.

PING_REQUEST

public static final byte PING_REQUEST

Indicates that a packet is a ping request.

PING_RESPONSE

public static final byte PING_RESPONSE

Indicates that a packet is a ping response.

FLOW_READ

public static final byte FLOW_READ

Indicates the no. of bytes read from the stream.

SHUTDOWN

public static final byte SHUTDOWN

Indicates to close the connection.

Constructor Detail

Multiplexer

public Multiplexer(MultiplexerListener listener,
                   Endpoint endpoint,
                   java.security.Principal principal)
            throws java.io.IOException,
                   SecurityException

Construct a new client-side Multiplexer.

Parameters:

listener - the multiplexer listener

endpoint - the endpoint to multiplex messages over

principal - the security principal

Throws:

java.io.IOException - if an I/O error occurs

SecurityException - if connection is refused by the server

Multiplexer

public Multiplexer(MultiplexerListener listener,
                   Endpoint endpoint,
                   Authenticator authenticator)
            throws java.io.IOException,
                   ResourceException

Construct a new server-side Multiplexer.

Parameters:

listener - the multiplexer listener

endpoint - the endpoint to multiplex messages over

authenticator - the connection authenticator

Throws:

java.io.IOException - if an I/O error occurs

ResourceException - if the authenticator cannot authenticate

Multiplexer

protected Multiplexer()

Construct a new Multiplexer.

This constructor is provided for subclasses that must perform setup work prior to invoking initialise(org.exolab.jms.net.multiplexer.MultiplexerListener, org.exolab.jms.net.multiplexer.Endpoint, boolean)

Method Detail

run

public void run()

Start multiplexing.

Specified by:

run in interface java.lang.Runnable

getChannel

public org.exolab.jms.net.multiplexer.Channel getChannel()
                                                  throws java.io.IOException

Returns a free channel from the pool, opening a new one if none are available.

Returns:

a free channel

Throws:

java.io.IOException - if an I/O error occurs

release

public void release(org.exolab.jms.net.multiplexer.Channel channel)

Releases a channel back to the pool.

Parameters:

channel - the channel to release

close

public void close(org.exolab.jms.net.multiplexer.Channel channel)
           throws java.io.IOException

Close a channel.

Parameters:

channel - the channel to close

Throws:

java.io.IOException - if an I/O error occurs

send

public void send(byte type)
          throws java.io.IOException

Send a message.

Parameters:

type - the packet type

Throws:

java.io.IOException - if an I/O error occurs

send

public void send(byte type,
                 int channelId)
          throws java.io.IOException

Send a message.

Parameters:

type - the packet type

channelId - the identifier of the channel sending the message

Throws:

java.io.IOException - if an I/O error occurs

send

public void send(byte type,
                 int channelId,
                 int data)
          throws java.io.IOException

Send a message.

Parameters:

type - the packet type

channelId - the identifier of the channel sending the message

data - the data to send

Throws:

java.io.IOException - if an I/O error occurs

send

public void send(byte type,
                 int channelId,
                 byte[] data,
                 int offset,
                 int length)
          throws java.io.IOException

Send a message.

Parameters:

type - the packet type

channelId - the identifier of the channel sending the message

data - the data to send

offset - the offset into the data

length - the length of data

Throws:

java.io.IOException - if an I/O error occurs

ping

public void ping(int token)
          throws java.io.IOException

Ping the connection.

Parameters:

token - the token to be returned in the reply

Throws:

java.io.IOException - if an I/O error occurs

close

public void close()

Close the multiplexer, releasing any resources. This closes the socket and waits for the thread to terminate.

isClosed

public boolean isClosed()

Determines if the multiplexer is closed.

Returns:

true if the multiplexer is closed

isClient

public boolean isClient()

Determines if this is a client-side instance.

Returns:

true if this is a client-side instance, false if it is a server=side instance

getPrincipal

public java.security.Principal getPrincipal()

Returns the principal that owns the connection.

Returns:

the principal that owns the connection, or null if this is an unauthenticated connection

initialise

protected void initialise(MultiplexerListener listener,
                          Endpoint endpoint,
                          boolean client)
                   throws java.io.IOException

Initialise the multiplexer.

Parameters:

listener - the multiplexer listener

endpoint - the endpoint to multiplex messages over

client - determines if this is a client-side or server-side instance

Throws:

java.io.IOException - if an I/O error occurs

handshake

protected void handshake(java.io.DataOutputStream out,
                         java.io.DataInputStream in)
                  throws java.io.IOException

Perform handshaking on initial connection, to verify protocol. Subclasses may extend this behaviour.

Parameters:

out - the endpoint's output stream

in - the endpoint's input stream

Throws:

java.io.IOException - for any I/O error

authenticate

protected void authenticate(java.security.Principal principal)
                     throws java.io.IOException,
                            SecurityException

Perform authentication on initial connection.

Parameters:

principal - the security principal. May be null

Throws:

java.io.IOException - for any I/O error

java.lang.SecurityException - if connection is refused by the server

authenticate

protected void authenticate(Authenticator authenticator)
                     throws java.io.IOException,
                            ResourceException

Performs authentication on initial connection.

Parameters:

authenticator - the authenticator

Throws:

java.io.IOException - for any I/O error

ResourceException - if the authenticator cannot authenticate

open

protected org.exolab.jms.net.multiplexer.Channel open()
                                               throws java.io.IOException

Opens a new channel.

Returns:

a new channel

Throws:

java.io.IOException - if a channel can't be opened