org.topoweb.net
Class TcpDomProtocol

java.lang.Object
  |
  +--org.topoweb.net.TcpDomProtocol

All Implemented Interfaces:

DomProtocol

public class TcpDomProtocol

extends java.lang.Object

implements DomProtocol

A TCP/IP client implementation of a DOM protocol using a blocking socket. The underlying network protocol is based on well formed request / response XML snippets. Moreover, to keep the parsing simple, we make one crucial assumption:

The root request or response elements always end with an XML tag of the form </response> with no whitespace between the < and > characters (where response can take on any value).

Actually, this class knows nothing about the remote end, but the above protocol contract is implied at both end-points.

Implementation Note

Using the DOM is inherently inefficient. Treat this class as a quick hack to get an XML network protocol up and running. So, its probably just useful in reference implementations.

Author:

Babak Farhang

Constructor Summary

TcpDomProtocol(java.net.InetSocketAddress socketAddress, java.lang.String responseTail, javax.xml.parsers.DocumentBuilder documentBuilder)
Constructs a new instance using the given socket address and the specified response element.

TcpDomProtocol(java.net.InetSocketAddress socketAddress, java.lang.String responseTail, javax.xml.parsers.DocumentBuilder documentBuilder, boolean check)
Constructs a new instance using the given socket address and the specified response element.

Method Summary

org.w3c.dom.Element	doProtocol(org.w3c.dom.Element request) Returns the response element for the specified request.
protected java.io.OutputStream	getRequestStream(java.net.Socket sock) Returns a request (output) stream from the specified socket.
protected java.io.InputStream	getResponseStream(java.net.Socket sock) Returns a response (input) stream from the specified socket.
java.lang.String	getResponseTagName() Returns the tag name for the response element.
protected java.net.Socket	getSocket() Returns a ready socket.
java.net.InetSocketAddress	getSocketAddress() Returns the socket address for this instance.
protected void	releaseSocket(java.net.Socket sock) Releases the given socket.

Methods inherited from class java.lang.Object

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

Constructor Detail

TcpDomProtocol

public TcpDomProtocol(java.net.InetSocketAddress socketAddress,
                      java.lang.String responseTail,
                      javax.xml.parsers.DocumentBuilder documentBuilder)

Constructs a new instance using the given socket address and the specified response element. The response element is specified in form of its tail tag. It should be of the form </response> containing no whitespace.

Parameters:

socketAddress - the socket address specifying the IP and port

responseTail - the response tail tag

TcpDomProtocol

public TcpDomProtocol(java.net.InetSocketAddress socketAddress,
                      java.lang.String responseTail,
                      javax.xml.parsers.DocumentBuilder documentBuilder,
                      boolean check)

Constructs a new instance using the given socket address and the specified response element. The response element is specified in form of its tail tag. It should be of the form </response> containing no whitespace.

Parameters:

socketAddress - the socket address specifying the IP and port

responseTail - the response tail tag

check - if true, a best efforts check is made to ensure that the arguments are valid

Method Detail

getSocketAddress

public java.net.InetSocketAddress getSocketAddress()

Returns the socket address for this instance.

Returns:

the socket address

getResponseTagName

public final java.lang.String getResponseTagName()

Returns the tag name for the response element.

getSocket

protected java.net.Socket getSocket()
                             throws java.io.IOException

Returns a ready socket. The socket encapsulates the communication medium over which the doProtocol method is implemented. Invoked every time the doProtocol method is invoked. The default implementation returns a new socket constructed from the socket address specified at instantiation. We imagine a subclass might returned a cached socket.

Returns:

a ready socket

java.io.IOException

See Also:

releaseSocket(Socket)

doProtocol

public org.w3c.dom.Element doProtocol(org.w3c.dom.Element request)
                               throws DomProtocolException

Description copied from interface: DomProtocol

Returns the response element for the specified request.

Specified by:

doProtocol in interface DomProtocol

Parameters:

request - the request element

Returns:

the response element

Throws:

DomProtocolException - if an error occurs while processing the request; application-specific errors are expected to be encoded in the returned response document

getRequestStream

protected java.io.OutputStream getRequestStream(java.net.Socket sock)
                                         throws java.io.IOException

Returns a request (output) stream from the specified socket.

Returns:

a request output stream

java.io.IOException

getResponseStream

protected java.io.InputStream getResponseStream(java.net.Socket sock)
                                         throws java.io.IOException

Returns a response (input) stream from the specified socket. The default implementation uses a StreamFragmenter to detect the end of the response.

Returns:

a response input stream

java.io.IOException

releaseSocket

protected void releaseSocket(java.net.Socket sock)

Releases the given socket. The default implementation just closes it. I imagine it could be cached by some subclass.

Parameters:

sock - the socket no longer used