You are viewing a plain text version of this content. The canonical link for it is here.
Posted to rpc-dev@xml.apache.org by ha...@apache.org on 2001/10/31 22:35:14 UTC
cvs commit: xml-rpc/xdocs index.xml client.xml parser.xml server.xml types.xml async.xml builtin.xml docs.xml handler.xml servlet.xml sync.xml
hannes 01/10/31 13:35:14
Modified: xdocs client.xml parser.xml server.xml types.xml
Added: xdocs index.xml
Removed: xdocs async.xml builtin.xml docs.xml handler.xml
servlet.xml sync.xml
Log:
Merged the existing doc with the anakia templates.
Replaced helma with apache, rewrote some parts.
Reduced the number of separate pages by packing
server and client topics into one page each.
Revision Changes Path
1.2 +58 -12 xml-rpc/xdocs/client.xml
Index: client.xml
===================================================================
RCS file: /home/cvs/xml-rpc/xdocs/client.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- client.xml 2001/10/30 16:09:05 1.1
+++ client.xml 2001/10/31 21:35:13 1.2
@@ -9,20 +9,66 @@
<body>
<section name="Client Classes">
<p>
+ Apache XML-RPC provides two client classes.
</p>
+ <ul>
+ <li><a href="/xml-rpc/apidocs/org/apache/xmlrpc/XmlRpcClient.html">org.apache.xmlrpc.XmlRpcClient
+ </a> uses java.net.URLConnection, the HTTP client that comes with
+ the standard Java API</li>
+ <li><a href="/xml-rpc/apidocs/org/apache//xmlrpc/XmlRpcClientLite.html">org.apache.xmlrpc.XmlRpcClientLite</a> provides its own lightweight
+ HTTP client implementation.</li></ul>
+ <p>XmlRpcClientLite is usually faster, but if you need full HTTP support
+ (e.g. Proxies, Redirect etc), you should use XmlRpcClient.Both client
+ classes provide the same interface, which includes
+ methods for synchronous and asynchronous calls.
+ </p>
</section>
- </body>
-</document>
+ <section name="Synchronous XML-RPC Calls">
+ <p>
+ Using the XML-RPC libray on the client side is quite straightforward.
+ Here is some sample code:</p>
+
+<pre>
+ XmlRpcClient xmlrpc = new XmlRpcClient ("http://localhost:8080/RPC2");
+ Vector params = new Vector ();
+ params.addElement ("some parameter");
+ // this method returns a string
+ String result = (String) xmlrpc.execute ("method.name", params);
+</pre>
-<!--
+<p>Note that execute can throw <tt>XmlRpcException</tt> and <tt>IOException</tt>,
+which must be caught or declared by your code.</p>
-Helma provides two XML-RPC client classes.
-<a href="/static/apidocs/helma/xmlrpc/XmlRpcClient.html">helma.xmlrpc.XmlRpcClient
-</a> uses java.net.URLConnection, the HTTP client that comes with the standard
-Java API. <a href="/static/apidocs/helma/xmlrpc/XmlRpcClientLite.html">
-helma.xmlrpc.XmlRpcClientLite</a> extends this class to provide its own lightweight
-HTTP client implementation. Both classes offer the same functionality and interface.
-XmlRpcClientLite may be faster in many cases, but if you need full HTTP support
-(e.g. Proxies, Redirect etc), you may be better off with XmlRpcClient.
+<p>To quickly test your installation you can issue the following commands:</p>
+
+<pre>
+ java org.apache.xmlrpc.WebServer
+ java org.apache.xmlrpc.XmlRpcClient http://localhost:8080 echo test 123
+</pre>
+
+<p>This should write [test, 123], which is the parameter array you sent to the echo
+handler of the XML-RPC server.</p>
+ </section>
+ <section name="Asynchronous XML-RPC Calls">
+ <p>
+ Apache XML-RPC supports asynchronous XML-RPC calls through the
+ executeAsync() method in the XML-RPC client classes. This means that
+ the call will return immediately without a result and the actual
+ XML-RPC call will be executed in a separate thread.</p>
--->
+ <p>If the caller
+ is interested in the result of the remote call, or wants to be
+ notified of exceptions, it can pass an object implementing the
+ <a href="/xml-rpc/apidocs/org/apache/xmlrpc/AsyncCallback.html">org.apache.xmlrpc.AsyncCallback</a>
+ interface to the XML-RPC client class. This interface defines two
+ methods:</p>
+
+<pre> public void handleResult (Object result, URL url, String method);
+ public void handleError (Exception exception, URL url, String method);</pre>
+
+<p>Depending on the outcome of the call, one of these methods will be called.
+ </p>
+ </section>
+
+ </body>
+</document>
1.2 +9 -10 xml-rpc/xdocs/parser.xml
Index: parser.xml
===================================================================
RCS file: /home/cvs/xml-rpc/xdocs/parser.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- parser.xml 2001/10/30 16:09:05 1.1
+++ parser.xml 2001/10/31 21:35:13 1.2
@@ -9,21 +9,20 @@
<body>
<section name="XML Parsers">
<p>
+ Apache XML-RPC supports
+<a href="http://www.megginson.com/SAX/SAX1">SAX 1.0</a>
+and can therefore be used with any compliant XML parser. However,
+John Wilson's <a href="http://www.wilson.co.uk/xml/minml.htm">MinML</a> parser that
+comes with the library is so small and fast that we recommend sticking to it even
+if you already have another XML-Parser in your application. If you still want
+to use a different parser, have a look at the
+<a href="http://classic.helma.at/hannes/xmlrpc/#parser">old site</a>
+for instructions.
</p>
</section>
</body>
</document>
<!--
-
-Helma XML-RPC supports
-<a href="http://www.megginson.com/SAX/SAX1">SAX 1.0</a>
-and can therefore be used with any compliant XML parser. However,
-John Wilson's <a href="http://www.wilson.co.uk/xml/minml.htm">MinML</a> parser that
-comes with the library is so small and fast that we recommend sticking to it even
-if you already have another XML-Parser in your application. If you still want
-to use a different parser, have a look at the
-<a href="http://classic.helma.at/hannes/xmlrpc/#parser">old site</a>
-for instructions.
-->
1.2 +112 -5 xml-rpc/xdocs/server.xml
Index: server.xml
===================================================================
RCS file: /home/cvs/xml-rpc/xdocs/server.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- server.xml 2001/10/30 16:09:05 1.1
+++ server.xml 2001/10/31 21:35:13 1.2
@@ -7,18 +7,125 @@
</properties>
<body>
- <section name="Server">
+ <section name="Server-side XML-RPC">
<p>
+ On the server side, you can either embed the XML-RPC library into an existing
+server framework, or use the built-in special purpose HTTP server. Let's
+first look at how to register handler objects to tell an XML-RPC server how to
+map incoming requests to actual methods.
+ </p>
+ </section>
+ <section name="XML-RPC Handler Objects">
+ <p>
+ The <a href="/xml-rpc/apidocs/org/apache/xmlrpc/XmlRpcServer.html">
+org.apache.xmlrpc.XmlRpcServer</a> and <a href="/xml-rpc/apidocs/org/apache/xmlrpc/WebServer.html">
+org.apache.xmlrpc.WebServer</a> classes provide methods that let your register and
+unregister Java objects as XML-RPC handlers:
+
+<pre> addHandler (String name, Object handler);
+ removeHandler (String name);</pre>
+
+Depending on what kind of handler object you give to the server, it will do
+one of the following things:
+
+<ol>
+ <li>
+ If you pass the XmlRpcServer any Java object, the server will
+ try to resolve incoming calls via object introspection, i.e. by
+ looking for public methods in the handler object corresponding to
+ the method name and the parameter types of incoming requests.
+ The input parameters of incoming XML-RPC requests must match the argument types of the Java method
+ (see <a href="/xml-rpc/types.html">conversion table</a>), or otherwise the method
+ won't be found. The return value of the Java method must be supported
+ by XML-RPC.
+ </li>
+
+ <li>
+ If you pass the XmlRpcServer an object that implements interface
+ <a href="/xml-rpc/apidocs/org/apache/xmlrpc/XmlRpcHandler.html">
+ org.apache.xmlrpc.XmlRpcHandler</a> or
+ <a href="/xml-rpc/apidocs/org/apache/xmlrpc/AuthenticatedXmlRpcHandler.html">
+ org.apache.xmlrpc.AuthenticatedXmlRpcHandler</a> the execute() method
+ will be called for every incoming request. You are then in full control
+ of how to process the XML-RPC request, enabling you to perform input and output
+ parameter checks and conversion, special error handling etc.
+ </li>
+</ol>
+
+In both cases, incoming requests will be interpreted as
+<tt>handlerName.methodName</tt> with <tt>handlerName</tt> being the String
+that the handler has been registered with, and <tt>methodName</tt> being the
+name of the method to be invoked. You can work around this scheme by
+registering a handler with the name "$default". In this case you can
+drop the <tt>handlerName.</tt> part from the method name.
+ </p>
+ </section>
+ <section name="Using XML-RPC within a Servlet environment">
+ <p>
+ The XML-RPC library can be embedded into any Web server framework that supports
+reading HTTP POSTs from an InputStream. The typical code for processing an
+incoming XML-RPC request looks like this:</p>
+
+<pre> XmlRpcServer xmlrpc = new XmlRpcServer ();
+ xmlrpc.addHandler ("examples", new ExampleHandler ());
+ ...
+ byte[] result = xmlrpc.execute (request.getInputStream ());
+ response.setContentType ("text/xml");
+ response.setContentLength (result.length ());
+ OutputStream out = response.getOutputStream();
+ out.write (result);
+ out.flush ();</pre>
+
+<p>Note that the <tt>execute</tt> method does not throw any exception, since all
+errors are encoded into the XML result that will be sent back to the client.
+A full example servlet is included in the package.
+
+There is a sample XML-RPC Servlet included in the library. You can use it as a
+starting point for your own needs.
+
</p>
</section>
+ <section name="Using the Built-in HTTP Server">
+ <p>
+ The XML-RPC library comes with its own built-in HTTP server. This is not a general
+purpose web server, its only purpose is to handle XML-RPC requests.
+The HTTP server can be embedded in any Java application with a few
+simple lines:</p>
+
+<pre> WebServer webserver = new WebServer (port);
+ webserver.addHandler ("examples", someHandler);</pre>
+
+You can also start the web server from the command line by typing:
+
+<pre> java org.apache.xmlrpc.WebServer</pre>
+
+<p>You can specify the server port, but there's no way to manipulate RPC handlers in
+command line mode, so you'll either have to modify WebServer.java for your purposes
+or embed it into your own application. A special bonus when using the built in Web
+server is that you can set the IP addresses of clients from which to accept or
+deny requests. This is done via the following methods:</p>
+
+<pre> webserver.setParanoid (true);
+ // deny all clients
+ webserver.acceptClient ("192.168.0.*"); // allow local access
+ webserver.denyClient ("192.168.0.3"); // except for this one
+ ...
+ webserver.setParanoid (false); // disable client filter</pre>
+
+<p>If the client filter is activated, entries to the deny list always override those in
+the accept list. Thus, <tt>webserver.denyClient ("*.*.*.*")</tt> would
+completely disable the web server.
+
+Note that the XML-RPC client in Frontier 5 has its requests hard-coded to URI /RPC2.
+To work with these clients, you have to configure your server environment to respond
+to /RPC2. This should be fixed in a newer version.
+ </p>
+ </section>
</body>
</document>
<!--
-On the server side, you can either embed the XML-RPC library into an existing
-server framework, or use the built-in special purpose HTTP server. Let's
-first look at how to register handler objects to tell an XML-RPC server how to
-map incoming requests to actual methods.
+
-->
1.2 +15 -14 xml-rpc/xdocs/types.xml
Index: types.xml
===================================================================
RCS file: /home/cvs/xml-rpc/xdocs/types.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- types.xml 2001/10/30 16:09:05 1.1
+++ types.xml 2001/10/31 21:35:13 1.2
@@ -7,26 +7,19 @@
</properties>
<body>
- <section name="Types">
+ <section name="Type Mapping between XML-RPC and Java">
<p>
- </p>
- </section>
- </body>
-</document>
-
-<!--
-
-The following table explains how data types are converted between their XML-RPC
+ The following table explains how data types are converted between their XML-RPC
representation and Java.
-Note that the automatic invocation mechanism expects your classes to take the
-primitive data types as input parameters. If your class defines any other types
-as input parameters (including java.lang.Integer, long, float), that
+Note that the automatic invocation mechanism expects your classes to take the
+primitive data types as input parameters. If your class defines any other types
+as input parameters (including java.lang.Integer, long, float), that
method won't be usable from XML-RPC unless you write your own handler.
For return values, both the primitive types and their wrapper classes work fine.
-<table border cellpadding="5">
+<table border="1" cellpadding="5">
<tr>
<td><b>XML-RPC data type</b></td>
<td><b>Data Types generated by the Parser</b></td>
@@ -58,7 +51,7 @@
<td>java.util.Date</td>
</tr>
<tr>
-<td><struct> </td>
+<td><struct></td>
<td>java.util.Hashtable</td>
<td>java.util.Hashtable</td>
</tr>
@@ -73,5 +66,13 @@
<td>byte[ ]</td>
</tr>
</table>
+ </p>
+ </section>
+ </body>
+</document>
+
+<!--
+
+
-->
1.1 xml-rpc/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Apache XML-RPC</title>
<author email="hannes@helma.at">Hannes Wallnofer</author>
</properties>
<body>
<section name="About Apache XML-RPC">
<p>Apache XML-RPC is a Java implementation of <a href="http://www.xmlrpc.com">XML-RPC</a>,
a popular protocol that uses XML over HTTP to implement remote procedure calls.
</p>
<p>
Apache XML-RPC was previously known as Helma XML-RPC. If you have code using the
Helma library, all you should have to do is change the import
statements in your code from helma.xmlrpc.* to org.apache.xmlrpc.*.
</p>
</section>
</body>
</document>