org.exolab.core.messenger
Interface Channel

All Known Subinterfaces:

SystemChannel

All Known Implementing Classes:

PacketChannel

public interface Channel

Version:

$Revision: 1.3 $ $Date: 2002/02/20 10:23:48 $

Author:

Tim Anderson

See Also:

Connection, ConnectionFactory, Messenger

Method Summary

void	close() Close the channel
java.lang.Object	invoke(java.lang.Object request) Send a message and wait for a response.
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
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.

Method Detail

send

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

Send a message

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.lang.ClassNotFoundException,
                                java.rmi.RemoteException

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

Returns:

the received message

Throws:

java.lang.ClassNotFoundException - if the class of a serialized object cannot be found

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.

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.

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.

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

Throws:

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