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 [EMAIL PROTECTED] WebServer}, which emulates a servlet
- * container. Mainly useful for debugging.
+/**
+ * <p>This is a subclass of the [EMAIL PROTECTED] WebServer}, which offers a
minimal
+ * servlet API. It is recommended to use this class, rather than the
+ * [EMAIL PROTECTED] WebServer}, because it offers you a smooth migration path
to
+ * a full blown servlet engine.</p>
+ * <p>Use of the [EMAIL PROTECTED] ServletWebServer} goes like this: First of
all,
+ * create a servlet. It may be an instance of [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] WebServer} is a minimal HTTP server, that might be
used
+ * as an embedded web server.</p>
+ * <p>Use of the [EMAIL PROTECTED] WebServer} has grown very popular amongst
users
+ * of Apache XML-RPC. Why this is the case, can hardly be explained,
+ * because the [EMAIL PROTECTED] 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 [EMAIL PROTECTED] WebServer}, it is
+ * recommended to use its subclass, the [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
