org.apache.xmlrpc.webserver

Class WebServer

public class WebServer extends Object implements Runnable

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

Use of the {@link WebServer} has grown very popular amongst users of Apache XML-RPC. Why this is the case, can hardly be explained, because the {@link 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 {@link WebServer}, it is recommended to use its subclass, the {@link 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 {@link 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 Listaccept
protected Listdeny
protected XmlRpcStreamServerserver
protected ServerSocketserverSocket
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
voidacceptClient(String pAddress)
Add an IP address to the list of accepted clients.
protected booleanallowConnection(Socket s)
Checks incoming connections to see if they should be allowed.
protected ServerSocketcreateServerSocket(int pPort, int backlog, InetAddress addr)
Factory method to manufacture the server socket.
voiddenyClient(String pAddress)
Add an IP address to the list of denied clients.
intgetPort()
Returns the port, on which the web server is running.
XmlRpcStreamServergetXmlRpcServer()
Returns the {@link org.apache.xmlrpc.server.XmlRpcServer}.
voidlog(Throwable pError)
Logs an error.
voidlog(String pMessage)
Logs a message.
protected ThreadPool.TasknewTask(WebServer pServer, XmlRpcStreamServer pXmlRpcServer, Socket pSocket)
protected ThreadPoolnewThreadPool()
protected XmlRpcStreamServernewXmlRpcStreamServer()
voidrun()
Listens for client requests until stopped.
voidsetParanoid(boolean pParanoid)
Switch client filtering on/off.
voidshutdown()
Stop listening on the server port.
voidstart()
Spawns a new thread which binds this server to the port it's configured to accept connections on.

Field Detail

accept

protected final List accept

deny

protected final List deny

server

protected final XmlRpcStreamServer server

serverSocket

protected ServerSocket serverSocket

Constructor Detail

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 Detail

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.

Throws: IllegalArgumentException Parsing the address failed.

See Also: WebServer WebServer

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)
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.

Throws: IOException Error creating listener socket.

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.

Throws: IllegalArgumentException Parsing the address failed.

See Also: WebServer WebServer

getPort

public int getPort()
Returns the port, on which the web server is running. This method may be invoked after {@link #start()} only.

Returns: Servers port number

getXmlRpcServer

public XmlRpcStreamServer getXmlRpcServer()
Returns the {@link org.apache.xmlrpc.server.XmlRpcServer}.

Returns: The server object.

log

public void log(Throwable pError)
Logs an error.

Parameters: pError The error being logged.

log

public void log(String pMessage)
Logs a message.

Parameters: pMessage The being logged.

newTask

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

newThreadPool

protected ThreadPool newThreadPool()

newXmlRpcStreamServer

protected XmlRpcStreamServer newXmlRpcStreamServer()

run

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

Throws: RuntimeException Generally caused by either an UnknownHostException or BindException with the vanilla web server.

See Also: start shutdown

setParanoid

public void setParanoid(boolean pParanoid)
Switch client filtering on/off.

Parameters: pParanoid True to enable filtering, false otherwise.

See Also: WebServer WebServer

shutdown

public void shutdown()
Stop listening on the server port. Shutting down our {@link #listener} effectively breaks it out of its {@link #run()} loop.

See Also: run

start

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

Throws: IOException Binding the server socket failed.

See Also: run

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