org.caleigo.toolkit.tunnel
Interface ITunnel

All Known Implementing Classes:

AbstractTunnel

public interface ITunnel

An ITunnel is responsible for sending messages between clients and a server. It hides the underlying protocol that is used for the communication and presents a clean interface for sending and receiving messages. It also handles the transformation of messages into sendable data and makes it possible to add any number of transformation of the data before it is sent.

Incoming messages are handled by IMessageConsumers. The ITunnel maintains a list of IMessageConsumers. When a message is received they are asked in order if they accept the message. The first IMessgeConsumer that accepts the message becomes the conumer for that message.

The ITunnel also maintains a list of ITunnelPackers. These packers a responsible for packing messages that are sent and unpacking messages that are received.

Version:

1.00

Author:

Dennis Zikovic

Method Summary

void	addMessageConsumer(IMessageConsumer consumer) Adds the consumer to the end of this ITunnels message consumer list.
void	addPacker(ITunnelPacker packer) Adds the packer to the end of this ITunnels packer list.
void	addStatusCallback(IStatusCallback callback) Adds the callback to the list of IStatusCallbacks that receives status messages from this ITunnel.
void	addTunnelListener(ITunnelListener listener)
java.lang.Object	ask(java.lang.Object message) Sends a request/reply message over this ITunnel.
void	finalize() Performs cleanup for this ITunnel.
java.lang.String	getDescription() Returns a humanly readably text that describes the ITunnel.
int	getLogLevel() Gets the log level for this ITunnel.
void	initialize() Initializes the ITunnel.
boolean	isActive() Returns true if this tunnel is active, that is, if it is correctly initialized.
int	ping() Sends a ping message over this ITunnel.
void	remomveMessageConsumer(IMessageConsumer consumer) Removes the consumer from this ITunnels message consumer list.
void	remomvePacker(ITunnelPacker packer) Removes the packer from this ITunnels packer list.
void	removeStatusCallback(IStatusCallback callback) Removes the callback from the list of IStatusCallbacks.
void	removeTunnelListener(ITunnelListener listener)
void	send(java.lang.Object message) Sends a message over this ITunnel.
void	setCodec(ITunnelCodec codec) Sets the ITunnelCodec that should be used by this ITunnel.
void	setLogLevel(int level) Sets the log level for this ITunnel.

Method Detail

initialize

public void initialize()
                throws java.lang.IllegalStateException,
                       TunnelException

Initializes the ITunnel. This method must be called before any messages can be sent. After this method has been called it is not possible to set the ITunnelCodec or to add or remove ITunnelPackers.

Throws:

java.lang.IllegalStateException

TunnelException

finalize

public void finalize()
              throws java.lang.IllegalStateException,
                     TunnelException

Performs cleanup for this ITunnel. No messages can be sent after this method has been called. This method will send all messages in the message queue before closing down.

Throws:

java.lang.IllegalStateException

TunnelException

isActive

public boolean isActive()

Returns true if this tunnel is active, that is, if it is correctly initialized. If this method returns true then a call to finalize must not throw an IllegalStateException.

ping

public int ping()
         throws TunnelException

Sends a ping message over this ITunnel. This method is typically used to check that the communication is working.

Returns:

the ping time in milli seconds.

Throws:

TunnelException

send

public void send(java.lang.Object message)
          throws TunnelException

Sends a message over this ITunnel. This method returns after the message has been sent.

Throws:

TunnelException

ask

public java.lang.Object ask(java.lang.Object message)
                     throws TunnelException

Sends a request/reply message over this ITunnel. This method blocks until the reply is received.

Throws:

TunnelException

addMessageConsumer

public void addMessageConsumer(IMessageConsumer consumer)

Adds the consumer to the end of this ITunnels message consumer list.

remomveMessageConsumer

public void remomveMessageConsumer(IMessageConsumer consumer)

Removes the consumer from this ITunnels message consumer list.

setCodec

public void setCodec(ITunnelCodec codec)
              throws java.lang.IllegalStateException

Sets the ITunnelCodec that should be used by this ITunnel.

Throws:

java.lang.IllegalStateException

addPacker

public void addPacker(ITunnelPacker packer)
               throws java.lang.IllegalStateException

Adds the packer to the end of this ITunnels packer list.

Throws:

java.lang.IllegalStateException

remomvePacker

public void remomvePacker(ITunnelPacker packer)
                   throws java.lang.IllegalStateException

Removes the packer from this ITunnels packer list.

Throws:

java.lang.IllegalStateException

addStatusCallback

public void addStatusCallback(IStatusCallback callback)

Adds the callback to the list of IStatusCallbacks that receives status messages from this ITunnel.

removeStatusCallback

public void removeStatusCallback(IStatusCallback callback)

Removes the callback from the list of IStatusCallbacks.

setLogLevel

public void setLogLevel(int level)

Sets the log level for this ITunnel.

getLogLevel

public int getLogLevel()

Gets the log level for this ITunnel.

addTunnelListener

public void addTunnelListener(ITunnelListener listener)

removeTunnelListener

public void removeTunnelListener(ITunnelListener listener)

getDescription

public java.lang.String getDescription()

Returns a humanly readably text that describes the ITunnel.