Patch: Clarification of thread safety in XmlRpcServer

[Jochen Wiedmann <jo...@freenet.de>]

Hi,

I would like to suggest the following patch for the XmlRpcServer docs.
The current statement is, IMO, misleading. Suggest the following:

  - Thread A invokes addHandler("name", something);
  - Thread B invokes removeHandler("name"); and
    addHandler("name", somethingElse);
  - Thread A calls execute

Result will almost definitely not be as expected.


Jochen


Index: XmlRpcServer.java
===================================================================
RCS file:
/home/cvs/ws-xmlrpc/src/java/org/apache/xmlrpc/XmlRpcServer.java,v
retrieving revision 1.36
diff -u -r1.36 XmlRpcServer.java
--- XmlRpcServer.java	1 May 2004 00:40:47 -0000	1.36
+++ XmlRpcServer.java	11 Jun 2004 09:39:56 -0000
@@ -55,16 +55,23 @@
  * <http://www.apache.org/>.
  */
 
-import java.io.IOException;
 import java.io.InputStream;
 import java.util.EmptyStackException;
 import java.util.Stack;
 
 /**
- * A multithreaded, reusable XML-RPC server object. The name may be
misleading
+ * <p>A reusable XML-RPC server object. The name may be misleading
  * because this does not open any server sockets. Instead it is fed by
passing
  * an XML-RPC input stream to the execute method. If you want to open a
- * HTTP listener, use the WebServer class instead.
+ * HTTP listener, use the WebServer class instead.</p>
+ * <p>This class is thread safe in the following sense:
+ * The process of configuring the XmlRpcServer (using
+ * {@link #addHandler(String, Object)} and {@link
#removeHandler(String)}
+ * is <em>not</em> thread safe. However, the configured XmlRpcServer
+ * <em>is</em> thread safe.</p>
+ * <p>In other words, suggested use is as follows: Create a single
+ * XmlRpcServer, configure it, and store it in a static field. Once
+ * you have done that, you may use the object as you like.</p>
  *
  * @author <a href="mailto:hannes@apache.org">Hannes Wallnoefer</a>
  * @author <a href="mailto:dlr@finemaltcoding.com">Daniel Rall</a>