com.ccg.net.tcp
Class SocketOptions

java.lang.Object
  com.ccg.net.tcp.SocketOptions

public class SocketOptions
extends Object

A handy "bean" type wrapper around the standard Socket options.

This object provides a wrapper around the various Socket options which one can control. It is particularily handy if you want to copy socket options from one Socket to another, load options from a standard TagLookup table, format the current options as a String, or apply the current settings to an open Socket.

This class is used by Server to allow one to specify a set of socket options to be applied for incoming connections.

It should be noted that JDK 1.3 added the Socket.setKeepAlive(boolean) option - this class doesn't support this as of yet, but will once we move to a JDK 1.3 environment.

Since:

1.0

Version:

$Revision: 1.5 $

Author:

$Author: pkb $

See Also:

Server

Field Summary

static int

DISABLE_SO_LINGER Used as a parameter to setSoLinger(int) to disable SO_LINGER.

Constructor Summary

SocketOptions()

Method Summary

Exception	apply(ServerSocket s) Apply the settings to an open ServerSocket connection.
SocketException	apply(Socket s) Apply the settings to an open Socket connection.
Socket	createClientSocket() Create a client socket object based upon the current settings in the bean.
Socket	createSocket(TagLookup tl, String dhost, int dport) Fully construct and initialize a TCP socket based on a set of properties.
static InetAddress	getInetAddress(String s) Helper method to convert string to internet address.
InetAddress	getLocalHost() Get the local host to connect to if creating a client socket.
int	getLocalPort() Get the port number to connect to when making a local connection.
void	getProperties(Properties props, String tag) Set the value of the object from values specified in a TagLookup table.
int	getReceiveBufferSize() Get the transmit buffer size (in bytes).
InetAddress	getRemoteHost() Get the remote host to connect to if creating a client socket.
int	getRemotePort() Get the port number to connect to when making a remote connection.
int	getSendBufferSize() Get the transmit buffer size (in bytes).
int	getSoLinger() Get the linger time (in seconds).
int	getSoTimeout() Get the timeout value for the connection (in seconds).
boolean	isTcpNoDelay() Is whether TCP_NO_DELAY is enabled set?
void	setLocalHost(InetAddress val) Set the local host to connect to if creating a client socket.
void	setLocalPort(int val) Set the port number to connect to when making a local connection.
Exception	setProperties(TagLookup tl) Set the value of the object from values specified in a TagLookup table.
void	setReceiveBufferSize(int val) Set the transmit buffer size (in bytes).
void	setRemoteHost(InetAddress val) Set the remote host to connect to if creating a client socket.
void	setRemotePort(int val) Set the port number to connect to when making a remote connection.
void	setSendBufferSize(int val) Set the transmit buffer size (in bytes).
void	setSoLinger(int val) Set the linger time (in seconds).
void	setSoTimeout(int val) Set the timeout value for the connection (in milliseconds).
void	setTcpNoDelay(boolean val) Set whether TCP_NO_DELAY is enabled.
Exception	setValues(Socket s) Fetch the TCP settings from an open Socket.
String	toString() Get String representation of the object.

Methods inherited from class java.lang.Object

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

Field Detail

DISABLE_SO_LINGER

public static final int DISABLE_SO_LINGER

Used as a parameter to setSoLinger(int) to disable SO_LINGER.

Since:

1.0

See Also:

setSoLinger(int), Constant Field Values

Constructor Detail

SocketOptions

public SocketOptions()

Method Detail

createSocket

public Socket createSocket(TagLookup tl,
                           String dhost,
                           int dport)
                    throws ParseException,
                           IOException,
                           UnknownHostException

Fully construct and initialize a TCP socket based on a set of properties.

This method does just about everything for you when you need to create a TCP client socket from a set of properties. It does the following:

• Sets the properties of the object based upon the properties you pass.
• Constructs a new Socket object using host/port information from the properties passed (or your default values).
• Applies the TCP connection properties to the newly created Socket object.
• Finally returns the newly created Socket object to you.

Many error conditions could be encountered along the way. If an error is encountered, a exception is thrown. If no exception is thrown, then you will receive a fully configured socket (null is never returned).

You should refer to the setProperties method for all of the standard socket options which are recognized. In addition to the standard options, this method also recognizes (and sometimes requires) the following:

host=HOST

This property specifies the remote host which we are to connect to. This property must be specified if the default host value (the 'dhost' parameter) is null.

port=INT

This property specifies the port number on the remote host which we are to connect to. This property must be specified if the default port value (the 'dport' parameter) is not a positive number.

host.local=HOST

This property specifies the local host which we will bind to. This property is not required and is seldom specified. You might need to specify this value if you have a system which has more than one network connection.

port.local=INT

This property specifies the port number to use on the local host side of the connection (the port we bind to). This property is not required and is seldom specified. You might need to specify this value if the server you are connecting to only accepts connections coming from a specific port number (this is rare).

Parameters:

tl - The properties to lookup the configuration information for the connection.

dhost - Default remote host name to use (may be null if you want to require that the host be specified in the properties passed).

dport - Default remote port to connect to (set to -1 if you want to require that the "port" value be specified in the properties passed).

Returns:

A Socket which is fully configured and initialized.

Throws:

ParseException - If there was a problem parsing any of the values from the properties.

UnknownHostException - If the host specified was not known (failed to lookup).

IOException - One of the many I/O errors that can occur when creating a socket connection.

Since:

1.0

createClientSocket

public Socket createClientSocket()
                          throws IllegalStateException,
                                 IOException

Create a client socket object based upon the current settings in the bean.

This method attempts to create a Socket based upon the current settings in the object. At a minimum, both the remote host and remote port must be set to valid values.

Returns:

A Socket which is fully configured and initialized and ready to use.

Throws:

IllegalStateException - If the remote host or remote port have not been set.

IOException - This is typically a SocketException indicating there is a problem establishing the socket.

Since:

1.0

toString

public String toString()

Get String representation of the object. This method returns the string representation of the values which have been explicitly set. This means that if none of the values have been set, you get back a zero length string (""). Otherwise, you'll get a string which looks like: "sendBufferSize=30000,receiveBufferSize=10000", the names of the values which will show up are the same recognized by setProperties(TagLookup).

Overrides:

toString in class Object

Returns:

String representation of the values explicitly known.

Since:

1.0

See Also:

setProperties(TagLookup)

setProperties

public Exception setProperties(TagLookup tl)

Set the value of the object from values specified in a TagLookup table. This is a very flexible method to set the values contained in this object based upon the values retrieved from the passed TagLookup table (which can originate from about any source - command line, applet parameters, property files, etc). All values are optional - if not specified in the property file, then this object won't update its current settings for the omitted fields (this is important to understand when the values are applied). The following properties are recognized:

receiveBufferSize=SIZE

You can specify the size (in bytes) for the receive buffer.

sendBufferSize=SIZE

You can specify the size (in bytes) for the send buffer.

soLinger=SECS

You can specify the time (in seconds) the connection should be allowed to "linger" when its shutdown. Pass a negative TIME to disable.

soTimeout=MILLIS

You can specify the time (in milliseconds) that the connection should wait for a read() to complete. The value should be 0 or higher where 0 is the default state which results in FULL blocking I/O.

tcpNoDelay=true|false

You can specify whether the "no delay" option should be applied to the connection.

Parameters:

tl - The TagLookup table to fetch properties for.

Since:

1.0

See Also:

apply(java.net.Socket)

getProperties

public void getProperties(Properties props,
                          String tag)

Set the value of the object from values specified in a TagLookup table. This is a very flexible method to set the values contained in this object based upon the values retrieved from the passed TagLookup table (which can originate from about any source - command line, applet parameters, property files, etc). All values are optional - if not specified in the property file, then this object won't update its current settings for the omitted fields (this is important to understand when the values are applied). The following properties are recognized:

receiveBufferSize=SIZE

You can specify the size (in bytes) for the receive buffer.

sendBufferSize=SIZE

You can specify the size (in bytes) for the send buffer.

soLinger=SECS

You can specify the time (in seconds) the connection should be allowed to "linger" when its shutdown. Pass a negative TIME to disable.

soTimeout=MILLIS

You can specify the time (in milliseconds) that the connection should wait for a read() to complete. The value should be 0 or higher where 0 is the default state which results in FULL blocking I/O.

tcpNoDelay=true|false

You can specify whether the "no delay" option should be applied to the connection.

Parameters:

tl - The TagLookup table to fetch properties for.

Since:

1.0

See Also:

apply(java.net.Socket)

setValues

public Exception setValues(Socket s)

Fetch the TCP settings from an open Socket. This method is useful if you want to fetch the socket options from an already open socket. This can be useful to do the following:

• Get a string representation of the socket options.
• Apply the settings of one Socket to another.
• To see what your system's default settings are.
• To see the remote host and remote port settings associated with the socket.
• To see the local host and local port settings associated with the socket.

Parameters:

s - The Socket which you want to fetch the settings from.

Returns:

null if values were successfully transfered, otherwise Exception which occurred while we tried to set them.

Since:

1.0

See Also:

setProperties(TagLookup)

apply

public SocketException apply(Socket s)

Apply the settings to an open Socket connection. This method will apply all of the settings, which have been explicitly set, to the Socket passed to the method. For example, if the setSendBufferSize(int) method had been previously invoked, then the size specified would be applied to the Socket. Refer to the various "set" methods to see how one can go about setting the options.

Parameters:

s - Socket to apply the current settings to.

Returns:

null if values were successfully applied, otherwise Exception which occurred.

Since:

1.0

See Also:

setValues(Socket)

apply

public Exception apply(ServerSocket s)

Apply the settings to an open ServerSocket connection. This method will apply all of the settings, which have been explicitly set, to the ServerSocket passed to the method. Currently, the only setting which can be applied to a ServerSocket are is the SO_TIMEOUT option.

Parameters:

s - ServerSocket to apply the current settings to.

Returns:

null if values were successfully applied, otherwise Exception which occurred.

Since:

1.0

See Also:

apply(Socket)

setTcpNoDelay

public void setTcpNoDelay(boolean val)

Set whether TCP_NO_DELAY is enabled.

Parameters:

val - New boolean value to assign. see #getTcpNoDelay

isTcpNoDelay

public boolean isTcpNoDelay()

Is whether TCP_NO_DELAY is enabled set?

Returns:

Current boolean value assigned. see #setTcpNoDelay

setSoLinger

public void setSoLinger(int val)

Set the linger time (in seconds).

Parameters:

val - New int value to assign (in seconds). Pass DISABLE_SO_LINGER value to disable.

See Also:

getSoLinger()

getSoLinger

public int getSoLinger()

Get the linger time (in seconds).

Returns:

Current value (in seconds) - will return DISABLE_SO_LINGER if disabled.

See Also:

setSoLinger(int)

setSoTimeout

public void setSoTimeout(int val)

Set the timeout value for the connection (in milliseconds).

Parameters:

val - Maximum number of milliseconds to wait on a read. Pass 0 to block forever. Use -1 to disable (which means we don't adjust whatever the system gives us).

See Also:

getSoTimeout()

getSoTimeout

public int getSoTimeout()

Get the timeout value for the connection (in seconds).

Returns:

Current int value assigned (or -1 if not specified).

See Also:

setSoTimeout(int)

setSendBufferSize

public void setSendBufferSize(int val)

Set the transmit buffer size (in bytes).

Parameters:

val - New receive buffer size (in bytes). Set to 0 to clear setting and go back to sytem defaults.

See Also:

getSendBufferSize()

getSendBufferSize

public int getSendBufferSize()

Get the transmit buffer size (in bytes).

Returns:

Current int value assigned (returns 0 if using system default).

See Also:

setSendBufferSize(int)

setReceiveBufferSize

public void setReceiveBufferSize(int val)

Set the transmit buffer size (in bytes).

Parameters:

val - New receive buffer size (in bytes). Set to 0 to clear setting and go back to sytem defaults.

See Also:

getReceiveBufferSize()

getReceiveBufferSize

public int getReceiveBufferSize()

Get the transmit buffer size (in bytes).

Returns:

Current int value assigned (returns 0 if not set).

See Also:

setReceiveBufferSize(int)

setRemoteHost

public void setRemoteHost(InetAddress val)

Set the remote host to connect to if creating a client socket.

Parameters:

val - New InetAddress value to assign, or null to clear.

See Also:

getRemoteHost()

getRemoteHost

public InetAddress getRemoteHost()

Get the remote host to connect to if creating a client socket.

Returns:

The InetAddress associated with the remote end of the connection - or null if not specified.

See Also:

setRemoteHost(java.net.InetAddress)

setRemotePort

public void setRemotePort(int val)

Set the port number to connect to when making a remote connection.

Parameters:

val - New int value to assign - set to 0 or less to clear.

See Also:

getRemotePort()

getRemotePort

public int getRemotePort()

Get the port number to connect to when making a remote connection.

Returns:

Current int value assigned, returns 0 if not yet specified.

See Also:

setRemotePort(int)

setLocalHost

public void setLocalHost(InetAddress val)

Set the local host to connect to if creating a client socket.

Typically one never bothers to set this. If your system has multiple IP addresses, it allows one to specify which IP address you want your local side of the connection to be bound to.

Parameters:

val - New InetAddress value to assign, or null to clear.

See Also:

getLocalHost()

getLocalHost

public InetAddress getLocalHost()

Get the local host to connect to if creating a client socket.

Returns:

The InetAddress associated with the local end of the connection - or null if not specified.

See Also:

setLocalHost(java.net.InetAddress)

setLocalPort

public void setLocalPort(int val)

Set the port number to connect to when making a local connection.

Parameters:

val - New int value to assign - set to 0 or less to clear.

See Also:

getLocalPort()

getLocalPort

public int getLocalPort()

Get the port number to connect to when making a local connection.

Returns:

Current int value assigned, returns 0 if not yet specified.

See Also:

setLocalPort(int)

getInetAddress

public static InetAddress getInetAddress(String s)
                                  throws UnknownHostException

Helper method to convert string to internet address.

Unfortunately, it can be difficult to transform a string value into a Internet address (and vice versa). In one case, one can always use the absolute address (like: 127.0.0.1), but this is not very nice and doesn't help when servers have their addresses changed. One can also use the fully qualified domain name (like: my.yahoo.com), however, this has a problem if the name can't be resolved.

This method attempts to solve the problem by allowing one to specify a "slash" separated list of names to try and resolve. For example, you could pass "localhost/127.0.0.1" and we would first try to use "localhost" if that failed, we would try "127.0.0.1".

Parameters:

s - String to convert to a internet address (must not be null)

Returns:

Internet address associated with string - never returns null.

Throws:

UnknownHostException - If unable to resolve string to a internet address.

Since:

1.0