marquee.xmlrpc

Class XmlRpcServer

java.lang.Object

marquee.xmlrpc.XmlRpcServer

Direct Known Subclasses:

Server

public class XmlRpcServer
extends java.lang.Object

An XmlRpcServer is responsible for hosting a set of invocation handlers and a set of invocation processors. It is invoked by calling the execute() method, supplying a stream containing the XML-RPC message to be handled. The messages will be parsed and dispatched to the corresponding invocation handler, if any.

The XmlRpcServer may also be started as a service accepting connections on a given port. This way, a servlet environment is not required to be able to expose XML-RPC services. The server acts as a minimal HTTP server accepting text/xml posts containing XML-RPC messages, only.

For further information on setting up an XML-RPC server, see the documentation.

Note that a current limitation of the server prevents invocation handlers, invocation processors, and invocation handler aliases to be added after the server is running. Access to these collections has not been synchronized

Since:

JDK 1.1

Version:

$Revision: 1.9 $

Author:

Greger Ohlson (greger.ohlson@marquee.se), Rainer Bischof (rainer.bischof@eds.com)

Constructor Summary

Constructors

Constructor and Description
XmlRpcServer()

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	execute(java.io.InputStream xmlInput) Dispatches the call contained in the supplied input stream.
java.lang.String	getInvocationHandlerAlias(java.lang.String alias) Returns the alias mapping for the supplied alias, or null, if the alias is not registered.
XmlRpcInvocationProcessor	getInvocationProcessor(int index)
int	getInvocationProcessorCount() Returns the number of invocation processors registered in the server.
void	registerInvocationHandler(java.lang.String name, XmlRpcInvocationHandler handler) Binds an invocation handler object to the given name.
void	registerInvocationHandlerAlias(java.lang.String alias, java.lang.String mapping) Binds an invocation handler object to the given name.
void	registerInvocationProcessor(XmlRpcInvocationProcessor processor) Invocation processors are invoked on every call, regardless of which handler or method the call is intended for.
void	registerProxyService(java.lang.Object service) Registers a service that is used by a dynamic proxy created by XmlRpcProxy.
void	registerProxyService(java.lang.Object service, java.lang.String name) Registers a service that is used by a dynamic proxy created by XmlRpcProxy.
void	runAsService(int port) Starts the XmlRpcServer object as a service accepting inbound HTTP connections on the given port.
void	unregisterInvocationHandler(java.lang.String name) Unbinds a previously bound invocation handler.
void	unregisterInvocationHandlerAlias(java.lang.String alias) Unbinds a previously bound invocation handler.
void	unregisterInvocationProcessor(XmlRpcInvocationProcessor processor) Removes a previously registered invocation processor.

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlRpcServer

public XmlRpcServer()

Method Detail

runAsService

public void runAsService(int port)
                  throws java.io.IOException

Starts the XmlRpcServer object as a service accepting inbound HTTP connections on the given port.

Parameters:

port - The port number to be used for inbound connections.

Throws:

java.io.IOException - if a socket error occurs.

execute

public byte[] execute(java.io.InputStream xmlInput)
               throws java.lang.Throwable

Dispatches the call contained in the supplied input stream. The stream should contain a proper XML message conforming to the XML-RPC specification.

Parameters:

xmlInput - The XML-RPC message.

Returns:

An array of bytes representing the XML-RPC response. Any exception occuring in the invocation handlers are embedded in the XML-RPC response.

Throws:

java.lang.Throwable - if the input stream contains unparseable XML or if some error occurs in the SAX driver.

registerInvocationHandler

public void registerInvocationHandler(java.lang.String name,
                             XmlRpcInvocationHandler handler)

Binds an invocation handler object to the given name.

Parameters:

name - The name to bind the handler to.

handler - The invocation handler object.

unregisterInvocationHandler

public void unregisterInvocationHandler(java.lang.String name)

Unbinds a previously bound invocation handler.

Parameters:

name - The name of the handler to unbind.

registerInvocationHandlerAlias

public void registerInvocationHandlerAlias(java.lang.String alias,
                                  java.lang.String mapping)

Binds an invocation handler object to the given name.

Parameters:

name - The name to bind the handler to.

handler - The invocation handler object.

unregisterInvocationHandlerAlias

public void unregisterInvocationHandlerAlias(java.lang.String alias)

Unbinds a previously bound invocation handler.

Parameters:

name - The name of the handler to unbind.

getInvocationHandlerAlias

public java.lang.String getInvocationHandlerAlias(java.lang.String alias)

Returns the alias mapping for the supplied alias, or null, if the alias is not registered.

Parameters:

alias -

Returns:

The alias mapping or null.

registerInvocationProcessor

public void registerInvocationProcessor(XmlRpcInvocationProcessor processor)

Invocation processors are invoked on every call, regardless of which handler or method the call is intended for. Processors are useful for supplying entry points for logging and other utilities like transaction handling. For instance, a fictive TransactionInvocationProcessor may examine the name of the method called upon, and if it starts with "tx_" it may attach an additional transaction object in the argument vector.

Parameters:

processor - An invocation processor that will be invoked on every call sent to this server.

unregisterInvocationProcessor

public void unregisterInvocationProcessor(XmlRpcInvocationProcessor processor)

Removes a previously registered invocation processor. The processor will no longer be invoked on inbound calls.

Parameters:

processor - The invocation processor to remove

getInvocationProcessorCount

public int getInvocationProcessorCount()

Returns the number of invocation processors registered in the server.

getInvocationProcessor

public XmlRpcInvocationProcessor getInvocationProcessor(int index)

Parameters:

index -

Returns:

registerProxyService

public void registerProxyService(java.lang.Object service)

Registers a service that is used by a dynamic proxy created by XmlRpcProxy. The passed service object is bound to the server using the unqualified class names of the implemented interfaces, i.e. the class name of each implemented interface without the leading package identifiers.

Parameters:

Object - service the object that exposes methods to XmlRpc clients

registerProxyService

public void registerProxyService(java.lang.Object service,
                        java.lang.String name)

Registers a service that is used by a dynamic proxy created by XmlRpcProxy. The passed service object is bound to the server using the supplied handler name.

Parameters:

service - the object that exposes methods to XmlRpc clients

name - the name under which the service will be registered