org.apache.xmlrpc.webserver

Class WebServer

Implemented Interfaces:
Runnable
Known Direct Subclasses:
ServletWebServer

public class WebServer
extends java.lang.Object
implements Runnable

The WebServer is a minimal HTTP server, that might be used as an embedded web server.

Use of the WebServer has grown very popular amongst users of Apache XML-RPC. Why this is the case, can hardly be explained, because the WebServer is at best a workaround, compared to full blown servlet engines like Tomcat or Jetty. For example, under heavy load it will almost definitely be slower than a real servlet engine, because it does neither support proper keepalive (multiple requests per physical connection) nor chunked mode (in other words, it cannot stream requests).

If you still insist in using the WebServer, it is recommended to use its subclass, the ServletWebServer instead, which offers a minimal subset of the servlet API. In other words, you keep yourself the option to migrate to a real servlet engine later.

Use of the WebServer goes roughly like this: First of all, create a property file (for example "MyHandlers.properties") and add it to your jar file. The property keys are handler names and the property values are the handler classes. Once that is done, create an instance of WebServer:

   final int port = 8088;
   final String propertyFile = "MyHandler.properties";

   PropertyHandlerMapping mapping = new PropertyHandlerMapping();
   ClassLoader cl = Thread.currentThread().getContextClassLoader();
   mapping.load(cl, propertyFile);
   WebServer webServer = new WebServer(port);
   XmlRpcServerConfigImpl config = new XmlRpcServerConfigImpl();
   XmlRpcServer server = webServer.getXmlRpcServer();
   server.setConfig(config);
   server.setHandlerMapping(mapping);
   webServer.start();
 

Field Summary

protected List
accept
protected List
deny
protected XmlRpcStreamServer
server
protected ServerSocket
serverSocket

Constructor Summary

WebServer(int pPort)
Creates a web server at the specified port number.
WebServer(int pPort, InetAddress pAddr)
Creates a web server at the specified port number and IP address.

Method Summary

void
acceptClient(String pAddress)
Add an IP address to the list of accepted clients.
protected boolean
allowConnection(Socket s)
Checks incoming connections to see if they should be allowed.
protected ServerSocket
createServerSocket(int pPort, int backlog, InetAddress addr)
Factory method to manufacture the server socket.
void
denyClient(String pAddress)
Add an IP address to the list of denied clients.
int
getPort()
Returns the port, on which the web server is running.
XmlRpcStreamServer
getXmlRpcServer()
Returns the XmlRpcServer.
void
log(String pMessage)
Logs a message.
void
log(Throwable pError)
Logs an error.
protected ThreadPool.Task
newTask(WebServer pServer, XmlRpcStreamServer pXmlRpcServer, Socket pSocket)
protected ThreadPool
newThreadPool()
protected XmlRpcStreamServer
newXmlRpcStreamServer()
void
run()
Listens for client requests until stopped.
void
setParanoid(boolean pParanoid)
Switch client filtering on/off.
void
shutdown()
Stop listening on the server port.
void
start()
Spawns a new thread which binds this server to the port it's configured to accept connections on.

Field Details

accept

protected final List accept

deny

protected final List deny

server

protected final XmlRpcStreamServer server

serverSocket

protected ServerSocket serverSocket

Constructor Details

WebServer

public WebServer(int pPort)
Creates a web server at the specified port number.
Parameters:
pPort - Port number; 0 for a random port, choosen by the operating system.

WebServer

public WebServer(int pPort,
                 InetAddress pAddr)
Creates a web server at the specified port number and IP address.
Parameters:
pPort - Port number; 0 for a random port, choosen by the operating system.
pAddr - Local IP address; null for all available IP addresses.

Method Details

acceptClient

public void acceptClient(String pAddress)
Add an IP address to the list of accepted clients. The parameter can contain '*' as wildcard character, e.g. "192.168.*.*". You must call setParanoid(true) in order for this to have any effect.
Parameters:
pAddress - The IP address being enabled.

allowConnection

protected boolean allowConnection(Socket s)
Checks incoming connections to see if they should be allowed. If not in paranoid mode, always returns true.
Parameters:
s - The socket to inspect.
Returns:
Whether the connection should be allowed.

createServerSocket

protected ServerSocket createServerSocket(int pPort,
                                          int backlog,
                                          InetAddress addr)
            throws IOException
Factory method to manufacture the server socket. Useful as a hook method for subclasses to override when they desire different flavor of socket (i.e. a SSLServerSocket).
Parameters:
pPort - Port number; 0 for a random port, choosen by the operating system.
backlog -
addr - If null, binds to INADDR_ANY, meaning that all network interfaces on a multi-homed host will be listening.

denyClient

public void denyClient(String pAddress)
Add an IP address to the list of denied clients. The parameter can contain '*' as wildcard character, e.g. "192.168.*.*". You must call setParanoid(true) in order for this to have any effect.
Parameters:
pAddress - The IP address being disabled.

getPort

public int getPort()
Returns:
Servers port number

getXmlRpcServer

public XmlRpcStreamServer getXmlRpcServer()
Returns the XmlRpcServer.
Returns:
The server object.

log

public void log(String pMessage)
Logs a message.
Parameters:
pMessage - The being logged.

log

public void log(Throwable pError)
Logs an error.
Parameters:
pError - The error being logged.

newTask

protected ThreadPool.Task newTask(WebServer pServer,
                                  XmlRpcStreamServer pXmlRpcServer,
                                  Socket pSocket)
            throws IOException

newThreadPool

protected ThreadPool newThreadPool()

newXmlRpcStreamServer

protected XmlRpcStreamServer newXmlRpcStreamServer()

run

public void run()
Listens for client requests until stopped. Call start() to invoke this method, and shutdown() to break out of it.

setParanoid

public void setParanoid(boolean pParanoid)
Switch client filtering on/off.
Parameters:
pParanoid - True to enable filtering, false otherwise.
See Also:
acceptClient(java.lang.String), denyClient(java.lang.String)

shutdown

public void shutdown()
See Also:
run()

start

public void start()
            throws IOException
Spawns a new thread which binds this server to the port it's configured to accept connections on.

Copyright © 2001-2007 Apache Software Foundation. All Rights Reserved.