com.flat502.rox.server
Class HttpRpcServer

java.lang.Object
  com.flat502.rox.processing.HttpRpcProcessor
      com.flat502.rox.server.HttpRpcServer

Direct Known Subclasses:

XmlRpcServer

public abstract class HttpRpcServer
extends HttpRpcProcessor

This is the server-side RPC interface.

This class supports both synchronous and asynchronous handling of method calls. An instance is backed by at least two threads: a selecting thread and a worker thread. Both threads are daemon threads.

The selecting thread handles all low-level network I/O. As soon as this thread identifies a complete HTTP request the request is passed to the worker thread (or threads).

The number of worker threads may be adjusted dynamically using the inherited HttpRpcProcessor.addWorker() and HttpRpcProcessor.removeWorker() methods. Worker threads are responsible for notification of registered RequestHandlers.

Field Summary

Fields inherited from class com.flat502.rox.processing.HttpRpcProcessor

ALL_CIPHER_SUITES, ANON_CIPHER_SUITES

Constructor Summary

HttpRpcServer(java.net.InetAddress hostAddress, int port, boolean useHttps, ServerResourcePool workerPool)
Initialize a new HTTP RPC server.

HttpRpcServer(java.net.InetAddress hostAddress, int port, boolean useHttps, ServerResourcePool workerPool, SSLConfiguration sslCfg)

Method Summary

protected void	accept(java.nio.channels.SelectionKey key) Called when a new connection is pending on the underlying ServerSocketChannel.
protected void	deregisterResponseCoordinator(com.flat502.rox.server.ResponseCoordinator coordinator)
protected void	deregisterSocket(java.net.Socket socket)
protected HttpMessageBuffer	getReadBuffer(java.net.Socket socket) Called when data is available on a socket.
protected java.lang.String	getServerName()
protected java.nio.ByteBuffer	getWriteBuffer(java.net.Socket socket) Called when a socket becomes available for writing.
protected void	handleMessageException(HttpMessageBuffer msg, java.lang.Exception e) Converts an exception raised while processing an HTTP request into a suitable HTTP response.
protected void	handleProcessingException(java.net.Socket socket, java.lang.Exception e) An error handler invoked when an error occurs within the main processing loop.
protected void	handleSelectionKeyOperation(java.nio.channels.SelectionKey key) This implementation defers to the accept(SelectionKey) method if a connection is pending.
protected void	handleSSLHandshakeFinished(java.net.Socket socket, javax.net.ssl.SSLEngine engine)
protected void	handleTimeout(java.net.Socket socket, java.lang.Exception cause)
protected void	initSelector(java.nio.channels.Selector selector) Creates and initializes a ServerSocketChannel for accepting connections on.
protected javax.net.ssl.SSLEngine	initSocketSSLEngine(java.net.Socket socket)
protected boolean	isWriteQueued(java.net.Socket socket) Called to find out if data is queued to be written to a socket.
protected HttpResponse	newHttpResponse(HttpMessageBuffer msg, HttpResponseException e)
protected HttpResponse	newHttpResponse(HttpMessageBuffer origMsg, int statusCode, java.lang.String reasonPhrase, Encoding encoding)
protected RpcCallContext	newRpcCallContext(java.net.Socket socket, HttpRequestBuffer req)
protected ResourcePool	newWorkerPool() Factory method for new worker pools.
protected void	putWriteBuffer(java.net.Socket socket, java.nio.ByteBuffer data) Called when data is available to be written to a socket.
protected void	read(java.nio.channels.SelectionKey key) Reads any pending data from the socket indicated by the given SelectionKey.
void	registerAcceptPolicy(AcceptPolicy policy)
void	registerContentEncoding(Encoding encoding)
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, AsynchronousRequestHandler handler) Register an asynchronous XML-RPC method call handler.
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, AsynchronousRequestHandler handler, MethodCallUnmarshallerAid aid) Register an asynchronous XML-RPC method call handler.
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, AsyncRequestHandler handler) Deprecated. Use registerHandler(String, String, AsynchronousRequestHandler) instead.
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, AsyncRequestHandler handler, MethodCallUnmarshallerAid aid) Deprecated. Use registerHandler(String, String, AsynchronousRequestHandler, MethodCallUnmarshallerAid) instead.
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, SynchronousRequestHandler handler) Register a synchronous XML-RPC method call handler.
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, SynchronousRequestHandler handler, MethodCallUnmarshallerAid aid) Register a synchronous XML-RPC method call handler.
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, SyncRequestHandler handler) Deprecated. Use registerHandler(String, String, SynchronousRequestHandler) instead.
RequestHandler	registerHandler(java.lang.String uriPath, java.lang.String method, SyncRequestHandler handler, MethodCallUnmarshallerAid aid) Deprecated. Use registerHandler(String, String, SynchronousRequestHandler, MethodCallUnmarshallerAid) instead.
HttpRequestUnmarshaller	registerRequestUnmarshaller(java.lang.String httpMethod, HttpRequestUnmarshaller unmarshaller) Register an HttpRequestUnmarshaller instance for a given HTTP method.
protected void	removeReadBuffer(java.net.Socket socket) Called when a complete HTTP message has been identified.
protected void	removeReadBuffers(java.net.Socket socket) Called when a a socket is deregistered and any buffers associated with it should be released.
protected void	removeWriteBuffer(java.net.Socket socket) Called when a all of the data in a pending write buffer has been written to a socket.
protected void	removeWriteBuffers(java.net.Socket socket) Called when a a socket is deregistered and any buffers associated with it should be released.
protected Encoding	selectResponseEncoding(HttpRequestBuffer request)
void	setEncodeResponses(boolean encode)
void	setIdleClientTimeout(int timeout)
protected void	stopImpl()
protected HttpResponse	toHttpResponse(HttpMessageBuffer origMsg, RpcResponse methodRsp, Encoding encoding) Constructs a new HttpResponse containing the given XML-RPC method response.
protected void	write(java.nio.channels.SelectionKey key) Writes any pending data to the socket indicated by the given SelectionKey.

Methods inherited from class com.flat502.rox.processing.HttpRpcProcessor

addWorker, addWorkers, deregisterChannel, getQueue, getSocketSelector, getSSLConfiguration, getSSLSession, getTimer, getWorkerCount, initialize, isSharedWorkerPool, isStarted, newSSLSession, queueCancellation, queueRead, queueRegistration, queueWrite, queueWrite, registerChannel, registerProfiler, registerSocket, registerSSLSessionPolicy, removeWorker, setCipherSuitePattern, setSSLHandshakeTimeout, shouldUseHTTPS, start, stop

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpRpcServer

public HttpRpcServer(java.net.InetAddress hostAddress,
                     int port,
                     boolean useHttps,
                     ServerResourcePool workerPool)
              throws java.io.IOException

Initialize a new HTTP RPC server.

The server will not attempt to bind to a local port or being accepting connections (and by implication processing requests) until Thread.start() is invoked on this instance.

Parameters:

hostAddress - An InetAddress this instance should bind to when listening for connections. null is interpreted as "listen on all interfaces".

port -

useHttps -

workerPool -

Throws:

java.io.IOException

HttpRpcServer

public HttpRpcServer(java.net.InetAddress hostAddress,
                     int port,
                     boolean useHttps,
                     ServerResourcePool workerPool,
                     SSLConfiguration sslCfg)
              throws java.io.IOException

Throws:

java.io.IOException

Method Detail

registerAcceptPolicy

public void registerAcceptPolicy(AcceptPolicy policy)

registerContentEncoding

public void registerContentEncoding(Encoding encoding)

setEncodeResponses

public void setEncodeResponses(boolean encode)

setIdleClientTimeout

public void setIdleClientTimeout(int timeout)

registerRequestUnmarshaller

public HttpRequestUnmarshaller registerRequestUnmarshaller(java.lang.String httpMethod,
                                                           HttpRequestUnmarshaller unmarshaller)

Register an HttpRequestUnmarshaller instance for a given HTTP method.

If a prior unmarshaller instance exists for the named HTTP method the unmarshaller instance is replaced and the previously registered instance is returned.

Parameters:

httpMethod - The HTTP method to register the unmarshaller to handle. Custom HTTP methods may be used. No validation is performed on this value, it is only used as a mapping key.

unmarshaller - The HttpRequestUnmarshaller instance to register for the given HTTP method. This may be null which effectively deregisters any existing handler for the given HTTP method.

Returns:

The HttpRequestUnmarshaller instance previously registered to handle the given HTTP method, or null if no prior instance was registered.

See Also:

CgiRequestUnmarshaller, XmlRpcRequestUnmarshaller, HttpConstants.Methods

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      AsyncRequestHandler handler)

Deprecated. Use registerHandler(String, String, AsynchronousRequestHandler) instead.

Register an asynchronous XML-RPC method call handler.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

See Also:

registerHandler(String, String, SyncRequestHandler, MethodCallUnmarshallerAid)

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      AsynchronousRequestHandler handler)

Register an asynchronous XML-RPC method call handler.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

See Also:

registerHandler(String, String, SyncRequestHandler, MethodCallUnmarshallerAid)

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      AsyncRequestHandler handler,
                                      MethodCallUnmarshallerAid aid)

Deprecated. Use registerHandler(String, String, AsynchronousRequestHandler, MethodCallUnmarshallerAid) instead.

Register an asynchronous XML-RPC method call handler.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

aid - A mapper to be used during the unmarshalling of parameters of incoming method calls. May be null.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

See Also:

registerHandler(String, String, SyncRequestHandler, MethodCallUnmarshallerAid)

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      AsynchronousRequestHandler handler,
                                      MethodCallUnmarshallerAid aid)

Register an asynchronous XML-RPC method call handler.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

aid - A mapper to be used during the unmarshalling of parameters of incoming method calls. May be null.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

See Also:

registerHandler(String, String, SyncRequestHandler, MethodCallUnmarshallerAid)

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      SyncRequestHandler handler)

Deprecated. Use registerHandler(String, String, SynchronousRequestHandler) instead.

Register a synchronous XML-RPC method call handler.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

See Also:

registerHandler(String, String, SyncRequestHandler, MethodCallUnmarshallerAid)

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      SynchronousRequestHandler handler)

Register a synchronous XML-RPC method call handler.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

See Also:

registerHandler(String, String, SyncRequestHandler, MethodCallUnmarshallerAid)

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      SyncRequestHandler handler,
                                      MethodCallUnmarshallerAid aid)

Deprecated. Use registerHandler(String, String, SynchronousRequestHandler, MethodCallUnmarshallerAid) instead.

Register a synchronous XML-RPC method call handler.

Handlers are indexed first using the normalized URI and then using the method name regular expression.

When a request is available the handler for the request is chosen by looking up the list of handlers registered under the associated URI (after normalization). This list is then scanned until a regular expression matches the given method name. If no match is found this is repeated using a null URI (i.e. a more specific URI match takes precedence).

If no handler is found an HTTP "404 Not Found" response is sent to the client.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

aid - A mapper to be used during the unmarshalling of parameters of incoming method calls. May be null.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

registerHandler

public RequestHandler registerHandler(java.lang.String uriPath,
                                      java.lang.String method,
                                      SynchronousRequestHandler handler,
                                      MethodCallUnmarshallerAid aid)

Register a synchronous XML-RPC method call handler.

Handlers are indexed first using the normalized URI and then using the method name regular expression.

When a request is available the handler for the request is chosen by looking up the list of handlers registered under the associated URI (after normalization). This list is then scanned until a regular expression matches the given method name. If no match is found this is repeated using a null URI (i.e. a more specific URI match takes precedence).

If no handler is found an HTTP "404 Not Found" response is sent to the client.

Parameters:

uriPath - URIs for which this handler is responsible. null indicates all URIs.

method - A regular expression (see Pattern) to match method names on. Matching is performed as for the Matcher.find() method.

handler - The handler to call back when a request is received matching the indicated URI and method name pattern.

aid - A mapper to be used during the unmarshalling of parameters of incoming method calls. May be null.

Returns:

If a previously registered request handler existed and this handler replaced it (i.e. their URI and method regular expression were identical)

newRpcCallContext

protected RpcCallContext newRpcCallContext(java.net.Socket socket,
                                           HttpRequestBuffer req)

toHttpResponse

protected HttpResponse toHttpResponse(HttpMessageBuffer origMsg,
                                      RpcResponse methodRsp,
                                      Encoding encoding)
                               throws java.io.IOException,
                                      MarshallingException

Constructs a new HttpResponse containing the given XML-RPC method response.

This implementation encodes the response using UTF-8, sets the status code to 200, and sets Content-Type header to text/xml as required. No other headers are set.

Parameters:

methodRsp - The XML-RPC method response to be returned in the HTTP response.

encoding - An Encoding describing the encoding to use when constructing this message. This also informs the Content-Encoding header value. May be null.

Returns:

A new HttpResponse with the marshalled XML-RPC response as its content.

Throws:

java.io.IOException - if an error occurs while marshalling the XML-RPC response.

MarshallingException

selectResponseEncoding

protected Encoding selectResponseEncoding(HttpRequestBuffer request)

newWorkerPool

protected ResourcePool newWorkerPool()

Description copied from class: HttpRpcProcessor

Factory method for new worker pools.

This is invoked from the constructor to create a new worker pool when one is not provided.

Specified by:

newWorkerPool in class HttpRpcProcessor

Returns:

A new ResourcePool.

handleSelectionKeyOperation

protected void handleSelectionKeyOperation(java.nio.channels.SelectionKey key)
                                    throws java.io.IOException

This implementation defers to the accept(SelectionKey) method if a connection is pending. In all other cases it defers to it's parent.

Overrides:

handleSelectionKeyOperation in class HttpRpcProcessor

Parameters:

key - The SelectionKey for the socket on which an I/O operation is pending.

Throws:

java.io.IOException - if an error occurs while processing the pending event.

read

protected void read(java.nio.channels.SelectionKey key)
             throws java.io.IOException

Description copied from class: HttpRpcProcessor

Reads any pending data from the socket indicated by the given SelectionKey.

This implementation retrieves an HttpMessageBuffer instance for the indicated socket using the HttpRpcProcessor.getReadBuffer(Socket) method. Data present on the socket is added to this buffer and if a complete HTTP message has been received it is enqueued on the shared queue.

Overrides:

read in class HttpRpcProcessor

Parameters:

key - The SelectionKey indicating the socket available for writing.

Throws:

java.io.IOException - If an error occurs while attempting to read from the indicated socket.

write

protected void write(java.nio.channels.SelectionKey key)
              throws java.io.IOException

Description copied from class: HttpRpcProcessor

Writes any pending data to the socket indicated by the given SelectionKey.

This implementation checks for data using the HttpRpcProcessor.getWriteBuffer(Socket) method. If data is available as much as possible is written to the socket.

Overrides:

write in class HttpRpcProcessor

Parameters:

key - The SelectionKey indicating the socket available for writing.

Throws:

java.io.IOException - If an error occurs while attempting to write to the indicated socket.

deregisterSocket

protected void deregisterSocket(java.net.Socket socket)

Overrides:

deregisterSocket in class HttpRpcProcessor

deregisterResponseCoordinator

protected void deregisterResponseCoordinator(com.flat502.rox.server.ResponseCoordinator coordinator)

accept

protected void accept(java.nio.channels.SelectionKey key)
               throws java.io.IOException

Called when a new connection is pending on the underlying ServerSocketChannel.

Parameters:

key - The SelectionKey for the socket on which a connection is pending.

Throws:

java.io.IOException - if an error occurs while accepting the new connection.

handleMessageException

protected void handleMessageException(HttpMessageBuffer msg,
                                      java.lang.Exception e)
                               throws java.io.IOException

Converts an exception raised while processing an HTTP request into a suitable HTTP response.

The response is marshalled and queued for writing on the socket associated with the original request.

Specified by:

handleMessageException in class HttpRpcProcessor

Parameters:

msg - The HTTP request being processed when the exception occurred.

e - The exception that was raised.

Throws:

java.io.IOException - if an error occurs marshalling or writing the response.

handleProcessingException

protected void handleProcessingException(java.net.Socket socket,
                                         java.lang.Exception e)

Description copied from class: HttpRpcProcessor

An error handler invoked when an error occurs within the main processing loop.

Specified by:

handleProcessingException in class HttpRpcProcessor

Parameters:

socket - The socket the exception is associated with. This may be null if the exception is not specific to a particular socket.

e - The exception that was raised.

handleTimeout

protected void handleTimeout(java.net.Socket socket,
                             java.lang.Exception cause)

Specified by:

handleTimeout in class HttpRpcProcessor

handleSSLHandshakeFinished

protected void handleSSLHandshakeFinished(java.net.Socket socket,
                                          javax.net.ssl.SSLEngine engine)

Specified by:

handleSSLHandshakeFinished in class HttpRpcProcessor

stopImpl

protected void stopImpl()
                 throws java.io.IOException

Specified by:

stopImpl in class HttpRpcProcessor

Throws:

java.io.IOException

initSelector

protected void initSelector(java.nio.channels.Selector selector)
                     throws java.io.IOException

Creates and initializes a ServerSocketChannel for accepting connections on.

Overrides:

initSelector in class HttpRpcProcessor

Throws:

java.io.IOException - If an error occurs while attempting to create the Selector.

initSocketSSLEngine

protected javax.net.ssl.SSLEngine initSocketSSLEngine(java.net.Socket socket)
                                               throws javax.net.ssl.SSLException

Overrides:

initSocketSSLEngine in class HttpRpcProcessor

Throws:

javax.net.ssl.SSLException

getReadBuffer

protected HttpMessageBuffer getReadBuffer(java.net.Socket socket)

Description copied from class: HttpRpcProcessor

Called when data is available on a socket.

Implementations must return a buffer, even if this means creating a new instance. The same buffer should be returned for a given socket until the HttpRpcProcessor.removeReadBuffer(Socket) method is invoked, ensuring that message fragmentation is correctly handled.

Specified by:

getReadBuffer in class HttpRpcProcessor

Parameters:

socket - The socket on which data has arrived.

Returns:

A message buffer for the given socket.

removeReadBuffer

protected void removeReadBuffer(java.net.Socket socket)

Description copied from class: HttpRpcProcessor

Called when a complete HTTP message has been identified.

Specified by:

removeReadBuffer in class HttpRpcProcessor

Parameters:

socket - The socket on which a complete message has been received.

removeReadBuffers

protected void removeReadBuffers(java.net.Socket socket)

Description copied from class: HttpRpcProcessor

Called when a a socket is deregistered and any buffers associated with it should be released.

Specified by:

removeReadBuffers in class HttpRpcProcessor

Parameters:

socket - The socket on which a complete message has been received.

putWriteBuffer

protected void putWriteBuffer(java.net.Socket socket,
                              java.nio.ByteBuffer data)

Description copied from class: HttpRpcProcessor

Called when data is available to be written to a socket.

Specified by:

putWriteBuffer in class HttpRpcProcessor

Parameters:

socket - The socket on which the data should be sent.

data - The data to be written.

isWriteQueued

protected boolean isWriteQueued(java.net.Socket socket)

Description copied from class: HttpRpcProcessor

Called to find out if data is queued to be written to a socket.

Specified by:

isWriteQueued in class HttpRpcProcessor

Parameters:

socket - The socket on which the data should be sent.

Returns:

true if there is a buffer waiting to be written on the given socket

getWriteBuffer

protected java.nio.ByteBuffer getWriteBuffer(java.net.Socket socket)

Description copied from class: HttpRpcProcessor

Called when a socket becomes available for writing.

Implementations should return a buffer only if one has been added using HttpRpcProcessor.putWriteBuffer(Socket, ByteBuffer). The same buffer should be returned for a given socket until the HttpRpcProcessor.removeWriteBuffer(Socket) method is invoked, ensuring that large messages that must be written in multiple fragments are correctly handled.

Specified by:

getWriteBuffer in class HttpRpcProcessor

Parameters:

socket - The socket that is available for writing.

Returns:

A data buffer for the given socket.

removeWriteBuffer

protected void removeWriteBuffer(java.net.Socket socket)

Description copied from class: HttpRpcProcessor

Called when a all of the data in a pending write buffer has been written to a socket.

Specified by:

removeWriteBuffer in class HttpRpcProcessor

Parameters:

socket - The socket the buffer was associated with.

removeWriteBuffers

protected void removeWriteBuffers(java.net.Socket socket)

Description copied from class: HttpRpcProcessor

Called when a a socket is deregistered and any buffers associated with it should be released.

Specified by:

removeWriteBuffers in class HttpRpcProcessor

Parameters:

socket - The socket the buffer was associated with.

newHttpResponse

protected HttpResponse newHttpResponse(HttpMessageBuffer msg,
                                       HttpResponseException e)

newHttpResponse

protected HttpResponse newHttpResponse(HttpMessageBuffer origMsg,
                                       int statusCode,
                                       java.lang.String reasonPhrase,
                                       Encoding encoding)

getServerName

protected java.lang.String getServerName()