svn commit: r423226 - in /webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver: ServletWebServer.java WebServer.java XmlRpcServlet.java

[jo...@apache.org]

Author: jochen
Date: Tue Jul 18 13:05:46 2006
New Revision: 423226

URL: http://svn.apache.org/viewvc?rev=423226&view=rev
Log:
Improved docs of WebServer and ServletWebServer classes.

Modified:
    webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/ServletWebServer.java
    webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/WebServer.java
    webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/XmlRpcServlet.java

Modified: webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/ServletWebServer.java
URL: http://svn.apache.org/viewvc/webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/ServletWebServer.java?rev=423226&r1=423225&r2=423226&view=diff
==============================================================================
--- webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/ServletWebServer.java (original)
+++ webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/ServletWebServer.java Tue Jul 18 13:05:46 2006
@@ -26,12 +26,35 @@
 import javax.servlet.ServletException;
 import javax.servlet.http.HttpServlet;
 
+import org.apache.xmlrpc.server.PropertyHandlerMapping;
 import org.apache.xmlrpc.server.XmlRpcStreamServer;
 import org.apache.xmlrpc.util.ThreadPool;
 
 
-/** A subclass of {@link WebServer}, which emulates a servlet
- * container. Mainly useful for debugging.
+/**
+ * <p>This is a subclass of the {@link WebServer}, which offers a minimal
+ * servlet API. It is recommended to use this class, rather than the
+ * {@link WebServer}, because it offers you a smooth migration path to
+ * a full blown servlet engine.</p>
+ * <p>Use of the {@link ServletWebServer} goes like this: First of all,
+ * create a servlet. It may be an instance of {@link XmlRpcServlet} or
+ * a subclass thereof. Note, that servlets are stateless: One servlet
+ * may be used by multiple threads (aka requests) concurrently. In
+ * other words, the servlet must not have any instance variables,
+ * other than those which are read only after the servlets
+ * initialization.</p>
+ * <p>The XmlRpcServlet is by default using a property file named
+ * <code>org/apache/xmlrpc/server/webserver/XmlRpcServlet.properties</code>.
+ * See the {@link PropertyHandlerMapping} for details on the property
+ * file.</p>
+ * <pre>
+ *   final int portNumber = 8088;
+ *
+ *   ClassLoader cl = Thread.currentThread().getContextClassLoader();
+ *   XmlRpcServlet servlet = new XmlRpcServlet();
+ *   ServletWebServer webServer = new ServletWebServer(servlet, port);
+ *   webServer.start();
+ * </pre>
  */
 public class ServletWebServer extends WebServer {
 	/** This exception is thrown by the request handling classes,

Modified: webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/WebServer.java
URL: http://svn.apache.org/viewvc/webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/WebServer.java?rev=423226&r1=423225&r2=423226&view=diff
==============================================================================
--- webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/WebServer.java (original)
+++ webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/WebServer.java Tue Jul 18 13:05:46 2006
@@ -32,7 +32,45 @@
 import org.apache.xmlrpc.util.ThreadPool;
 
 
-/** A minimal web server that exclusively handles XML-RPC requests.
+/**
+ * <p>The {@link WebServer} is a minimal HTTP server, that might be used
+ * as an embedded web server.</p>
+ * <p>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).</p>
+ * <p>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.</p>
+ * <p>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:
+ * <pre>
+ *   final int portNumber = 8088;
+ *   final String propertyFile = "MyHandler.properties";
+ *
+ *   ClassLoader cl = Thread.currentThread().getContextClassLoader();
+ *   URL url = cl.getResource(property);
+ *   if (url == null) {
+ *     throw new NullPointerException("No such resource: " + property);
+ *   }
+ *   PropertyHandlerMapping mapping = new PropertyHandlerMapping(cl,
+ *       url, new TypeConverterFactoryImpl(), false);
+ *   WebServer webServer = new WebServer(port);
+ *   XmlRpcServerConfigImpl config = new XmlRpcServerConfigImpl();
+ *   XmlRpcServer server = server.getXmlRpcServer();
+ *   server.setConfig(config);
+ *   server.setHandlerMapping(mapping);
+ *   server.start();
+ * </pre>
  */
 public class WebServer implements Runnable {
 	private static final Log log = LogFactory.getLog(WebServer.class);

Modified: webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/XmlRpcServlet.java
URL: http://svn.apache.org/viewvc/webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/XmlRpcServlet.java?rev=423226&r1=423225&r2=423226&view=diff
==============================================================================
--- webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/XmlRpcServlet.java (original)
+++ webservices/xmlrpc/trunk/server/src/main/java/org/apache/xmlrpc/webserver/XmlRpcServlet.java Tue Jul 18 13:05:46 2006
@@ -29,7 +29,6 @@
 import org.apache.xmlrpc.server.PropertyHandlerMapping;
 import org.apache.xmlrpc.server.XmlRpcHandlerMapping;
 import org.apache.xmlrpc.server.XmlRpcServer;
-import org.apache.xmlrpc.server.XmlRpcServerConfig;
 import org.apache.xmlrpc.server.XmlRpcServerConfigImpl;
 
 



---------------------------------------------------------------------
To unsubscribe, e-mail: xmlrpc-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: xmlrpc-dev-help@ws.apache.org