org.exolab.core.messenger
Class PacketChannel

java.lang.Object
  org.exolab.core.messenger.PacketChannel

All Implemented Interfaces:

Channel

public class PacketChannel

extends java.lang.Object

implements Channel

A PacketConnection is a Connection that minimises resource usage.

This is achieved by:

• Restricting the number of physical connections by sharing them between multiple Channel instances
• Breaking large messages into packets, allowing multiple channels to use the connection at the same time
• Optionally restricting the number of packets used by the connection, to avoid OutOfMemoryError exceptions being thrown during high activity on the connection

Version:

$Revision: 1.5 $ $Date: 2003/06/09 06:28:40 $

Author:

Tim Anderson

See Also:

PacketConnection, PacketPool, PacketInputStream, PacketOutputStream

Field Summary

static int	ACCEPTOR_CHANNEL_ID The identifier for the channel to accept open and close requests
static int	CONNECTION_ACCEPT_CHANNEL_ID The identifier for the connection acceptor channel
static int	CONNECTION_CHANNEL_ID The identifier for the connection channel
static int	HANDSHAKE_CHANNEL_ID The identifier for the handshaking channel
static int	LAST_SYSTEM_ID The last system channel identifier
static int	SYSTEM_CHANNEL_ID The identifier for the system channel

Constructor Summary

PacketChannel(PacketConnection connection, int channelId, int destinationId, PacketQueue inputQueue)
Create a new channel

Method Summary

void	close() Close the channel.
protected void	closeListener() Closes the listener
protected void	doClose() Closes the channel, without notifying the opposing channel instance
protected java.lang.Object	doReceive(long timeout) Receive the next message that arrives within the specified timeout interval.
protected void	enqueue(org.exolab.core.messenger.Packet packet) Enqueues a packet on the inbound queue, for de-serializing. If a ChannelHandler is registered, it will be queued for notification using the thread pool
int	getChannelId() Returns the channel identifier.
protected PacketConnection	getConnection() Returns a reference to the owning connection
protected void	handlerCompleted()
java.lang.Object	invoke(java.lang.Object request) Send a message and wait for a response
boolean	isClosed() Returns true if this channel is closed
java.lang.Object	receive() Receive a message.
java.lang.Object	receive(long timeout) Receive the next message that arrives within the specified timeout interval.
void	send(java.lang.Object message) Send a message
protected void	send(java.lang.Object message, byte type, int destinationId) Send a message to the specified destination channel
void	setChannelListener(ChannelListener listener) Register a listener to process messages asynchronously. Only a single listener may be registered at any one time. Setting the listener to null deregisters the listener. > NOTE: the listener will be invoked in a separate thread - to maintain the single threaded nature of channels, it is an error to call send(java.lang.Object), receive(), or invoke(java.lang.Object) from any other thread other than that running the listener, while the listener is registered.
protected void	setInvoke(boolean invoke) Sets the 'invoke handler' flag.

Methods inherited from class java.lang.Object

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

Field Detail

CONNECTION_CHANNEL_ID

public static final int CONNECTION_CHANNEL_ID

The identifier for the connection channel

See Also:

Constant Field Values

CONNECTION_ACCEPT_CHANNEL_ID

public static final int CONNECTION_ACCEPT_CHANNEL_ID

The identifier for the connection acceptor channel

See Also:

Constant Field Values

SYSTEM_CHANNEL_ID

public static final int SYSTEM_CHANNEL_ID

The identifier for the system channel

See Also:

Constant Field Values

ACCEPTOR_CHANNEL_ID

public static final int ACCEPTOR_CHANNEL_ID

The identifier for the channel to accept open and close requests

See Also:

Constant Field Values

HANDSHAKE_CHANNEL_ID

public static final int HANDSHAKE_CHANNEL_ID

The identifier for the handshaking channel

See Also:

Constant Field Values

LAST_SYSTEM_ID

public static final int LAST_SYSTEM_ID

The last system channel identifier

See Also:

Constant Field Values

Constructor Detail

PacketChannel

public PacketChannel(PacketConnection connection,
                     int channelId,
                     int destinationId,
                     PacketQueue inputQueue)

Create a new channel

Parameters:

connection - the owning connection

channelId - the channel identifier

destinationId - the destination channel identifier

inputQueue - the inbound packet queue, to deserialize messages from

Throws:

java.lang.IllegalArgumentException - if any argument is null

Method Detail

getChannelId

public int getChannelId()

Returns the channel identifier. This is unique to a connection

Returns:

the channel identifier

send

public void send(java.lang.Object message)
          throws java.rmi.RemoteException

Send a message

Specified by:

send in interface Channel

Parameters:

message - the object to send

Throws:

java.rmi.RemoteException - if the message can't be sent

receive

public java.lang.Object receive()
                         throws java.rmi.RemoteException

Receive a message. This method blocks until a message is received.

Specified by:

receive in interface Channel

Returns:

the received message

Throws:

java.rmi.RemoteException - if the message can't be received

receive

public java.lang.Object receive(long timeout)
                         throws java.rmi.RemoteException

Receive the next message that arrives within the specified timeout interval.

This call blocks until a message arrives, the timeout expires, or the channel is closed. A timeout of zero never expires and the call blocks indefinitely.

Specified by:

receive in interface Channel

Parameters:

timeout - the timeout value (in milliseconds)

Returns:

the received message

Throws:

java.rmi.RemoteException - if a message can't be received

ReceiveTimeoutException - if no message is available within the specified interval

invoke

public java.lang.Object invoke(java.lang.Object request)
                        throws java.lang.Exception,
                               java.rmi.RemoteException

Send a message and wait for a response

Specified by:

invoke in interface Channel

Parameters:

request - the object to send

Returns:

the response

Throws:

java.lang.Exception - if the server throws an exception

java.rmi.RemoteException - if the message can't be sent or the response can't be received

setChannelListener

public void setChannelListener(ChannelListener listener)

Register a listener to process messages asynchronously.
Only a single listener may be registered at any one time.
Setting the listener to null deregisters the listener.

> NOTE: the listener will be invoked in a separate thread - to maintain the single threaded nature of channels, it is an error to call send(java.lang.Object), receive(), or invoke(java.lang.Object) from any other thread other than that running the listener, while the listener is registered.

Specified by:

setChannelListener in interface Channel

Parameters:

listener - the listener to process messages, or null, to deregister the current listener

close

public void close()
           throws java.rmi.RemoteException

Close the channel. This notifies the opposing channel instance that this has closed, and notifies the ChannelListener if one is registered.

Specified by:

close in interface Channel

Throws:

java.rmi.RemoteException - if an I/O error occurs closing the channel

isClosed

public boolean isClosed()

Returns true if this channel is closed

doReceive

protected java.lang.Object doReceive(long timeout)
                              throws java.rmi.RemoteException

Receive the next message that arrives within the specified timeout interval.

This call blocks until a message arrives, the timeout expires, or the channel is closed. A timeout of zero never expires and the call blocks indefinitely.

Parameters:

timeout - the timeout value (in milliseconds)

Returns:

the received message

Throws:

java.rmi.RemoteException - if a message can't be received

ReceiveTimeoutException - if no message is available within the specified interval

doClose

protected void doClose()

Closes the channel, without notifying the opposing channel instance

closeListener

protected void closeListener()

Closes the listener

setInvoke

protected void setInvoke(boolean invoke)

Sets the 'invoke handler' flag. This is used to prevent the channel being used during an invocation.

Parameters:

invoke - if true prevent the channel being used for send(java.lang.Object), receive(), and invoke(java.lang.Object)

getConnection

protected PacketConnection getConnection()

Returns a reference to the owning connection

send

protected void send(java.lang.Object message,
                    byte type,
                    int destinationId)
             throws java.rmi.RemoteException

Send a message to the specified destination channel

Parameters:

message - the message to send

type - the message type

destinationId - the destination channel id

Throws:

java.rmi.RemoteException - if an I/O error occurs

enqueue

protected void enqueue(org.exolab.core.messenger.Packet packet)

Enqueues a packet on the inbound queue, for de-serializing.
If a ChannelHandler is registered, it will be queued for notification using the thread pool

Parameters:

packet - the packet to queue on the inbound queue

handlerCompleted

protected void handlerCompleted()