Developer's Guide

SOAP

Beginning with version 0.8, eXist-db provides a SOAP interface as an alternative to XML-RPC. Programming with SOAP is slightly more convenient than XML-RPC. While you have to write XML-RPC method calls by hand, most SOAP tools will automatically create the low-level code from a given WSDL service description. Also fewer methods are needed to exploit the same functionality. On the other hand, SOAP toolkits tend to be complex.

eXist-db uses the Axis SOAP toolkit from Apache, which runs as a servlet. The Tomcat webserver shipped with eXist has been configured to start Axis automatically, and will listen on port 8080: http://localhost:8080/exist/services. Note however that SOAP is not available in the stand-alone server.

The interface has been tested using various clients, including Perl (SOAP::Lite) and the Microsoft .NET framework. The client stubs needed to access the SOAP interface from Java have been automatically generated by Axis and are included in the distribution.

eXist-db provides two web services: one that contains methods to query the server and retrieve documents, and a second for storing and removing documents and collections. The first will by default listen on:

http://localhost:8080/exist/services/Query

while the second is available on:

http://localhost:8080/exist/services/Admin

Both services are described in the Java docs regarding their interfaces. Visit: org.exist.soap.Query and org.exist.soap.Admin for more information.

The following SOAP example (available at: samples/org/exist/examples/soap/GetDocument.java) demonstrates how to retrieve a document from the database:

package org.exist.examples.soap; import org.exist.soap.Query; import org.exist.soap.QueryService; import org.exist.soap.QueryServiceLocator; public class GetDocument { public static void main( String[] args ) throws Exception { QueryService service = new QueryServiceLocator(); Query query = service.getQuery(); String session = query.connect("guest", "guest"); byte[] data = query.getResourceData(session, "/db/shakespeare/plays/hamlet.xml", true, false, false); System.out.println(new String(data, "UTF-8")); query.disconnect(session); } }
Retrieving a document (SOAP)

In this example, the Query client stub class has been automatically generated by the WSDL service description, and has methods for each of the operations defined in WSDL. You will find the web service description file query.wsdl in directory src/org/exist/soap. You may also get the WSDL directly from the server by pointing your web browser to http://localhost:8080/exist/services/Query?WSDL.

To use the services provided, the client first has to establish a connection with the database. This is done by calling connect() with a valid user id and password. connect() returns a session id, which can then be passed to any subsequent method calls.

To retrieve a resource we simply call Query.getResource(). And to release the current session, the method Query.disconnect() is called. Otherwise the session will remain valid for at least 60 minutes.