ws-xmlrpc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jvan...@apache.org
Subject cvs commit: xml-rpc/xdocs async.xml builtin.xml client.xml docs.xml handler.xml parser.xml server.xml servlet.xml sync.xml types.xml
Date Tue, 30 Oct 2001 16:09:06 GMT
jvanzyl     01/10/30 08:09:06

  Added:       xdocs    async.xml builtin.xml client.xml docs.xml
                        handler.xml parser.xml server.xml servlet.xml
                        sync.xml types.xml
  Log:
  - set of minimal documentation just to get hannes going.
  
  Revision  Changes    Path
  1.1                  xml-rpc/xdocs/async.xml
  
  Index: async.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Asynchronous XML-RPC Calls</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Asynchronous XML-RPC Calls">
        <p>
          Helma now supports asynchronous XML-RPC calls. Have a look 
          at <a href="http://xmlrpc.helma.org/static/apidocs/helma/xmlrpc/XmlRpcClient.html">
          helma.xmlrpc.XmlRpcClient</a> 
          and <a href="http://xmlrpc.helma.org/static/apidocs/helma/xmlrpc/AsyncCallback.html">
          helma.xmlrpc.AsyncCallback</a> for information on how to implement an asynchronous
client.
        </p>
      </section>
    </body>
  </document>
  
  
  
  1.1                  xml-rpc/xdocs/builtin.xml
  
  Index: builtin.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Built in Http Server</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Built in Http Server">
        <p>
        </p>
      </section>
    </body>
  </document>
  
  <!--
  
  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:
  
  <small><tt>&nbsp; WebServer webserver = new WebServer (port);</tt>
  <tt>&nbsp; webserver.addHandler ("examples", someHandler);</tt></small>
  
  You can also start the web server from the command line by typing:
  
  <small><tt>&nbsp; java helma.xmlrpc.WebServer</tt></small>
  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:
  
  <small><tt>&nbsp; webserver.setParanoid (true);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  
  // deny all clients</tt>
  
  <tt>&nbsp; webserver.acceptClient ("192.168.0.*"); // allow LAN access</tt>
  
  <tt>&nbsp; webserver.denyClient ("192.168.0.3");&nbsp; // except for
  
  this one</tt>
  
  <tt>&nbsp; ...</tt>
  
  <tt>&nbsp; webserver.setParanoid (false);&nbsp; // disable client filter</tt></small>
  
  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.
  
  -->
  
  
  
  1.1                  xml-rpc/xdocs/client.xml
  
  Index: client.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Client Classes</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Client Classes">
        <p>
        </p>
      </section>
    </body>
  </document>
  
  <!--
  
  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.
  
  -->
  
  
  
  1.1                  xml-rpc/xdocs/docs.xml
  
  Index: docs.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Documentation</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Documentation">
        <p>
        </p>
      </section>
    </body>
  </document>
  
  <!--
  
  This section of the site provides information on how to use the Helma XML-RPC library for

  Java. Also see the 
  <a href="http://xmlrpc.helma.org/static/apidocs/helma/xmlrpc/package-summary.html">
  API Documentation</a> for the helma.xmlrpc package.
  
  -->
  
  
  
  1.1                  xml-rpc/xdocs/handler.xml
  
  Index: handler.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Handlers</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Handlers">
        <p>
        </p>
      </section>
    </body>
  </document>
  
  <!--
  
  The classes <a href="/static/apidocs/helma/xmlrpc/XmlRpcServer.html">
  helma.xmlrpc.XmlRpcServer</a> and <a href="/static/apidocs/helma/xmlrpc/WebServer.html">
  helma.xmlrpc.WebServer</a> provide two methods that let your register and 
  unregister Java objects as XML-RPC handlers:
  
  <tt>addHandler (String name, Object handler);</tt>
  <tt>removeHandler (String name);</tt>
  
  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 look up the corresponding method by looking at 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="/docs/types/">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="/static/apidocs/helma/xmlrpc/XmlRpcHandler.html">
      helma.xmlrpc.XmlRpcHandler</a> or 
      <a href="/static/apidocs/helma/xmlrpc/AuthenticatedXmlRpcHandler.html">
      helma.xmlrpc.AuthenticatedXmlRpcHandler</a> you'll be in full control 
      of how the XML-RPC request is processed, including input and output 
      parameter conversion, special error handling etc. Note that the XmlRpcClient 
      in this library also implements XmlRpcHandler, so it can act as an XML-RPC 
      proxy. This is very useful for applets that can only connect to the server 
      they came from. <a href="http://helma.at/hannes/xmlrpc_test.html">
      (Click here for a demo.)</a>
    </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 which case you can 
  drop the <tt>handlerName.</tt> part from the method name.
  
  -->
  
  
  
  1.1                  xml-rpc/xdocs/parser.xml
  
  Index: parser.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>XML Parsers</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="XML Parsers">
        <p>
        </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.1                  xml-rpc/xdocs/server.xml
  
  Index: server.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Server</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Server">
        <p>
        </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.1                  xml-rpc/xdocs/servlet.xml
  
  Index: servlet.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Servlet</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Servlet">
        <p>
        </p>
      </section>
    </body>
  </document>
  
  <!--
  
  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:
  
  <small><tt>&nbsp;XmlRpcServer xmlrpc = new XmlRpcServer ();</tt>
  <tt>&nbsp;xmlrpc.addHandler ("examples", new ExampleHandler ());</tt>
  <tt>&nbsp;...</tt>
  <tt>&nbsp;byte[] result = xmlrpc.execute (request.getInputStream ());</tt>
  <tt>&nbsp;response.setContentType ("text/xml");</tt>
  <tt>&nbsp;response.setContentLength (result.length ());</tt>
  <tt>&nbsp;OutputStream out = response.getOutputStream();</tt>
  <tt>&nbsp;out.write (result);</tt>
  <tt>&nbsp;out.flush ();</tt></small>
  
  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.
  
  -->
  
  
  
  1.1                  xml-rpc/xdocs/sync.xml
  
  Index: sync.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Sync</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Sync">
        <p>
        </p>
      </section>
    </body>
  </document>
  
  <!--
  
  Using the XML-RPC libray on the client side is quite straightforward. 
  Here is some sample code:
  
  <source>
  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);
  </source>
  
  Note that execute can throw <tt>XmlRpcException</tt> and <tt>IOException</tt>,
  which must be caught or declared by your code.
  
  To quickly test your installation you can issue the following commands:
  
  <source>
  java helma.xmlrpc.WebServer
  java helma.xmlrpc.XmlRpcClient http://localhost:8080 echo test 123
  </source>
  
  This should write [test, 123], which is the parameter array you sent to the echo 
  handler of the XML-RPC server.
  
  -->
  
  
  
  1.1                  xml-rpc/xdocs/types.xml
  
  Index: types.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Types</title>
      <author email="hannes@helma.at">Hannes Wallnofer</author>
    </properties>
  
    <body>
      <section name="Types">
        <p>
        </p>
      </section>
    </body>
  </document>
  
  <!--
  
  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 
  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">
  <tr>
  <td><b>XML-RPC data type</b></td>
  <td><b>Data Types generated by the Parser</b></td>
  <td><b>Types expected by the Invoker as input parameters of RPC handlers</b></td>
  </tr>
  <tr>
  <td>&lt;i4> or &lt;int></td>
  <td>java.lang.Integer</td>
  <td><font color="#000000">int</font></td>
  </tr>
  <tr>
  <td>&lt;boolean></td>
  <td>java.lang.Boolean</td>
  <td><font color="#000000">boolean</font></td>
  </tr>
  <tr>
  <td>&lt;string></td>
  <td>java.lang.String</td>
  <td>java.lang.String</td>
  </tr>
  <tr>
  <td>&lt;double></td>
  <td>java.lang.Double</td>
  <td><font color="#000000">double</font></td>
  </tr>
  <tr>
  <td>&lt;dateTime.iso8601></td>
  <td>java.util.Date</td>
  <td>java.util.Date</td>
  </tr>
  <tr>
  <td>&lt;struct>&nbsp;</td>
  <td>java.util.Hashtable</td>
  <td>java.util.Hashtable</td>
  </tr>
  <tr>
  <td>&lt;array></td>
  <td>java.util.Vector</td>
  <td>java.util.Vector</td>
  </tr>
  <tr>
  <td>&lt;base64></td>
  <td>byte[ ]</td>
  <td>byte[ ]</td>
  </tr>
  </table>
  
  -->
  
  
  

Mime
View raw message