com.ibm.etill.framework.io
Class TypicalClientSocket

java.lang.Object
  |
  +--java.net.Socket
        |
        +--com.ibm.etill.framework.io.ClientSocket
              |
              +--com.ibm.etill.framework.io.TypicalClientSocket

public class TypicalClientSocket
extends ClientSocket

This is a convenience class. It exists for the following reason: When a TCP connection is closed gracefully by the other end, a FIN is sent to this end's TCP stack causing an end-of-stream condition when all data has been read. Most applications, when the other end closes its connection gracefully, wish to recognize this as soon as possible and not be allowed to write data to the socket anymore. This socket, when read from, throws IOExceptions when it gets an end-of-stream instead of returning -1. It also remembers if an IOException was thrown, so that later writes to the socket to fail. This is the scenario that, I believe, most programmers wish to see happen when writing most applications ... and is especially useful when multiple threads use the same socket and would like writes to fail as soon as reads have failed (because end-of-stream was received) on another thread.

Since:
2.2
Author:
dj

Field Summary
static int READBYTE_NO_DATA
          No data is available from socket, but the socket is still up
 
Constructor Summary
TypicalClientSocket(Socket s)
          Class constructor that takes an existing socket.
TypicalClientSocket(TcpipHost targetHost)
          Class constructor taking a TcpipHost.
TypicalClientSocket(TcpipHost targetHost, TcpipHost socksHost)
          Class constructor taking a TcpipHost as the target and a TcpipHost socks server.
 
Method Summary
 int available()
          returns total number of bytes ready to be read from the socket.
 void checkForJavaMemoryLeakOnRead()
          Continually reads from the socket unless an IOException occurs This function is used for testing for a memory leak "caused" by reading from the socket.
 void close()
          closes the socket.
 void flush()
          flushes data to the socket.
 InetAddress getInetAddress()
          Gets the socket's InetAddress.
 InputStream getInputStream()
          Gets the socket's InputStream.
 InetAddress getLocalAddress()
          Gets the socket's local InetAddress.
 int getLocalPort()
          Gets the socket's local port number.
 OutputStream getOutputStream()
          Gets the socket's OutputStream.
 int getPort()
          Gets the socket's port number.
 int getSoLinger()
          Returns setting for SO_LINGER.
 int getSoTimeout()
          Gets the setting for the socket timeout.
 boolean getTcpNoDelay()
          Tests if TCP_NODELAY is enabled.
 boolean isDown()
           
 boolean isUp()
          returns whether the socket is up or down.
static void main(String[] args)
           
 void notifyIfSocketIsDown(SocketDownInterface n)
          Accepts an Object implementing the SocketDownInterface to be notified when the socket interface goes down.
 int read(byte[] ba, int offset, int maxLengthToRead)
          Gets a set of bytes.
 int readByte()
          gets a byte from the socket
 int readByteNoBlocking()
          gets a byte from the socket without blocking the current thread when no data is present.
 void setSoLinger(boolean on, int val)
          Enable/disable SO_LINGER with the specified linger time in seconds.
 void setSoTimeout(int timeout)
          Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds.
 void setTcpNoDelay(boolean on)
          Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm).
 String toString()
          Gets the socket in the form of a string.
 void write(byte thebyte)
          writes a byte to the socket.
 void write(byte[] bytes)
          writes a set of bytes to the socket.
 
Methods inherited from class java.net.Socket
getKeepAlive, getReceiveBufferSize, getSendBufferSize, setKeepAlive, setReceiveBufferSize, setSendBufferSize, setSocketImplFactory, shutdownInput, shutdownOutput
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

READBYTE_NO_DATA

public static final int READBYTE_NO_DATA
No data is available from socket, but the socket is still up
Constructor Detail

TypicalClientSocket

public TypicalClientSocket(TcpipHost targetHost)
                    throws IOException
Class constructor taking a TcpipHost.
Parameters:
targetHost - the host and port to connect to
Throws:
IOException - if an InputStream or an OutputStream can not be obtained from the socket.

TypicalClientSocket

public TypicalClientSocket(TcpipHost targetHost,
                           TcpipHost socksHost)
                    throws IOException
Class constructor taking a TcpipHost as the target and a TcpipHost socks server.
Parameters:
targetHost - the host and port to connect to
socksHost - the socks server and port to connect to.
Throws:
IOException - if an InputStream or an OutputStream can not be obtained from the socket.

TypicalClientSocket

public TypicalClientSocket(Socket s)
                    throws IOException
Class constructor that takes an existing socket. This is useful when a Socket object is created from a serversocket.accept() call. DO NOT use the InputStream and OutputStream objects *from the socket* you gave on this constructor. You must use the input/output streams gotten from calling getInputStream() and getOutputStream() in this class.
Parameters:
s - an existing socket
Throws:
IOException - if an InputStream or an OutputStream can not be obtained from the socket.
Method Detail

notifyIfSocketIsDown

public void notifyIfSocketIsDown(SocketDownInterface n)
Accepts an Object implementing the SocketDownInterface to be notified when the socket interface goes down.
Parameters:
n - an object that implements the SocketDownInterface will be notified if the socket interface goes down.

isUp

public boolean isUp()
returns whether the socket is up or down.
Returns:
true if the socket is still up or false if the socket is down.

isDown

public boolean isDown()

readByte

public int readByte()
             throws IOException
gets a byte from the socket
Returns:
a byte from the socket or READBYTE_NO_DATA if no data is available to be read from the socket. if data is available to read from the socket, a value from 0 to 255 will be returned.
Throws:
IOException - if the other side closed its connection

checkForJavaMemoryLeakOnRead

public void checkForJavaMemoryLeakOnRead()
                                  throws IOException
Continually reads from the socket unless an IOException occurs This function is used for testing for a memory leak "caused" by reading from the socket.
Throws:
IOException - if the socket closed (throws an IOException). Note that the the socket is down using noteThatSocketIsDown.

readByteNoBlocking

public int readByteNoBlocking()
                       throws IOException
gets a byte from the socket without blocking the current thread when no data is present.
Returns:
a byte from the socket or READBYTE_NO_DATA if no data is available to be read from the socket. if data is available to read from the socket, a value from 0 to 255 will be returned.
Throws:
IOException - if the socket is already down or if readByte() throws one.

read

public int read(byte[] ba,
                int offset,
                int maxLengthToRead)
         throws IOException
Gets a set of bytes. The set of bytes is placed into the specified byte array starting at the specified offset. If the socket closed while reading the bytes, the socket will be noted as being down. @see java.io#InputStream(byte[], int, int)
Parameters:
ba - where the set of bytes will be placed.
offset - offset in ba where the set of bytes will be placed.
maxLengthToRead - the number of bytes to read.
Returns:
@see the java.io#InputStream(byte[], int, int) the number of bytes actually read or the socket, a value from 0 to 255 will be returned.
Throws:
IOException - if the socket is already down or the socket goes down while the set of bytes is being loaded into ba..

available

public int available()
              throws IOException
returns total number of bytes ready to be read from the socket. If an IOException occurs while attempting to determine the number of bytes, the fact that the socket is down will be remembered.
Returns:
the number of bytes ready to be read from the socket
Throws:
IOException - if the socket is already down or an exception occurs attempting to determine how many bytes the socket has ready to read.

write

public void write(byte[] bytes)
           throws IOException
writes a set of bytes to the socket. If an IOException occurs while attempting to write the bytes, the fact that the socket is down will be remembered.
Parameters:
bytes - an array of bytes to write to the socket
Throws:
IOException - if the socket is already down or an exception occurs attempting to determine how many bytes the socket has ready to read.

write

public void write(byte thebyte)
           throws IOException
writes a byte to the socket. If an IOException occurs while attempting to write the byte, the fact that the socket is down will be remembered.
Parameters:
thebyte - the byte to write to the socket
Throws:
IOException - if the socket is already down or an exception occurs attempting to determine how many bytes the socket has ready to read.

flush

public void flush()
           throws IOException
flushes data to the socket. If an IOException occurs while attempting flush the data to the socket, the fact that the socket is down will be remembered.
Throws:
IOException - if the socket is already down or an exception occurs attempting to flush the data to the socket.

close

public void close()
closes the socket. the data pending for the socket will be flushed before the socket is closed the InputStream and the OutputStream will be closed.

The socket will be noted as being down.

Overrides:
close in class Socket

getInputStream

public InputStream getInputStream()
Gets the socket's InputStream.
Overrides:
getInputStream in class Socket
Returns:
the socket's InputStream

getOutputStream

public OutputStream getOutputStream()
Gets the socket's OutputStream.
Overrides:
getOutputStream in class Socket
Returns:
the socket's OutputStream

getInetAddress

public InetAddress getInetAddress()
Gets the socket's InetAddress.
Overrides:
getInetAddress in class Socket
Returns:
the InetAddress(IP Address) for the socket.

getLocalAddress

public InetAddress getLocalAddress()
Gets the socket's local InetAddress.
Overrides:
getLocalAddress in class Socket
Returns:
the local InetAddress(IP Address) for the socket.

getLocalPort

public int getLocalPort()
Gets the socket's local port number.
Overrides:
getLocalPort in class Socket
Returns:
the port number or the socket's local port.

getPort

public int getPort()
Gets the socket's port number.
Overrides:
getPort in class Socket
Returns:
the socket's port number

setTcpNoDelay

public void setTcpNoDelay(boolean on)
                   throws SocketException
Enable/disable TCP_NODELAY (disable/enable Nagle's algorithm).
Overrides:
setTcpNoDelay in class Socket
Parameters:
on - true=enable Nagle's algorithm
Throws:
SocketException - if the socket TCP_NODELAY can not be set.

getTcpNoDelay

public boolean getTcpNoDelay()
                      throws SocketException
Tests if TCP_NODELAY is enabled.
Overrides:
getTcpNoDelay in class Socket
Returns:
true if TCP_NODELAY is enabled.

setSoLinger

public void setSoLinger(boolean on,
                        int val)
                 throws SocketException
Enable/disable SO_LINGER with the specified linger time in seconds. If the specified timeout value exceeds 65,535 it will be reduced to 65,535.
Overrides:
setSoLinger in class Socket
Parameters:
on - true indicates the socket should linger on.
val - the linger time in seconds.

getSoLinger

public int getSoLinger()
                throws SocketException
Returns setting for SO_LINGER. -1 implies that the option is disabled.
Overrides:
getSoLinger in class Socket
Returns:
the linger timeout in seconds or -1 if the linger option is disabled.
Throws:
SocketException - if the linger setting can not be obtained.

setSoTimeout

public void setSoTimeout(int timeout)
                  throws SocketException
Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. With this option set to a non-zero timeout, a read() call on the InputStream associated with this Socket will block for only this amount of time. If the timeout expires, a java.io.InterruptedIOException is raised, though the Socket is still valid. The option must be enabled prior to entering the blocking operation to have effect. The timeout must be greater than 0. A timeout of zero is interpreted as an infinite timeout.
Overrides:
setSoTimeout in class Socket
Parameters:
timeout - the socket timeout value in milliseconds.
Throws:
SocketException - if the socket timeout can not be set.

getSoTimeout

public int getSoTimeout()
                 throws SocketException
Gets the setting for the socket timeout. 0 implies that the socket timeout option is disabled.
Overrides:
getSoTimeout in class Socket
Throws:
SocketException - if the socket timeout can not be obtained.

toString

public String toString()
Gets the socket in the form of a string.
Overrides:
toString in class Socket
Returns:
the socket in the form of a string

main

public static void main(String[] args)
                 throws Exception