com.ccg.net.tcp
Class URLConnection

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

public class URLConnection
extends URLConnection

Implementation of a URLConnection for TCP connections.

This is a implementation of a "java.protocol.handler.pkgs" object which will add a "tcp:" type to the type of URL objects that the JVM recognizes. This allows one to open up input and output streams on a TCP connection in a manner similar to how one would go about doing it for a "http:" type of URL.

This class is used to handle both the creation of connections (connecting to another machine via TCP), and the acceptance of connections (waiting for another machine to connect to this machine). However, this is a point to point type of connection. If you want to create a standard TCP server that can handle many clients at once, you will want to look at the Server class instead of this one.

The form of the URL which this class adds support for looks like the following:

 tcp://[HOST]:PORT/[OPTIONS]
 

tcp://

This indicates that you want to specify a "straight" TCP connection between two machines.

HOST

If this option is specified, then you are indicating that you want to connect to a remote machine.

:PORT/

This option MUST be specified. If the HOST parameter is included as well, it indicates the TCP port which on the HOST you wish to connect to (a connection will be made to the HOST:PORT specified). If the HOST parameter is omitted, it indicates the PORT on the local machine which you want to accept the next incoming TCP connection from another machine (another process connecting to yours).

OPTIONS

There are many options which you can specify. These configure how the TCP connection is setup. If you don't specify any, you will get the default settings for the JVM. The options specified should be of the form: "KEY=VALUE,KEY=VALUE,...". Unrecognized key/value pairs are ignored (in case some other process might allow other settings). All of the options recognized by SocketOptions.setProperties(com.ccg.util.TagLookup) are allowed. I've tried to list them below, but you should check with that class as well in case they change over time (JDK 1.3 is going to support the TCP keep alive option).

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.

You might want to take a look at the Cat class for more information on how one uses this type of URL (the source code would be handy for developers), but here are some quick examples:

 "tcp://:20080/"
 "tcp://www.yahoo.com:80/sendBufferSize=5000,soLinger=3,tcpNoDelay=true"
 

To make this class available to ALL Java code which opens up URL's, you will need to add the com.ccg.net package to the list of valid protocol handlers. You should be able to configure the JVM to support this, or add it as a definition when you start Java (I know its possible, but I've forgotten how to do it at the moment). If you'd rather just enable it directly in your code, you can add the following statements to add the com.ccg.net based protocol handlers to the JVM's search path:

 Class.forName("com.ccg.net.tcp.URLConnection");
 

To enable it from the command line, you can use "-Djava.protocol.handler.pkgs=com.ccg.net" to the JVM invocation to add it to the System properties (it may even be possible to locate your JVM's system property configuration file and add it there by hand). This has the advantage of making the protocol available to ALL Java code as a standard URL handler. This is demonstrated with the following command line invocation:

 java -Djava.protocol.handler.pkgs=com.ccg.net com.ccg.app.convert.HexDump \
 -in tcp://localhost:23/soTimeout=5000
 

Since:

1.0

Version:

$Revision: 1.3 $

Author:

$Author: pkb $

See Also:

URLConnection, Cat

Field Summary

Fields inherited from class java.net.URLConnection

allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, url, useCaches

Constructor Summary

URLConnection(URL url)
Initializes object with a standard URL This method is used to initialize the connection, however, no attempt will be made for a connection until the connect(java.net.URL, com.ccg.net.tcp.SocketOptions), getInputStream(), or getOutputStream() methods are invoked.

Method Summary

void	connect() Create the connection to the specified URL.
static Socket	connect(URL url, SocketOptions so) Static method to open up a TCP connection.
InputStream	getInputStream() Get the InputStream to read data from the remote end.
OutputStream	getOutputStream() Get the OutputStream to send data to the remote end.
Socket	getSocket() Access the Socket which is established after connect(java.net.URL, com.ccg.net.tcp.SocketOptions) Typially one will just use the getInputStream() or getOutputStream() methods.
SocketOptions	getSocketOptions() Get the socket options to apply to all incoming connections
void	setSocketOptions(SocketOptions val) Set the socket options to apply to all incoming connections This method allows one to specify a specific set of socket options (receive buffer size, send buffer size, etc), which should be applied to all incoming connections.

Methods inherited from class java.net.URLConnection

addRequestProperty, getAllowUserInteraction, getConnectTimeout, getContent, getContent, getContentEncoding, getContentLength, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getHeaderFields, getIfModifiedSince, getLastModified, getPermission, getReadTimeout, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setConnectTimeout, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setReadTimeout, setRequestProperty, setUseCaches, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

URLConnection

public URLConnection(URL url)

Initializes object with a standard URL This method is used to initialize the connection, however, no attempt will be made for a connection until the connect(java.net.URL, com.ccg.net.tcp.SocketOptions), getInputStream(), or getOutputStream() methods are invoked.

Parameters:

url - The URL to initialize the connection with - it must follow the form specified by the class.

Since:

1.0

See Also:

URLConnection(URL)

Method Detail

connect

public static Socket connect(URL url,
                             SocketOptions so)
                      throws IOException

Static method to open up a TCP connection. This is a static method which will attempt to open up a TCP connection as described in the class overview. It parses the fields from the passed URL, establishes a connection to the specified HOST:PORT, or waits for a connection to be made to the specified :PORT, sets any specified socket options and returns the newly formed connection.

Parameters:

url - The URL in the proper form recognized by this class - must not be null.

so - If you have any default SocketOptions which you would like to apply to the connection once its established. It should be noted, that any options found in the URL will override values found in this object. You can pass null if you just want the default values.

Returns:

Socket to the newly opened connection.

Throws:

IOException - If we were unable to setup the socket.

Since:

1.0

See Also:

connect()

connect

public void connect()
             throws IOException

Create the connection to the specified URL. This method establishes the connection specified by the URL. As explained in the class overview this may mean that we will make a TCP connection to a specific host and port, OR, we will listen on a specific port and wait for someone else to connect to us.

If this method succeeds (doesn't throw an IOException), then its safe to assume that the connection was established. This method uses the static version to actually open the connection.

Typically, one would set the socket options prior to invoking this method - but we will try to honor requests that come after the connection is already established.

Specified by:

connect in class URLConnection

Throws:

IOException - If there is a problem establishing the connection.

Since:

1.0

See Also:

getInputStream(), getOutputStream()

getSocket

public Socket getSocket()

Access the Socket which is established after connect(java.net.URL, com.ccg.net.tcp.SocketOptions) Typially one will just use the getInputStream() or getOutputStream() methods. However, if one is curious about the underlying connection, then this method can be used to retrieve the underlying Socket object. This method will return null if a connection hasn't been established yet.

Returns:

The Socket established by connect(java.net.URL, com.ccg.net.tcp.SocketOptions), or null if one hasn't been established yet.

Since:

1.0

See Also:

connect(java.net.URL, com.ccg.net.tcp.SocketOptions)

getInputStream

public InputStream getInputStream()
                           throws IOException

Get the InputStream to read data from the remote end. This method will make the connection, if necessary, and then return a InputStream object which one can use to read the data sent from the remote end of the connection.

Overrides:

getInputStream in class URLConnection

Returns:

A InputStream which you can read the raw data sent from the remote end of the connection.

Throws:

IOException - If there is a problem establishing the connection, or getting a InputStream from the Socket.

Since:

1.0

See Also:

connect(java.net.URL, com.ccg.net.tcp.SocketOptions)

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Get the OutputStream to send data to the remote end. This method will make the connection, if necessary, and then return a OutputStream object which one can use to send data to the remote end of the connection.

Overrides:

getOutputStream in class URLConnection

Returns:

A OutputStream which you can use to send data to the remote end of the connection.

Throws:

IOException - If there is a problem establishing the connection, or getting a OutputStream from the Socket.

Since:

1.0

See Also:

connect(java.net.URL, com.ccg.net.tcp.SocketOptions)

setSocketOptions

public void setSocketOptions(SocketOptions val)

Set the socket options to apply to all incoming connections This method allows one to specify a specific set of socket options (receive buffer size, send buffer size, etc), which should be applied to all incoming connections. By default, this will be null indicating that no special options should be applied.

Parameters:

val - New SocketOptions value to assign (pass null to leave connections in the system default state).

See Also:

getSocketOptions()

getSocketOptions

public SocketOptions getSocketOptions()

Get the socket options to apply to all incoming connections

Returns:

Current SocketOptions value assigned.

See Also:

setSocketOptions(com.ccg.net.tcp.SocketOptions)