1. Introduction

The eXist-restlet subproject provides an integration with the Restlet project. It provides a simple way to integrate an embedded version of eXist into a web application.

The handling of services, web interfaces, etc. is all handled via regular Restlet code and there is a special "exist" protocol for talking to the internal database as if it is its own service via the Client restlet API.

2. Examples

2.1 Starting the Database

   XMLDB xmldb = new XMLDB(new File("conf.xml"));
   xmldb.start();

2.2 A Web Component for eXist Requests

public class WebComponent extends Component {
   
   public WebComponent(String hostname,String ipAddress, int port) {
      
      // ------------------
      // Add the connectors
      // ------------------
      getServers().add(Protocol.HTTP, ipAddress, port);
      getClients().add(Protocol.FILE);
      getClients().add(XMLDBResource.EXIST);
      
      // ---------------
      // Add the virtual host
      // ---------------
      VirtualHost host = new VirtualHost(getContext());
      host.setHostDomain(hostname);
      host.setHostPort("80|" + Integer.toString(port));
      
      host.attach(new XMLDBApplication(getContext()));
      
      getHosts().add(host);
      
   }
   
}

2.3 Getting a Document

   Client client = new Client(Protocol.valueOf("exist"));
   Response response = client.get("exist:///foo.xml");

2.4 Storing a Document

   Client client = new Client(Protocol.valueOf("exist"));
   Response response =client.put("exist:///foo.xml",new StringRepresentation("<foo/>",MediaType.APPLICATION_XML));

2.5 Querying

   Client client = new Client(Protocol.valueOf("exist"));
   Response response = client.post("exist:///",new StringRepresentation("//foo",MediaType.valueOf("application/xquery"))

3. Building

The restlet integration relies upon the embedded version of eXist. You can build the embedded version by the following instructions

1. Checkout the trunk/eXist and trunk/embedded directories of eXist from eXist's subversion
2. Build eXist.
3. Execute the import-exist ant target.
4. Build the embedded project via the jar ant target.

Once you have the embedded version of eXist, you can build the restlet project by:

1. Checkout the trunk/restlet from this project's subversion.
2. Execute the import-embedded ant target. You'll probably need to set the embedded.dir parameter to directory of your embedded version of eXist.
3. Build the project with the jar ant target.

All of these projects (eXist, embedded eXist, and this project) are also Netbeans projects.

4. API

The Restlet integration makes using eXist as an embedded database very simple. The minimum you need to do is start the database and then access eXist with the "exist" protocol via the Client class.

You can only start the database engine per process which is accomplished by:

   XMLDB xmldb = new XMLDB(new File("conf.xml"));
   xmldb.start();

The file passed into the constructor is the path to the eXist configuration file (an XML document). This is a regular eXist configuration. All the features of eXist with the exception of the HTTP services are available via this configuration.

Once you have the database started, you can access exist via REST methods:

• A PUT request stores a document into the database.
• A GET request retrieves a document representation.
• A POST request submits an XQuery to the database.
• A DELETE request removes a document or collection from the database.
• A HEAD request returns the modification time of a document.

The embedded eXist database is treated like an HTTP protocol server in that requests are made to resources. Internally, these request are handled locally by interactions with the database. Externally, the Restlet Client class is used to interact with the embedded database. This allows the programmer to treat eXist as any other REST-oriented server even tough the database runs locally.

4.1 PUT

A PUT request stores a document. Any media type that is considered XML (i.e. text/xml, application/xml, and those with the "+xml" suffix) are stored as XML documents. Otherwise, the document is stored as a binary resource.

The media type used to store the document is associated with the resource in eXist. This media type is used for future GET requests against the resource.

If the collection reference in the resource path does not exist, that collection path is created.

For example:

   Client client = new Client(Protocol.valueOf("exist"));
   Response response = client.put("exist:///foo.xml",StringRepresentation("<foo/>",MediaType.APPLICATION_XML));
   if (response.getStatus().isSuccess()) {
     ...
   }

4.2 GET

A GET request retrieves a resource from eXist. If it exists, a Response is formulated with a representation of the resource (often a output stream from the database).

Currently, a GET request on a collection is not supported.

For example, to get an XML resource:

   Client client = new Client(Protocol.valueOf("exist"));
   Response response = client.get("exist:///foo.xml");
   if (response.getStatus().isSuccess()) {
     ...
   }

4.3 POST

All POST requests are interpreted as queries. If the media type is "application/xquery", the entity of the post is interpreted as an XQuery. If the media type is an XML media type, then the document is interpreted via the following rules:

1. If the document element is {http://exist.sourceforge.net/NS/exist}query, then

same semantics as eXist's REST interface are applied.

2. If the document element is in the XUpdate (http://www.xmldb.org/xupdate) namespace,

XUpdate process is performed with the same semantics as eXist's REST interface.

3. Otherwise, the serialized document is compiled as an XQuery.

The results are serialized and returned as an XML document with the application/xml media type.

For example:

   Client client = new Client(Protocol.valueOf("exist"));
   Response response = client.post("exist:///",new StringRepresentation("<docs>{/foo}</docs>,MediaType.valueOf("application/xquery")));
   if (response.getStatus().isSuccess()) {
     ...
   }

4.4 DELETE

A DELETE request on a collection or document resource deletes the resource.

For example:

   Client client = new Client(Protocol.valueOf("exist"));
   Response response = client.delete("exist:///foo.xml");
   if (response.getStatus().isSuccess()) {
     ...
   }

4.5 HEAD

A HEAD request works very similar to a GET request exception that no entity body is returned. The last-modified header is set as appropriate and the media type is also returned.

4.6 Other Class

• The XMLDBApplication proxies the eXist as resources served by the Restlet engine.
• The XMLDBFinder finds resources in the eXist database.
• The XMLDBResource represents a resource stored in the eXist database.
• The WebComponent is a component that wraps the Application and can be used to instantiate a server bound to a host address.