<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id: devguide_soap.xml 17299 2012-10-10 23:47:33Z joewiz $ --><book><bookinfo><productname>eXist-db – Open Source Native XML Database</productname><title>Developer's Guide</title><date>September 2009</date><author><firstname>Wolfgang M.</firstname><surname>Meier</surname><affiliation><address format="linespecific"><email>wolfgang at exist-db.org</email></address></affiliation></author></bookinfo><chapter id="ch01"><title>Developer's Guide</title><section><title>SOAP</title><para>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.</para><para>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: <filename>http://localhost:8080/exist/services</filename>.
                Note however that SOAP is not available in the stand-alone server.</para><para>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.</para><para>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:</para><synopsis format="linespecific">http://localhost:8080/exist/services/Query</synopsis><para>while the second is available on:</para><synopsis format="linespecific">http://localhost:8080/exist/services/Admin</synopsis><para>Both services are described in the Java docs regarding their interfaces. Visit:
                    <ulink url="api/org/exist/soap/Query.html">org.exist.soap.Query</ulink> and
                    <ulink url="api/org/exist/soap/Admin.html">org.exist.soap.Admin</ulink> for more
                information.</para><para>The following SOAP example (available at:
                    <filename>samples/org/exist/examples/soap/GetDocument.java</filename>)
                demonstrates how to retrieve a document from the database:</para><example><title>Retrieving a document (SOAP)</title><programlisting format="linespecific" language="java">
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);
    }
}
        </programlisting></example><para>In this example, the <classname>Query</classname> 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
                    <filename moreinfo="none">query.wsdl</filename> in directory <filename moreinfo="none">src/org/exist/soap</filename>. You may also get the WSDL
                directly from the server by pointing your web browser to <ulink url="http://localhost:8080/exist/services/Query?WSDL">
                    http://localhost:8080/exist/services/Query?WSDL</ulink>.</para><para>To use the services provided, the client first has to establish a connection with
                the database. This is done by calling <methodname>connect()</methodname> with a
                valid user id and password. <methodname>connect()</methodname> returns a session id,
                which can then be passed to any subsequent method calls.</para><para>To retrieve a resource we simply call
                <methodname>Query.getResource()</methodname>. And to release the current session,
                the method <methodname>Query.disconnect()</methodname> is called. Otherwise the
                session will remain valid for at least 60 minutes.</para></section></chapter></book>