dbXML XML-RPC Interface Users Guide

Inspirational Technology
Kimbro Staken's views on Mac OS X, XML databases, and other inspirational technologies.

Home

dbXML XML-RPC Interface Users Guide

Version: 0.5

Author: Kimbro Staken

Basic operations

The dbXML XML-RPC interface provides basic access to dbXML to any language that has an XML-RPC implementation. For more information on XML-RPC and a list of implementations see xmlrpc.com. The dbXML interface uses the Helma XML-RPC library on the server but any client implementation should be able to call methods on the server.

Operation is pretty simple and in this guide I'll just provide a couple of examples. As part of the distribution there is a test suite that provides examples for all methods if you want to see how one that isn't covered here is used. All the examples are in Java using Helma XML-RPC, but it shouldn't be too difficult to convert the examples to other client libraries.

Basic Program Structure

Here is about the simplest program that you can write to access dbXML via XML-RPC. While the program is simple it does show all the basic mechanisms that you need to know to use the API.

      import java.util.*;
      import helma.xmlrpc.*;
      
      public class Client {
         public static void main(String[] args) throws Exception {
            XmlRpcClient  client = new XmlRpcClient("http://localhost:4080");
            Vector params = new Vector();
            params.addElement("/db/root");
            Integer result = (Integer) client.execute("db.getDocumentCount", params);   
            System.out.println(result);
         }
      }

To use the API all you really need to do is create an XmlRpcClient that connects to dbXML via HTTP. Since the default HTTP port for dbXML is 4080 that is what we use here.

        XmlRpcClient  client = new XmlRpcClient("http://localhost:4080");

Once we have our client we need to create a Vector that contains all the parameters for the method. In this case we're calling the method db.getDocumentCount that only takes one parameter. This is the path of the collection that we want to count the documents in. Parameters in XML-RPC must be added to the Vector in the order that they are listed in the method signature. In this case we only have one, so there is no problem, however you need to be aware of this to call the other methods in the API.

       Vector params = new Vector();
       params.addElement("/db/root");

Once you've created the Vector of parameters, invoking the method is simply calling client.execute and providing it the name of the method you want to call and the parameter Vector that you just created. All methods in the API are part of the db package, so you must prefix the method name with "db.".

The return type will vary depending on the return type of the method. In this case the method returns an int so our XML-RPC library maps it into an Integer object. Other languages will have different mappings.

      Integer result = (Integer) client.execute("db.getDocumentCount", params);

Now that we have the result we can just print it out, and that's all there is to it.

      System.out.println(result);

Accessing the other methods is pretty similar and I'll provide a couple other partial examples.

Inserting a document

This example will insert a document into the collection /db/root under the id "test". The XML document is passed as a simple string.

      Vector params = new Vector();
      params.addElement("/db/root");
      params.addElement("test");
      params.addElement("<doc>value</doc>");
      
      return (String) client.execute("db.insertDocument", params);

Retrieving a document

To retrieve the document we inserted in the previous example we can do something like this. The document is returned as a string in UTF-8 encoding.

      Vector params = new Vector();
      params.addElement("/db/root");
      params.addElement("test");
      
      String document = (String) client.execute("db.getDocument", params);

Querying a collection

Querying the database is probably the most complex operation. This example just queries the database looking for the document we inserted earlier. The valid query types are "XPath" and "XUpdate". The final parameter where we just insert an empty Hashtable is a namespace map to allow namespace restricted queries.

      Vector params = new Vector();
      params.addElement("/db/root");
      params.addElement("XPath");
      params.addElement("/test");
      params.addElement(new Hashtable());      
      
      String result = (String) client.execute("db.queryCollection", params);
      System.out.println(result);

Executing this would result in output that looks something like this.

      <result count="1"><doc xmlns:src="http://www.dbxml.org/Query" src:col="/db/root" src:key="test">value</doc></result>

As you can see dbXML adds some extra meta-data to the query result to tell you how many results there are (count="1") and to make it easier to map back to the original document (xmlns:src="http://www.dbxml.org/Query" src:col="/db/root" src:key="test"). The meta-data for mapping back to the original document is more valuable when your query result comes from deep within the document.

API Documentation

The API documentation is available as part of your distribution or online

The documentation is provided in Javadoc form. To convert the Java types into the appropriate XML-RPC type refer to the Helma XML-RPC type mapping documentation