org.indy
Class Connection

java.lang.Object
  |
  +--org.indy.BaseComponent
        |
        +--org.indy.IndyComponent
              |
              +--org.indy.Connection

Direct Known Subclasses:

TCPServerConnection

public class Connection

extends IndyComponent

Provides extended functionality for using org.indy.IOHandlers, such as reading and writing primitives, checking response codes and extracting RFC compliant messages.

Author:

Owen Green

Inner Class Summary

protected static interface

Connection.Capturable An interface that supports having lines of text input to it.

Inner classes inherited from class org.indy.IndyComponent

IndyComponent.WorkMode

Field Summary

protected IOHandler	ioHandler The IOHandler used by this connection
protected RFCReply	lastCmdResult Holds the result of the last command for reply checking

Constructor Summary

Connection(IOHandler handler)
Constructs a new instance of TCPConnection

Method Summary

java.lang.String	allData() Reads all data from the connection until disconnection occurs, and returns it as a String using the platform character encoding.
java.lang.String	allData(java.lang.String encoding) Reads all data from the connection until disconnection occurs, and returns it as a String using the character encoding specified by encoding, or the platform default if encoding is null.
int	capture(java.lang.StringBuffer strings, java.lang.String delim, boolean isRFC) Reads lines of text from the connection into a StringBuffer until delim is found and returns the number of lines read.
int	capture(StringList strings, java.lang.String delim, boolean isRFC) Reads lines of text from the connection until into a StringList delim is found and returns the number of lines read.
int	checkResponse(int response, int[] allowedResponses) Checks whether a numeric response code is within a desired list of responses.
byte[]	currentReadBuffer() Returns the current data that can be read without blocking.
void	disconnect() Disconnects this connection.
void	disconnectSocket()
protected void	getInternalResponse() Used to implement the processing required for getResponse(int[]).
IOHandler	getIOHandler() Gets the iOHandler attribute of the TCPConnection object
int	getMaximumLineLength() Gets the maxLineLength attribute of the IdTCPConnection object
int	getReadTimeOut() Returns the timeout for read operations.
int	getResponse(int allowedResponse) Retreives a response from the connection using getInternalResponse and checks it for validity.
int	getResponse(int[] allowedResponses) Reads a response from the remote peer, typically of the form of a response code and some text, and checks that the code is within allowedResponses.
boolean	isConnected() Checks whether this TCP connection is still connected.
protected int	performCapture(Connection.Capturable dest, java.lang.String delim, boolean isRFCMessage) Reads lines from the connection into dest until delim is hit, and returns the number of lines read into dest
int	readBuffer(byte[] b, int len) Fills a buffer, b, with up to len bytes of data from the connection.
char	readChar() Read a char from the connection
int	readInt() Reads an int from this connection.
java.lang.String	readLine() Reads a line of text from the connection.
java.lang.String	readLine(int timeout, int maxLineLength) Reads a line of text from the connection.
java.lang.String	readLineWait() DOCUMENT ME!
java.lang.String	readLineWait(int failCount) Invokes readLine and will allow upto failCount time outs before throwing ReadTimedOutException.
long	readLong() Reads a long from the connection
short	readShort() Reads a short from the connection
java.io.InputStream	readStream(int byteCount, boolean readUntilDisconnect) Reads bytes from the socket and returns them in an InputStream.
protected byte[]	readTillDisconnect() DOCUMENT ME!
protected void	resetConnection() Resets this connection
void	setIOHandler(IOHandler handler) Sets the iOHandler attribute of the IdTCPConnection object
void	setMaxLineLength(int newLen) Sets the maxLineLength attribute of the TCPConnection object
void	setReadTimeOut(int timeout) Sets the timeout for read operations.
void	write(java.lang.String s) Write a String to this connection.
void	writeBuffer(byte[] buf) Write a buffer of bytes to this connection.
void	writeFile(java.io.File f) Writes a File object to the stream
void	writeHeader(StringList header) Write the contents of a StringList as an RFC header, translating strings of the form
void	writeInt(int value)
void	writeLine(java.lang.String line) Write a line of text to the connection.
void	writeLong(long value) Write a long to the connection
void	writeRFCReply(RFCReply reply) Write an RFCReply to this connection.
void	writeRFCStrings(StringList strings) Write the contents of a StringList instance to this connection.
void	writeShort(short value) Write a short to the connection
void	writeStream(java.io.InputStream stream, int len, boolean writeByteCount) Writes the contents of an InputStream to the connection
void	writeStrings(StringList strings, boolean writeLineCount) Write a the contents of a StringList instance to the connection as individual lines.

Methods inherited from class org.indy.IndyComponent

addComponentListener, doBeginWork, doBeginWork, doEndWork, doStatus, doStatus, doWork, getLocalName, removeComponentListener

Methods inherited from class org.indy.BaseComponent

getVersion

Methods inherited from class java.lang.Object

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

Field Detail

ioHandler

protected IOHandler ioHandler

The IOHandler used by this connection

lastCmdResult

protected RFCReply lastCmdResult

Holds the result of the last command for reply checking

Constructor Detail

Connection

public Connection(IOHandler handler)

Constructs a new instance of TCPConnection

Parameters:

handler - The IOHandler for this connection to use

Method Detail

setMaxLineLength

public void setMaxLineLength(int newLen)

Sets the maxLineLength attribute of the TCPConnection object

Parameters:

newLen - The new maxLineLength value

setReadTimeOut

public void setReadTimeOut(int timeout)
                    throws IndyIOException

Sets the timeout for read operations.

Parameters:

timeout - The new readTimeOut value

setIOHandler

public void setIOHandler(IOHandler handler)

Sets the iOHandler attribute of the IdTCPConnection object

Parameters:

handler - The new iOHandler value

getMaximumLineLength

public int getMaximumLineLength()

Gets the maxLineLength attribute of the IdTCPConnection object

Returns:

The maxLineLength value

getReadTimeOut

public int getReadTimeOut()
                   throws IndyIOException

Returns the timeout for read operations.

Returns:

The readTimeOut value

isConnected

public boolean isConnected()

Checks whether this TCP connection is still connected.

Returns:

true if the connection is still active, false otherwise.

Throws:

ConnectionClosedGracefullyException - If the connection closes gracefully

getIOHandler

public IOHandler getIOHandler()

Gets the iOHandler attribute of the TCPConnection object

Returns:

The iOHandler value

performCapture

protected final int performCapture(Connection.Capturable dest,
                                   java.lang.String delim,
                                   boolean isRFCMessage)
                            throws IndyIOException,
                                   ReadTimedOutException,
                                   PeerDisconnectedException,
                                   MaxLineLengthExceededException,
                                   NotConnectedException

Reads lines from the connection into dest until delim is hit, and returns the number of lines read into dest

Parameters:

dest - The Captureable to add lines to

delim - The delimiter to used demarcate the message

isRFCMessage - Whether the incoming text should be treated as part of an RFC message

Returns:

The number of lines read

Throws:

IndyIOException - if an IO error occurs

ReadTimedOutException - if the read operation times out

PeerDisconnectedException - if the remote connection disconnects

MaxLineLengthExceededException - if the maximum line lentgh is exceeded

NotConnectedException - if not connected

capture

public final int capture(StringList strings,
                         java.lang.String delim,
                         boolean isRFC)
                  throws IndyIOException,
                         ReadTimedOutException,
                         PeerDisconnectedException,
                         MaxLineLengthExceededException,
                         NotConnectedException

Reads lines of text from the connection until into a StringList delim is found and returns the number of lines read.

Parameters:

strings - The StringList to fill

delim - The delimter to read up to

isRFC - Whether the text should be interpreted as part of an RFC message

Returns:

The number of lines read

Throws:

IndyIOException - if an IO error occurs

ReadTimedOutException - if the read operation times out

PeerDisconnectedException - if the remote peer disconnects

MaxLineLengthExceededException - if the maximum line length is exceeded

NotConnectedException - if not connected

capture

public final int capture(java.lang.StringBuffer strings,
                         java.lang.String delim,
                         boolean isRFC)
                  throws IndyIOException,
                         ReadTimedOutException,
                         PeerDisconnectedException,
                         MaxLineLengthExceededException,
                         NotConnectedException

Reads lines of text from the connection into a StringBuffer until delim is found and returns the number of lines read.

Parameters:

strings - The StringBuffer to fill

delim - the delimiter to look for

isRFC - true if this should be treated as an RFC message

Returns:

the number of lines read

Throws:

IndyIOException - if an IO error occurs

ReadTimedOutException - if the read operation times out

PeerDisconnectedException - if the remote peer disconnects

MaxLineLengthExceededException - if the maximum line length is exceeded

NotConnectedException - if not connected

resetConnection

protected void resetConnection()

Resets this connection

disconnect

public void disconnect()

Disconnects this connection.

Throws:

IndyIOException - If an IO error occurs

disconnectSocket

public void disconnectSocket()

checkResponse

public int checkResponse(int response,
                         int[] allowedResponses)
                  throws ProtocolException

Checks whether a numeric response code is within a desired list of responses. If so, the response is returned otherwise a ProtocolException is thrown.

Parameters:

response - The response being examined

allowedResponses - The allowed responses

Returns:

The response encountered

Throws:

ProtocolException - if the response is not in the allowed list

getResponse

public int getResponse(int[] allowedResponses)
                throws PeerDisconnectedException,
                       ReadTimedOutException,
                       IndyIOException,
                       ProtocolException,
                       MaxLineLengthExceededException,
                       NotConnectedException

Reads a response from the remote peer, typically of the form of a response code and some text, and checks that the code is within allowedResponses. If not a ProtocolException is thrown, otherwise the response encountered is returned.

Parameters:

allowedResponses - The response codes allowed

Returns:

The encountered response

Throws:

PeerDisconnectedException - If the remote host disconnects

ReadTimedOutException - If the read operation times out

IndyIOException - If an IO error occurs

ProtocolException - If the response is not in allowed set

MaxLineLengthExceededException - If the maximum line length is exceeded

NotConnectedException - If not connected

getResponse

public int getResponse(int allowedResponse)
                throws PeerDisconnectedException,
                       ReadTimedOutException,
                       IndyIOException,
                       ProtocolException,
                       MaxLineLengthExceededException,
                       NotConnectedException

Retreives a response from the connection using getInternalResponse and checks it for validity. This is an alias for getResponse(int[])

Parameters:

allowedResponse - The expected response

Returns:

The response, if found

Throws:

PeerDisconnectedException - if the remote peer disconnected

ReadTimedOutException - if the read operation timed out

IndyIOException - if an IO error occured

ProtocolException - if the desired response was not returned

MaxLineLengthExceededException - if the maximum line length was exceeded

NotConnectedException - if not connected

getInternalResponse

protected void getInternalResponse()
                            throws IndyIOException,
                                   ReadTimedOutException,
                                   PeerDisconnectedException,
                                   MaxLineLengthExceededException,
                                   NotConnectedException

Used to implement the processing required for getResponse(int[]). A response, typically expected to be comptrised of a three digit code and some text is read and stored using readLineWait()

Throws:

IndyIOException - if an IO error occurs

ReadTimedOutException - if the read operation times out

PeerDisconnectedException - if the remote peer disconnectes

MaxLineLengthExceededException - if the maximum line length is exceeded

NotConnectedException - if not connected

readLineWait

public java.lang.String readLineWait(int failCount)
                              throws IndyIOException,
                                     ReadTimedOutException,
                                     PeerDisconnectedException,
                                     MaxLineLengthExceededException,
                                     NotConnectedException

Invokes readLine and will allow upto failCount time outs before throwing ReadTimedOutException.

Parameters:

failCount - The number of time outs to allow before failing

Returns:

A line of text from the connection.

Throws:

IndyIOException - If an IO error occurs.

ReadTimedOutException - If the operation times out more than failCount times

PeerDisconnectedException - If the remote peer disconnects

MaxLineLengthExceededException - If the maximum line length is exceeded

NotConnectedException - If not connected

readLineWait

public java.lang.String readLineWait()
                              throws IndyIOException,
                                     ReadTimedOutException,
                                     PeerDisconnectedException,
                                     MaxLineLengthExceededException,
                                     NotConnectedException

DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

IndyIOException - DOCUMENT ME!

ReadTimedOutException - DOCUMENT ME!

PeerDisconnectedException - DOCUMENT ME!

MaxLineLengthExceededException - DOCUMENT ME!

NotConnectedException - DOCUMENT ME!

readLine

public java.lang.String readLine()
                          throws PeerDisconnectedException,
                                 ReadTimedOutException,
                                 IndyIOException,
                                 MaxLineLengthExceededException,
                                 NotConnectedException

Reads a line of text from the connection. This wraps IOHandler.readLine()/

Returns:

A line of text from the connection

Throws:

PeerDisconnectedException - If the remote peer disconnects

ReadTimedOutException - If the read operation times out

IndyIOException - If an IO error occurs

MaxLineLengthExceededException - If the maximum line length is exceeded

NotConnectedException - If not connected

readLine

public java.lang.String readLine(int timeout,
                                 int maxLineLength)
                          throws IndyIOException,
                                 ReadTimedOutException,
                                 PeerDisconnectedException,
                                 NotConnectedException,
                                 MaxLineLengthExceededException

Reads a line of text from the connection. This wraps IOHandler.readLine(int,int)

Parameters:

timeout - The timeout to allow for this read operation

maxLineLength - The maximum line lentgh to accept

Returns:

A line of text from this connection

Throws:

IndyIOException - If an IO error occurs

ReadTimedOutException - If the operation times out

PeerDisconnectedException - If the remote peer disonnects

MaxLineLengthExceededException - If the maximum line length is exceeded

NotConnectedException - If not connected

readBuffer

public final int readBuffer(byte[] b,
                            int len)
                     throws PeerDisconnectedException,
                            ReadTimedOutException,
                            IndyIOException,
                            NotConnectedException

Fills a buffer, b, with up to len bytes of data from the connection.

Parameters:

b - The buffer to fill

len - The amount of data to read

Returns:

The actual amount of data read

Throws:

PeerDisconnectedException - If the remote peer disconnects

ReadTimedOutException - If the read operation times out

IndyIOException - If an IOError occurs

NotConnectedException - if not connected

readInt

public final int readInt()
                  throws PeerDisconnectedException,
                         ReadTimedOutException,
                         IndyIOException,
                         NotConnectedException

Reads an int from this connection.

Returns:

An int

Throws:

PeerDisconnectedException - If the remote peer disconnects

ReadTimedOutException - If the read operation timed out

IndyIOException - If an IO error occurs.

NotConnectedException - If not connected

readLong

public final long readLong()
                    throws PeerDisconnectedException,
                           ReadTimedOutException,
                           IndyIOException,
                           NotConnectedException

Reads a long from the connection

Returns:

A long from the connection

Throws:

PeerDisconnectedException - If the remote peer disconnects

ReadTimedOutException - If the read operation times out

NotConnectedException - If not connected

IndyIOException - If an IO error occurs

readChar

public final char readChar()
                    throws PeerDisconnectedException,
                           ReadTimedOutException,
                           IndyIOException,
                           NotConnectedException

Read a char from the connection

Returns:

A char from the connection

Throws:

PeerDisconnectedException - If the remote peer disconnects

ReadTimedOutException - If the read operation times out

NotConnectedException - If not connected

IndyIOException - If an IO error occurs

readShort

public final short readShort()
                      throws PeerDisconnectedException,
                             ReadTimedOutException,
                             IndyIOException,
                             NotConnectedException

Reads a short from the connection

Returns:

A short from the connection

Throws:

PeerDisconnectedException - If the remote peer disconnects

ReadTimedOutException - If the read operation times out

NotConnectedException - If not connected

IndyIOException - If an IO error occurs

readStream

public final java.io.InputStream readStream(int byteCount,
                                            boolean readUntilDisconnect)
                                     throws PeerDisconnectedException,
                                            ReadTimedOutException,
                                            NotConnectedException,
                                            IndyIOException

Reads bytes from the socket and returns them in an InputStream. If readUntilDisconnect is true, then the method will block and return only when the connection has closed (or if an exception is thrown). If readUntilDisconnect is false, then byteCount bytes will be read. If readUntilDisconnect is false and byteCount = -1 then the first 4 bytes read from the socket will be assumed to be an integer representing the stream size, and this number of bytes will be read.

Parameters:

byteCount - The number of bytes to read

readUntilDisconnect - Whether byteCount should be ignored and the read operation should contniue until disconnected

Returns:

An InputStream containing bytes from the connection.

Throws:

PeerDisconnectedException - If the remote peer disconnects

ReadTimedOutException - If the read operation times out

NotConnectedException - If not connected

IndyIOException - If an IO error occurs

writeRFCStrings

public final void writeRFCStrings(StringList strings)
                           throws IndyIOException

Write the contents of a StringList instance to this connection. This method ensures that individual lines in strings beginning with the response termination character '.' are converted to '..', and call WriteLn using the updated values. When all lines have been written, WriteRFCStrings calls WriteLn to send the '.' termination character to indicate the end of RFC response messages

Parameters:

strings - A StringList to write

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeRFCReply

public final void writeRFCReply(RFCReply reply)
                         throws IndyIOException

Write an RFCReply to this connection.

Parameters:

reply - The RFCReply to write

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

write

public final void write(java.lang.String s)
                 throws IndyIOException,
                        NotConnectedException

Write a String to this connection.

Parameters:

s - The String to write

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeBuffer

public final void writeBuffer(byte[] buf)
                       throws IndyIOException,
                              NotConnectedException

Write a buffer of bytes to this connection.

Parameters:

buf - The bytes to write

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeLine

public final void writeLine(java.lang.String line)
                     throws IndyIOException

Write a line of text to the connection.

Parameters:

line - The text to write as a line

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeHeader

public final void writeHeader(StringList header)
                       throws IndyIOException

Write the contents of a StringList as an RFC header, translating strings of the form

name=value

to

name:value

Parameters:

header - The StringList to write as a header

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeInt

public final void writeInt(int value)
                    throws IndyIOException

Parameters:

value - The int to write

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeLong

public final void writeLong(long value)
                     throws IndyIOException

Write a long to the connection

Parameters:

value - The long to write

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeShort

public final void writeShort(short value)
                      throws IndyIOException

Write a short to the connection

Parameters:

value - The short to write

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeStrings

public final void writeStrings(StringList strings,
                               boolean writeLineCount)
                        throws IndyIOException

Write a the contents of a StringList instance to the connection as individual lines.

Parameters:

strings - The StringList to write

writeLineCount - Whether to prepend the text with a int representing the number of lines

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeStream

public final void writeStream(java.io.InputStream stream,
                              int len,
                              boolean writeByteCount)
                       throws IndyIOException

Writes the contents of an InputStream to the connection

Parameters:

stream - The InputStream to write

len - The number of bytes to write

writeByteCount - Whether the bytes should be prepended with an int representing the byte count

Throws:

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

writeFile

public final void writeFile(java.io.File f)
                     throws java.io.FileNotFoundException,
                            IndyIOException

Writes a File object to the stream

Parameters:

f - The File to write

Throws:

java.io.FileNotFoundException - If the File doesn't exist

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

currentReadBuffer

public final byte[] currentReadBuffer()
                               throws PeerDisconnectedException,
                                      IndyIOException

Returns the current data that can be read without blocking. This wraps IOHandler.currentReadBuffer()

Returns:

The data from the read buffer

Throws:

PeerDisconnectedException - If the remote peer has disconnected

ReadTimedOutException - If the read operation times out

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

readTillDisconnect

protected byte[] readTillDisconnect()
                             throws PeerDisconnectedException,
                                    ReadTimedOutException,
                                    IndyIOException

DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

PeerDisconnectedException - DOCUMENT ME!

ReadTimedOutException - DOCUMENT ME!

IndyIOException - DOCUMENT ME!

allData

public java.lang.String allData()
                         throws ReadTimedOutException,
                                IndyIOException,
                                NotConnectedException

Reads all data from the connection until disconnection occurs, and returns it as a String using the platform character encoding. This is equivalent to allData(null).

Returns:

A string representing all read data from the connection

Throws:

ReadTimedOutException - If the read operation times out

IndyIOException - If an IO error occurs

NotConnectedException - If not connected

See Also:

allData(String)

allData

public java.lang.String allData(java.lang.String encoding)
                         throws IndyIOException,
                                ReadTimedOutException,
                                NotConnectedException

Reads all data from the connection until disconnection occurs, and returns it as a String using the character encoding specified by encoding, or the platform default if encoding is null.

Parameters:

encoding - The character encoding to use

Returns:

A string representing all read data from the connection

Throws:

IndyIOException - If an IO error occurs

ReadTimedOutException - If the read operation times out

NotConnectedException - If not connected