Package org.apache.xmlrpc.webserver

Class 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();

    • Constructor Summary

      Constructors 
      Constructor Description
      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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      private void setupServerSocket​(int backlog)
      Initializes this server's listener socket with the specified attributes, assuring that a socket timeout has been set.
      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

      • listener

        private java.lang.Thread listener

      • accept

        protected final java.util.List accept

      • deny

        protected final java.util.List deny

      • address

        private java.net.InetAddress address

      • port

        private int port

      • paranoid

        private boolean paranoid

    • 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

      • 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()

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

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