Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.xmlrpc.webserver
Class WebServer

    java.lang.Object
      org.apache.xmlrpc.webserver.WebServer

All Implemented Interfaces:
  java.lang.Runnable

Direct Known Subclasses:
  ServletWebServer

    public class WebServer

extends java.lang.Object
implements java.lang.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 java.util.List` | `accept`
`protected java.util.List` | `deny`
`protected XmlRpcStreamServer` | `server`
`protected java.net.ServerSocket` | `serverSocket`

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

Method Summary
`void` | `acceptClient(java.lang.String pAddress)` Add an IP address to the list of accepted clients.
`protected boolean` | `allowConnection(java.net.Socket s)` Checks incoming connections to see if they should be allowed.
`protected java.net.ServerSocket` | `createServerSocket(int pPort, int backlog, java.net.InetAddress addr)` Factory method to manufacture the server socket.
`void` | `denyClient(java.lang.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`.
`protected boolean` | `isParanoid()` Returns the client filtering state.
`void` | `log(java.lang.String pMessage)` Logs a message.
`void` | `log(java.lang.Throwable pError)` Logs an error.
`protected ThreadPool.Task` | `newTask(WebServer pServer, XmlRpcStreamServer pXmlRpcServer, java.net.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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### serverSocket

    protected java.net.ServerSocket serverSocket

### accept

    protected final java.util.List accept

### deny

    protected final java.util.List deny

### server

    protected final XmlRpcStreamServer server

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,
                     java.net.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

### newXmlRpcStreamServer

    protected XmlRpcStreamServer newXmlRpcStreamServer()

### createServerSocket

    protected java.net.ServerSocket createServerSocket(int pPort,
                                                       int backlog,
                                                       java.net.InetAddress addr)
                                                throws java.io.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.
  Throws:
    `java.io.IOException` - Error creating listener socket.

### start

    public void start()
               throws java.io.IOException

  Spawns a new thread which binds this server to the port it's configured to accept connections on.

  Throws:
    `java.io.IOException` - Binding the server socket failed.
  See Also:
    `run()`

### 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)`

### isParanoid

    protected boolean isParanoid()

  Returns the client filtering state.

  Returns:
    True, if client filtering is enabled, false otherwise.
  See Also:
    `acceptClient(java.lang.String)`, `denyClient(java.lang.String)`

### acceptClient

    public void acceptClient(java.lang.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:
    `java.lang.IllegalArgumentException` - Parsing the address failed.
  See Also:
    `denyClient(java.lang.String)`, `setParanoid(boolean)`

### denyClient

    public void denyClient(java.lang.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:
    `java.lang.IllegalArgumentException` - Parsing the address failed.
  See Also:
    `acceptClient(java.lang.String)`, `setParanoid(boolean)`

### allowConnection

    protected boolean allowConnection(java.net.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.

### newTask

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

  Throws:
    `java.io.IOException`

### run

    public void run()

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

  Specified by:
    `run` in interface `java.lang.Runnable`
  Throws:
    `java.lang.RuntimeException` - Generally caused by either an `UnknownHostException` or `BindException` with the vanilla web server.
  See Also:
    `start()`, `shutdown()`

### newThreadPool

    protected ThreadPool newThreadPool()

### shutdown

    public void shutdown()

  Stop listening on the server port. Shutting down our `listener` effectively breaks it out of its `run()` loop.

  See Also:
    `run()`

### getPort

    public int getPort()

  Returns the port, on which the web server is running. This method may be invoked after `start()` only.

  Returns:
    Servers port number

### log

    public void log(java.lang.Throwable pError)

  Logs an error.

  Parameters:
    `pError` - The error being logged.

### log

    public void log(java.lang.String pMessage)

  Logs a message.

  Parameters:
    `pMessage` - The being logged.

### getXmlRpcServer

    public XmlRpcStreamServer getXmlRpcServer()

  Returns the `XmlRpcServer`.

  Returns:
    The server object.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2010 The Apache Software Foundation. All Rights Reserved.