uk.ac.rdg.resc.jstyx.client
Class StyxConnection

java.lang.Object
  uk.ac.rdg.resc.jstyx.client.StyxConnection

All Implemented Interfaces:

org.apache.mina.protocol.ProtocolHandler

public class StyxConnection
extends java.lang.Object
implements org.apache.mina.protocol.ProtocolHandler

Object representing a client connection to a Styx server.

Author:

Jon Blower $Revision: 604 $ $Date: 2006-03-21 14:58:42 +0000 (Tue, 21 Mar 2006) $ $Log$ Revision 1.28 2006/03/21 14:58:41 jonblower Implemented clear-text password-based authentication and did some simple tests Revision 1.27 2006/03/21 09:06:14 jonblower Still implementing authentication Revision 1.24 2005/08/08 09:35:19 jonblower Commented out thread pool filters Revision 1.23 2005/07/08 16:01:27 jonblower Reinstated ProtocolThreadPoolFilter Revision 1.22 2005/07/08 15:22:54 jonblower Upgraded MINA library to 0.7.3-SNAPSHOT Revision 1.21 2005/06/27 17:17:15 jonblower Changed MessageCallback to pass Tmessage as parameter, rather than storing in the instance Revision 1.18 2005/05/25 15:37:55 jonblower Removed cache of CStyxFiles, dealt differently with root fid Revision 1.17 2005/05/23 16:48:17 jonblower Overhauled CStyxFile (esp. asynchronous methods) and StyxConnection (added cache of CStyxFiles) Revision 1.16 2005/05/16 16:16:52 jonblower Implemented getRemoteHost() and getRemotePort() Revision 1.15 2005/05/16 13:09:54 jonblower Added StyxConnection object as first argument in all StyxConnectionListener methods Revision 1.14 2005/05/16 12:57:39 jonblower Constructors no longer throw StyxException Revision 1.13 2005/05/09 13:35:48 jonblower Now throws an exception if try to send a message before connecting Revision 1.12 2005/05/05 16:57:31 jonblower Updated MINA library to revision 168337 and changed code accordingly Revision 1.11 2005/03/22 17:42:24 jonblower Changed default message size to 8192 for efficiency in MINA Revision 1.10 2005/03/22 10:19:52 jonblower Fixed problem with ByteBuffer leak in StyxMessageDecoder and StyxFileInputStream Revision 1.9 2005/03/17 07:30:05 jonblower Improved error logging code Revision 1.8 2005/03/16 17:55:52 jonblower Replaced use of java.nio.ByteBuffer with MINA's ByteBuffer to minimise copying of buffers Revision 1.7 2005/03/15 15:51:37 jonblower Removed hard limit on maximum message size Revision 1.6 2005/03/11 13:58:25 jonblower Merged MINA-Test_20059309 into main line of development Revision 1.5.2.2 2005/03/11 08:29:52 jonblower Moved to log4j logging system (from apache commons logging) Revision 1.5.2.1 2005/03/10 11:48:30 jonblower Updated to fit in with MINA framework Revision 1.4 2005/02/21 18:07:23 jonblower Separated constructor and connect methods Revision 1.3 2005/02/18 17:56:31 jonblower Set root directory in constructor; doesn't need to wait until connection is made Revision 1.1.1.1 2005/02/16 18:58:19 jonblower Initial import

Constructor Summary

StyxConnection(java.lang.String host, int port)
Creates a new instance of StyxConnection, connecting as an anonymous user

StyxConnection(java.lang.String host, int port, int maxMessageSizeRequest)
Creates a new instance of StyxConnection, connecting as an anonymous user

StyxConnection(java.lang.String host, int port, java.lang.String username, java.lang.String password)
Uses DEFAULT_MAX_MESSAGE_SIZE_REQUEST

StyxConnection(java.lang.String host, int port, java.lang.String username, java.lang.String password, int maxMessageSizeRequest)
Creates a new instance of StyxConnection.

Method Summary

void	addListener(StyxConnectionListener listener) Adds a StyxConnectionListener to this connection.
void	close() Overrides the close() method in Session.
void	connect() Connects to the remote server and handshakes.
void	connectAsync() Connects to the remote server and handshakes.
void	exceptionCaught(org.apache.mina.protocol.ProtocolSession session, java.lang.Throwable cause) Called when an exception is caught by MINA; fires the connectError() event on all registered listeners and closes the connection.
java.lang.String	getContents(java.lang.String path) Gets the entire contents of a file as a single string.
CStyxFile	getFile(java.lang.String path) Gets a CStyxFile with the given path.
long	getFreeFid()
int	getMaxMessageSize()
java.lang.String	getRemoteHost()
int	getRemotePort()
CStyxFile	getRootDirectory() Gets the CStyxFile representing the root directory of the remote Styx server
long	getRootFid()
void	messageReceived(org.apache.mina.protocol.ProtocolSession session, java.lang.Object message) Called when a reply has arrived from a Styx server
void	messageSent(org.apache.mina.protocol.ProtocolSession session, java.lang.Object message) Called by MINA when a message has been sent
CStyxFile	openFile(java.lang.String path, int mode) Opens a file on the server, throwing a StyxException if the file can't be found or opened in the given mode.
void	removeListener(StyxConnectionListener listener) Removes the given listener; does nothing if the listener has not been registered with this.addListener().
void	returnFid(long fid) Returns the given fid back to the pool
StyxMessage	send(StyxMessage message) Sends a message and blocks until the corresponding reply arrives
int	sendAsync(StyxMessage tMessage, MessageCallback callback) Sends a message and returns its tag.
int	sendAsync(StyxMessage tMessage, MessageCallback callback, boolean isHandshake) Sends a message and returns its tag.
void	sessionClosed(org.apache.mina.protocol.ProtocolSession session) Called when the connection is closed
void	sessionCreated(org.apache.mina.protocol.ProtocolSession session) Invoked when the session is created.
void	sessionIdle(org.apache.mina.protocol.ProtocolSession session, org.apache.mina.common.IdleStatus status) Required by the ProtocolHandler interface.
void	sessionOpened(org.apache.mina.protocol.ProtocolSession session) Called when the socket connection to the remote server has been established
void	setMaxMessageSize(int maxMessageSize) Sets the maximum size of message that can be sent on this connection

Methods inherited from class java.lang.Object

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

Constructor Detail

StyxConnection

public StyxConnection(java.lang.String host,
                      int port,
                      java.lang.String username,
                      java.lang.String password,
                      int maxMessageSizeRequest)

Creates a new instance of StyxConnection. This does not actually make the connection; call connectAsync() or connect() to do this.

StyxConnection

public StyxConnection(java.lang.String host,
                      int port,
                      java.lang.String username,
                      java.lang.String password)

Uses DEFAULT_MAX_MESSAGE_SIZE_REQUEST

StyxConnection

public StyxConnection(java.lang.String host,
                      int port,
                      int maxMessageSizeRequest)

Creates a new instance of StyxConnection, connecting as an anonymous user

StyxConnection

public StyxConnection(java.lang.String host,
                      int port)

Creates a new instance of StyxConnection, connecting as an anonymous user

Method Detail

getRemoteHost

public java.lang.String getRemoteHost()

Returns:

the name (or IP address) of the remote host

getRemotePort

public int getRemotePort()

Returns:

the port of the remote host

connectAsync

public void connectAsync()
                  throws StyxException

Connects to the remote server and handshakes. This method returns immediately; when the connection and handshaking are complete, the connectionReady() event will be fired on all registered StyxConnectionListeners. If an error occurred when connecting or handshaking, the connectionError() event will be fired on the listeners. This method will do nothing if we have already connected or are in the process of connecting.

Throws:

StyxException - if the IOProcessor could not be started

connect

public void connect()
             throws StyxException

Connects to the remote server and handshakes. This method blocks until the connection is made and the handshaking is complete, throwing a StyxException if an error occurred when connecting. If the connection is already made, this method does nothing. The connectionReady() and connectionError() events will be fired on any registered listeners when the connection is ready or if an error occurs.

Throws:

StyxException - if the IOProcessor could not be started or if an error occurred during connection or handshaking

close

public void close()

Overrides the close() method in Session. Clunks all fids before closing the connection. Does nothing if the connection has not been made. If the connection has been made, but the handshaking has not been done, this will enqueue the close request so that, when handshaking is complete, the fids will be clunked. Note that there is a possibility that if close() is called immediately after connectAsync(), the call to close() will return (having done nothing) before the connection is open. TODO: what can we do about this? The session is only definitively closed when the connectionClosed() event is fired on the registered StyxConnectionListeners.

getRootDirectory

public CStyxFile getRootDirectory()

Gets the CStyxFile representing the root directory of the remote Styx server

sendAsync

public int sendAsync(StyxMessage tMessage,
                     MessageCallback callback)

Sends a message and returns its tag. Note that this method will return immediately. When the reply arrives, the replyArrived() method of the callback object will be called. (The callback can be null.). If the connection hasn't been made yet, the message will be put in a queue and will be sent when the connection is ready (TODO this is convenient as it saves waiting for the connectionReady() event, but is this the best thing to do?) If this is called before connect() or connectAsync(), the callback's error function will be called.

Parameters:

tMessage - the message to be sent

callback - the MessageCallback to be called when the reply arrives

Returns:

the tag of the outgoing message

sendAsync

public int sendAsync(StyxMessage tMessage,
                     MessageCallback callback,
                     boolean isHandshake)

Sends a message and returns its tag. Note that this method will return immediately. When the reply arrives, the replyArrived() method of the callback object will be called. (The callback can be null.). If the connection hasn't been made yet, the message will be put in a queue and will be sent when the connection is ready (TODO this is convenient as it saves waiting for the connectionReady() event, but is this the best thing to do?) If this is called before connect() or connectAsync(), the callback's error function will be called unless isHandshake==true;

Parameters:

tMessage - the message to be sent

callback - the MessageCallback to be called when the reply arrives

isHandshake - if true, this message is part of the connection process itself (e.g. authentication)

Returns:

the tag of the outgoing message

send

public StyxMessage send(StyxMessage message)
                 throws StyxException

Sends a message and blocks until the corresponding reply arrives

Throws:

StyxException - if the message type is not as expected, or if the connection has not been made.

messageReceived

public void messageReceived(org.apache.mina.protocol.ProtocolSession session,
                            java.lang.Object message)

Called when a reply has arrived from a Styx server

Specified by:

messageReceived in interface org.apache.mina.protocol.ProtocolHandler

getFreeFid

public long getFreeFid()

Returns:

the next unused fid, or -1 if there are none left (this is extremely unlikely and would require StyxUtils.MAXUINT tags to be in use - this would probably only happen due to a bug)

returnFid

public void returnFid(long fid)

Returns the given fid back to the pool

getRootFid

public long getRootFid()

Returns:

the fid associated with the root of the remote server

getMaxMessageSize

public int getMaxMessageSize()

Returns:

the maximum size of message that can be sent on this connection

setMaxMessageSize

public void setMaxMessageSize(int maxMessageSize)

Sets the maximum size of message that can be sent on this connection

sessionCreated

public void sessionCreated(org.apache.mina.protocol.ProtocolSession session)
                    throws java.lang.Exception

Invoked when the session is created. Initialize default socket parameters and user-defined attributes here.

Specified by:

sessionCreated in interface org.apache.mina.protocol.ProtocolHandler

Throws:

java.lang.Exception

sessionOpened

public void sessionOpened(org.apache.mina.protocol.ProtocolSession session)

Called when the socket connection to the remote server has been established

Specified by:

sessionOpened in interface org.apache.mina.protocol.ProtocolHandler

sessionClosed

public void sessionClosed(org.apache.mina.protocol.ProtocolSession session)

Called when the connection is closed

Specified by:

sessionClosed in interface org.apache.mina.protocol.ProtocolHandler

exceptionCaught

public void exceptionCaught(org.apache.mina.protocol.ProtocolSession session,
                            java.lang.Throwable cause)

Called when an exception is caught by MINA; fires the connectError() event on all registered listeners and closes the connection.

Specified by:

exceptionCaught in interface org.apache.mina.protocol.ProtocolHandler

getFile

public CStyxFile getFile(java.lang.String path)

Gets a CStyxFile with the given path. Note that each call to this method will return a new object, even if the path is identical. This does not open, create or check the existence of the file: no messages are sent to the server in this method so this will never block.

Throws:

InvalidPathException - if the given path is not valid and absolute (only catch this runtime exception if it is likely that the path could be invalid, e.g. when the path is being input by a user)

openFile

public CStyxFile openFile(java.lang.String path,
                          int mode)
                   throws StyxException

Opens a file on the server, throwing a StyxException if the file can't be found or opened in the given mode. Blocks until the file is open.

Parameters:

path - The path of the file relative to the server root.

mode - Integer representing the mode - see the constants in StyxUtils. For example, to open a file for reading, use StyxUtils.OREAD. To open a file for writing with truncation use StyxUtils.OWRITE | StyxUtils.OTRUNC.

Returns:

The file that has just been opened

Throws:

StyxException

getContents

public java.lang.String getContents(java.lang.String path)
                             throws StyxException

Gets the entire contents of a file as a single string. Opens the file for reading, reads the contents and closes the file. This should only be used for relatively short files that can sensibly fit into a String - do not use for large files as not only will this method block until the file is read, you may run into memory problems.

Parameters:

path - The path of the file relative to the server root.

Throws:

StyxException

addListener

public void addListener(StyxConnectionListener listener)

Adds a StyxConnectionListener to this connection. The methods of the listener will be called when events happen, such as the connection being ready for messages, the connection being closed, and an error in connection. If this listener is already registered, this method does nothing.

removeListener

public void removeListener(StyxConnectionListener listener)

Removes the given listener; does nothing if the listener has not been registered with this.addListener().

messageSent

public void messageSent(org.apache.mina.protocol.ProtocolSession session,
                        java.lang.Object message)

Called by MINA when a message has been sent

Specified by:

messageSent in interface org.apache.mina.protocol.ProtocolHandler

sessionIdle

public void sessionIdle(org.apache.mina.protocol.ProtocolSession session,
                        org.apache.mina.common.IdleStatus status)

Required by the ProtocolHandler interface. Does nothing in this class.

Specified by:

sessionIdle in interface org.apache.mina.protocol.ProtocolHandler