SOAP Interface Developer's Guide

Introduction

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.

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.

Web services

eXist-db provides two web services: one that contains methods to query the server and retrieve documents:

• A service to query the server and retrieve documents. This will listen on:

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

• A service for storing and removing documents and collections. This will listen on:

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

Both services are described in the Java docs regarding their interfaces.

Example

The following example demonstrates how to retrieve a document from the database using SOAP:

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);
    }
}

The Query client stub class has been automatically generated by the WSDL service description. It has methods for each of the operations defined in the WSDL. You will find the web service description file query.wsdl in directory src/org/exist/soap.

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 simply call Query.getResource().

To release the current session, the method Query.disconnect() is called. Otherwise the session will remain valid for at least 60 minutes.