<?xml version="1.0" encoding="UTF-8"?>

<!--
  - Licensed to the Apache Software Foundation (ASF) under one or more
  - contributor license agreements.  See the NOTICE file distributed with
  - this work for additional information regarding copyright ownership.
  - The ASF licenses this file to You under the Apache License, Version 2.0
  - (the "License"); you may not use this file except in compliance with
  - the License.  You may obtain a copy of the License at
  -
  -     http://www.apache.org/licenses/LICENSE-2.0
  -
  - Unless required by applicable law or agreed to in writing, software
  - distributed under the License is distributed on an "AS IS" BASIS,
  - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  - See the License for the specific language governing permissions and
  - limitations under the License.
  -
  - $Id$
  -->

<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">

<!--
  - Version: $Revision$ $Date$
  - Author: Kimbro Staken (kstaken@xmldatabases.org)
  -->

<document>
  <header>
    <title>Xindice 1.1 Developer Guide</title>
    <version>$Revision$</version>
    <authors>
      <person id="ks" name="Kimbro Staken" email=""/>
      <person id="dv" name="Dave Viner" email="dviner@apache.org" />
    </authors>
  </header>
  <body>
    <note>
      If you notice incorrectness in this documentation, please
      <link href="../mail.html">notify</link> Xindice community. Your feedback
      will help create better documentation.
    </note>
    <section>
      <title>Introduction to Programming Xindice</title>
      <section>
        <title>Accessing the Server</title>
        <p>
          The Xindice server can be accessed either programmatically through
          the server's APIs, or from the command line using the provided
          command line tools. This document covers programmatic access,
          for more information on using the command line interface please
          refer to the <link href="guide-user.html">Xindice Users Guide</link>.
        </p>
        <section>
          <title>API's</title>
          <p>
            Xindice currently offers three layers of APIs that can be used to
            develop applications.
          </p>
          <ul>
            <li>
               <strong>XML:DB XML Database API</strong> used to develop
               Xindice applications in Java. This is the primary API used to
               develop applications and it will be given the most coverage in
               this manual. Xindice provides two implementations of the XML:DB
               API. One is built on top of the Xindice XML-RPC API, and another
               embeds Xindice within the same JVM. Xindice currently implements
               the May 07, 2001 draft of the XML:DB API. This API will change
               slightly in the future to track the development of the XML:DB API.
            </li>
            <li>
               <strong>Xindice XML-RPC API</strong> used when accessing Xindice
               from a language other then Java. The XML-RPC API is built on top
               of the Core Server API. XML-RPC implementation is provided by
               Apache Web Services Project.
            </li>
            <li>
               Core Server API is the internal Java API of the core
               database engine. This API is used to build the XML-RPC API and
               embedded XML:DB API. This is the lowest level API and is only
               available to software running in the same Java VM as the
               database engine itself.
            </li>
          </ul>
        </section>
        <p>
          The most common API for end user applications is the XML:DB XML
          Database API that was developed by the
          <link href="http://xmldb-org.sourceforge.net/">XML:DB Initiative</link>.
          This API is a vendor neutral API intended to make it possible to build
          applications that will work with more then one XML database
          without too much difficulty. This is similar to the capabilities
          provided by JDBC for relational databases. More information about this
          API can be found on the XML:DB Initiative web site,
          <link href="http://xmldb-org.sourceforge.net/">http://xmldb-org.sourceforge.net</link>. Most
          programming examples in this manual will use the XML:DB API. The
          Xindice implementation of the API is a Core Level 1 implementation.
        </p>
        <p>
          The Xindice server also exposes a XML-RPC API that is used to
          implement the XML:DB API. The XML-RPC API will mainly be of
          interest to those who want to access Xindice from a language other
          then Java. Any language that supports a XML-RPC should be
          able to utilize the services of the Xindice server via the XML-RPC
          API. This document does not cover development with the XML-RPC API
          as the XML:DB API is the preferred mechanism for developing Xindice
          applications. If you are developing applications in Java you can
          safely ignore the existence of this API. The XML-RPC API will be
          covered in a seperate document to be written at a later time.
        </p>
        <p>
          The final API for Xindice is the Core Server API.
        </p>
      </section>
      <section>
        <title>Introducing the XML:DB XML Database API</title>
        <p>
          XML:DB API is being developed by the
          <link href="http://xmldb-org.sourceforge.net/">XML:DB Initiative</link> to
          facilitate the development of applications that function with
          minimal change on more then one XML database. This is roughly
          equivalent to the functionality provided by JDBC or ODBC for
          providing access to relational databases. Xindice provides an
          implementation of the XML:DB API that also serves as the primary
          programming API for Xindice.
        </p>
        <p>
          The XML:DB API is based around the concept of collections that store
          resources. A resource can be an XML Document, a binary blob or
          some type that is not currently defined. Collections can be arranged
          in a hierarchical fashion. This makes the architecture very similar
          to that of a typical Windows or UNIX file system. What is different
          however, is that collections also expose services that allow you to
          do things such as query XML documents using XPath or update resources in a
          transactionally secure manner.
        </p>
        <p>
          The XML:DB API defines several levels of interoperability called
          Core Levels in XML:DB terminology. The Xindice implementation of the
          API is a complete Core Level 1 implementation plus implementations of
          some of the optional services.
        </p>
        <p>
          Required Core 1 services supported by Xindice include.
        </p>
        <ul>
          <li>
            <strong>XPathQueryService</strong> - Enables execution of XPath
            queries against the database.
          </li>
        </ul>
        <p>
          Optional Core 1 services supported by Xindice include.
        </p>
        <ul>
          <li>
            <strong>XUpdateQueryService</strong> - Enables execution of XUpdate
            queries against the database.
          </li>
          <li>
            <strong>CollectionManagementService</strong> - Provides basic
            facilities to create and remove collections.
          </li>
        </ul>
        <p>
          In addition to Core Level 1 support the Xindice implementation also
          supports a few added services that are specific to Xindice. These
          services exist because the functionality is necessary to fully
          utilize all the capabilities provided by Xindice. However, they are
          proprietary to Xindice and will not function unchanged on other XML
          databases.
        </p>
        <p>
          The following services are currently provided by Xindice and are not
          part of the common XML:DB API.
        </p>
        <ul>
          <li>
            <strong>DatabaseInstanceManager</strong> - Provides the ability to
            control the operation of the server programatically.
          </li>
          <li>
            <strong>CollectionManager</strong> - Provides the ability to create
            and configure collection instances within the server. This is a
            much more functional version of CollectionManagementService
            that will only work with Xindice.
          </li>
        </ul>
        <p>
          While this guide aims to provide some useful examples and to guide
          you in the process of getting to know how to program Xindice it is
          also useful to know that there is a good source of example code within
          the server it self. The Xindice command line tools are built 100% on
          the XML:DB API and provide a pretty comprehensive set of examples in
          how to use the API. This is especially true when it comes to the Xindice
          specific services that are included with the server. The source code
          for all the command line tools can be found in
          <code>xindice/java/src/org/apache/xindice/tools/command</code>.
        </p>
      </section>
      <section>
        <title>Setting up Your Build Environment</title>
        <p>
          Before you can build applications for Xindice you need to make sure you
          have your build environment properly setup. This mainly consists of
          making sure that you have the proper VM version and a properly
          configured <code>CLASSPATH</code>.
        </p>
        <p>
          To build applications for Xindice you can use JDK 1.3 or 1.4. JDK 1.2
          and below will not work. If you have more than one Java VM installed
          make sure that your <code>JAVA_HOME</code> environment variable and
          <code>PATH</code> environment variable both include the correct path.
        </p>
        <p>
          Once you have your Java VM properly configured you need to add a few
          jar files to your <code>CLASSPATH</code>. The following list of
          jars are required and should be made available on your
          <code>CLASSPATH</code>. All required jars can be found in
          <code>xindice/java/lib</code>
        </p>
        <ul>
          <li>
            <strong>xindice.jar</strong> - contains the main Xindice classes
            that are used by the client API.
          </li>
          <li>
             <strong>xmldb-common.jar</strong>, <strong>xmldb-api.jar</strong>,
             <strong>xmldb-api-sdk.jar</strong>, <strong>xmldb-xupdate.jar</strong>
             - contain implementations of the XML:DB API and XUpdate API.
          </li>
          <li>
             <strong>xml-apis.jar</strong> - contains Java XML APIs.
          </li>
          <li>
             <strong>xerces.jar</strong> - contains the Xerces XML parser.
          </li>
          <li>
             <strong>xalan.jar</strong> - contains the Xalan XSLT engine.
          </li>
          <li>
             <strong>commons-logging.jar</strong> - contains the Jakarta Commons
             Logging package.
          </li>
        </ul>
      </section>
      <section>
        <title>Preparing the Server For the Examples</title>
        <p>
          Before we get to some example code, we need to do a little work to setup the
          server. Don't worry nothing hard.
        </p>
        <p>
          First we need to make sure the addressbook collection exists. If you followed
          the install instructions completely you should have already created this,
          but if not you should do so now. To find out if the collection exists you
          can run:
        </p>
        <source>  xindice lc -c /db  </source>
        <p>
          If you don't see 'addressbook' listed in the result then you need to create
          the collection. To create it just run:
        </p>
        <source>  xindice ac -c /db -n addressbook  </source>
        <p>
          Now that we have the collection, we can add a few example documents
          so that we have something to play with. You can find the examples in your
          Xindice installation in the directory
          <code>java/examples/guide/xml</code>. Run these commands to add
          the documents.
        </p>
        <source>
  cd $XINDICE_HOME/java/examples/guide/xml
  xindice ad -c /db/addressbook -f address1.xml -n address1
  xindice ad -c /db/addressbook -f address2.xml -n address2
        </source>
        <p>
          If you're on Windows you'll need to adjust the path in the cd command
          for your platform. Most of the examples in the manual will be written for
          UNIX but will work fine in Windows if you just replace / with \ and
          $XINDICE_HOME with %XINDICE_HOME%.
        </p>
        <p>
          That wasn't so bad and now we're set to look at some example code.
        </p>
      </section>
      <section>
        <title>Diving in With an Example Program</title>
        <section>
          <title>Simple XML:DB Example Program</title>
          <p>
            This example simply executes an XPath query against a
            collection, retrieves the results as text and prints them out.
          </p>
          <p>
            You can find the source code for this example in
            Xindice/java/examples/guide/src/org/apache/xindice/examples/Example1.java
          </p>
          <source><![CDATA[
package org.apache.xindice.examples;

import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

public class Example1 {

public static void main(String[] args) throws Exception {
  Collection col = null;
  try {
    String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
    Class c = Class.forName(driver);

    Database database = (Database) c.newInstance();
    DatabaseManager.registerDatabase(database);

    String uri = "xmldb:xindice:///db/addressbook";
    col = DatabaseManager.getCollection(uri);

    String xpath = "//person[fname='John']";
    XPathQueryService service =
      (XPathQueryService) col.getService("XPathQueryService", "1.0");
    ResourceSet resultSet = service.query(xpath);
    ResourceIterator results = resultSet.getIterator();
    while (results.hasMoreResources()) {
      Resource res = results.nextResource();
      System.out.println((String) res.getContent());
    }
  } catch (XMLDBException e) {
    System.err.println("XML:DB Exception occured " + e.errorCode);
  } finally {
    if (col != null) {
      col.close();
    }
  }
}

}
          ]]></source>
        </section>
        <p>
          Before diving into the gory detail of what this program is doing, let's
          run it and see what we get back.
        </p>
        <p>
          If you have a binary build of Xindice the examples are already built
          and you can run this example by typing.
        </p>
        <source>
  cd $XINDICE_HOME/java/examples/guide
  ./run org.apache.xindice.examples.Example1
        </source>
        <p>
          If all goes well, you should see a result that looks something like this.
        </p>
        <source><![CDATA[<?xml version="1.0"?>
<person xmlns:src="http://xml.apache.org/xindice/Query"
        src:col="/db/addressbook" src:key="address1">
  <fname>John</fname>
  <lname>Smith</lname>
  <phone type="work">563-456-7890</phone>
  <phone type="home">534-567-8901</phone>
  <email type="home">jsmith@somemail.com</email>
  <email type="work">john@lovesushi.com</email>
  <address type="home">34 S. Colon St.</address>
  <address type="work">9967 W. Shrimp Ave.</address>
</person>
        ]]></source>
        <p>
          Now that we've seen the result, let's dive in and look at the code in
          detail. While this isn't the simplest possible example program to start
          with it does a nice job of showing all the basic techniques used when
          building applications with the XML:DB API.
        </p>
        <p>
          To begin the program imports several XML:DB packages.
        </p>
        <source>
  import org.xmldb.api.base.*;
  import org.xmldb.api.modules.*;
  import org.xmldb.api.*;
        </source>
        <p>
          These import the basic classes required by the API.
          <code>import org.xmldb.api.base.*;</code> is the base API module
          and is required for all XML:DB applications.
          <code>import org.xmldb.api.*;</code> imports the all
          important <code>DatabaseManager</code> class which is the
          entry point into the API.
          <code>import org.xmldb.api.modules.*;</code> brings in the
          optional modules defined for the API. In this case the module we're
          interested in is <code>XPathQueryService</code>.
        </p>
        <p>
          Before we can use the API we need to create and register the
          database driver we want to use. In this case since we're writing for
          Xindice we use <code>org.apache.xindice.client.xmldb.DatabaseImpl</code>
          for our driver and register it with the <code>DatabaseManager</code>
        </p>
        <source><![CDATA[
String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
Class c = Class.forName(driver);

Database database = (Database) c.newInstance();
DatabaseManager.registerDatabase(database);
        ]]></source>
        <p>
          Now that our driver is registered we're ready to retrieve the
          collection that we want to work with.
        </p>
        <source>
String uri = "xmldb:xindice:///db/addressbook";
Collection col =
  DatabaseManager.getCollection(uri);
        </source>
        <p>
          In the XML:DB API collections are retrieved by calling
          <code>getCollection</code> and handing it a URI that specifies the
          collection we want. The format of this URI will vary depending on
          the database implementation being used but will always begin with
          <code>xmldb:</code> and be followed by a database specific database
          name, <code>xindice:</code> in the case of Xindice.
        </p>
        <p>
          The rest of the URI is a path used to locate the collection you want
          to work with. This path begins with the name of the root collection
          for the Xindice instance that you are trying to connect with. All
          Xindice instances must have a unique name for the root collection. The
          reason for this is that the name of the root collection is also the
          name of the database instance and that name is what the Xindice server
          uses to register itself with the naming service. In all examples in
          this guide the root collection is called <code>db</code>. This
          is the default name used for a newly installed instance of Xindice. If
          you have more then one instance of Xindice running that you must be
          sure to change the names on all other instances so that they are
          unique.
          Once you do this you can switch between the instances by simply
          changing the first component of the path.
        </p>
        <source>
  xindice:///db/news
  xindice:///db2/news
        </source>
        <p>
          These paths will switch between a Xindice server with a root collection
          of db and one of db2. These instances could be on the same machine or
          on two completely different machines and to your application there is
          no significant difference.
        </p>
        <p>
          After the root collection name the rest of the URI simply consists of
          the path to locate the collection you want to work with.
        </p>
        <p>
          Now that we have a reference to the collection that we want to work
          with we need to get a reference to the <code>XPathQueryService</code>
          service for that collection.
        </p>
        <source><![CDATA[
String xpath = "//person[fname='John']";
XPathQueryService service =
(XPathQueryService) col.getService("XPathQueryService", "1.0");
ResourceSet resultSet = service.query(xpath);
        ]]></source>
        <p>
          Services provide a way to extend the functionality of the XML:DB
          API as well as enabling the definition of optional functionality.
          In this case the <code>XPathQueryService</code> is an optional
          part of Core Level 0 but is a required part of Core Level 1.
          Since Xindice provides a Core Level 1 XML:DB API implementation the
          <code>XPathQueryService</code> is available.
        </p>
        <p>
          To retrieve a service you must know the name of the service that
          you want as well as the version. Services define their own custom
          interfaces so you must cast the result of the getService() call to
          the appropriate service type before you can call its methods. The
          <code>XPathQueryService</code> defines a method
          <code>query()</code> that takes an XPath string as an argument.
          Different services will define different sets of methods.
        </p>
        <p>
          Now that we have an <code>XPathQueryService</code> reference
          and have called the <code>query()</code> method we get a
          <code>ResourceSet</code> containing the results. Since we just
          want to print out the results of the query, we need to get an
          iterator for our results and then use it to print out the results.
        </p>
        <source>
ResourceIterator results = resultSet.getIterator();
while (results.hasMoreResources()) {
    Resource res = results.nextResource();
    System.out.println((String) res.getContent());
}
        </source>
        <p>
          Resources are another important concept within the XML:DB API. Since
          XML can be accessed with multiple APIs and since an XML database
          could potentialy store more the one type of data, resources provide
          an abstract way to access the data in the database. The Xindice
          implementation only supports XMLResource but other vendors may
          support additional resource types as well.
        </p>
        <p>
          XMLResource provides access to the underlying XML data as either
          text, a DOM Node or via SAX ContentHandlers. In our example we're
          simply working with the content as text but we could just as easily
          have called <code>getContentAsDom()</code> to get the content
          as a DOM Node. Since we just want to print the XML out to the screen
          it is easier to just work with text.
        </p>
        <p>
          The final element about our example program worth noting is the
          finally clause.
        </p>
        <source>
finally {
    if (col != null) {
        col.close();
    }
}
        </source>
        <p>
          The finally clause closes the collection that we created earlier.
          This is vitally important and should never be overlooked. Closing
          the collection releases all the resources consumed by the
          collection. In the Xindice implementation this will make sure that the
          CORBA resources are released properly. Failure to properly call
          close on the collection will result in a
          resource leak within the server.
        </p>
      </section>
      <section>
        <title>Accessing Xindice Remotely</title>
        <p>
          By default Xindice assumes that the client and server are running on
          the same machine, and the server is running on port 8888. In most
          configurations this will not be the case so it will be necessary to
          include the hostname and port of the server where Xindice is running
          in your URIs. The port you use is the port that the servlet engine is
          listening on. The port setting configuration depends on the servlet
          engine you use. Xindice comes pre-configured with the Jetty servlet
          engine running on port 8888, so URL used by default is
          <code>xmldb:xindice://localhost:8888</code>.
          To access the collection /db/addressbook on host xml.apache.org port
          8000 the URI would look something like this
          <code>xmldb:xindice://xml.apache.org:8000/db/addressbook</code>. All
          examples in this document assume that server uses default configuration.
        </p>
        <p>
          If you are having problems accessing Xindice remotely this may be the
          result of the Xindice deployment in the non-standard servlet context
          name. Xindice assumes that the server will be deployed under
          <code>/xindice</code> servlet context. To do this, you just need to rename
          Xindice WAR file to <code>xindice.war</code>, and deploy this renamed WAR
          file. Alternatively, you need to specify system property
          <code>xindice.xmlrpc.service-location</code>, or set property
          <code>service-location</code> on the <code>Database</code> XML:DB object
          right after its creation.
        </p>
      </section>
    </section>
    <section>
      <title>Managing Documents</title>
      <p>
        In this chapter we'll look at using the XML:DB API to manage documents
        within the Xindice server. As part of this we'll look at some sample code
        that could be used to manage the data used by the AddressBook example
        application included with the server and discussed in more detail later.
      </p>
      <p>
        When looking at managing documents with the XML:DB API the first thing
        we need to confront is that the API doesn't actually work directly with
        documents. It works with what the API calls resources that are an
        abstraction of a document. This abstraction allows you to work with the same
        document as either text, a DOM tree or SAX events. This is important to
        understand as the use of resources runs as a common thread throughout the
        XML:DB API. The XML:DB API actually defines more then one type of resource
        however Xindice does not implement anything beyond XMLResource.
      </p>
      <section>
        <title>Creating a Collection</title>
        <p>
          Before we can work with any data in the database we need to create
          a collection to hold our data.
          While we could easily create this collection using the command line
          tools it will be more fun to see how you might do this from your own
          program. This will also show you a quick example of using the Xindice
          specific <code>CollectionManager</code> service to manage
          collections. This guide doesn't go into detail about using this
          service but you can find lots of examples by looking at the source
          code to the command line tool commands in the package
          <code>org/apache/xindice/tools/commands</code>.
        </p>
        <p>
          The collection we want to create will be named
          <code>mycollection</code> and will be a child of the root
          collection.
        </p>
        <section>
          <title>Creating a Collection</title>
          <source><![CDATA[
package org.apache.xindice.examples;

import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

// For the Xindice specific CollectionManager service
import org.apache.xindice.client.xmldb.services.*;

import org.apache.xindice.xml.dom.*;

public class CreateCollection {

public static void main(String[] args) throws Exception {
  Collection col = null;
  try {
    String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
    Class c = Class.forName(driver);

    Database database = (Database) c.newInstance();
    DatabaseManager.registerDatabase(database);
    String uri = "xmldb:xindice:///db/";
    col =
      DatabaseManager.getCollection(uri);

    String collectionName = "mycollection";
    CollectionManager service =
      (CollectionManager) col.getService("CollectionManager", "1.0");

    // Build up the Collection XML configuration.
    String collectionConfig =
      "<collection compressed=\"true\" " +
      "            name=\"" + collectionName + "\">" +
      "   <filer class=\"org.apache.xindice.core.filer.BTreeFiler\"/>" +
      "</collection>";

    service.createCollection(collectionName,
      DOMParser.toDocument(collectionConfig));

    System.out.println("Collection " + collectionName + " created.");
  }
  catch (XMLDBException e) {
    System.err.println("XML:DB Exception occured " + e.errorCode);
  }
  finally {
    if (col != null) {
      col.close();
    }
  }
}
}
          ]]></source>
        </section>
        <p>
          With this example you can see a basic example of how to create the
          <code>CollectionManager</code> service and use it to create
          the collection. This service is proprietary to Xindice so if you use
          it in your application you will not be able to port it to another
          server. However, if you have the need to create collections within
          your programs this is currently the most powerful way to do it.
        </p>
        <p>
          The trickiest part of creating a collection is creating the
          proper XML configuration to hand to the
          <code>createCollection</code> method. This XML
          is the exact same thing that is placed into the system.xml file.
          At this time these XML configurations are not documented so to
          see what they need to be you should look for examples in system.xml
          and the source code for the command line tools. Future versions of
          this documentation will cover this area in more detail.
        </p>
      </section>
      <section>
        <title>Working with Documents</title>
        <p>
          Now that we have a collection to store our data, we need to add
          some data to it. We could use the command line tools
          to do this but since we want to learn how the XML:DB API works we'll
          look at how we can do this in a program that we write.
        </p>
        <p>
          For our examples in this chapter we'll work with some very simple
          XML files that could be used to represent a person in an
          address book. Later in the guide we'll look at an example
          application that implements the actual address book functionality.
          Each address book entry is stored in a seperate XML file.
        </p>
        <section>
          <title>Example Document</title>
          <source><![CDATA[
  <person>
    <fname>John</fname>
    <lname>Smith</lname>
    <phone type="work">563-456-7890</phone>
    <phone type="home">534-567-8901</phone>
    <email type="home">jsmith@somemail.com</email>
    <email type="work">john@lovesushi.com</email>
    <address type="home">34 S. Colon St.</address>
    <address type="work">9967 W. Shrimp Ave.</address>
  </person>
          ]]></source>
        </section>
        <p>
          If we store this example XML into a file we can then load it into
          our addressbook collection using a simple program.
        </p>
        <section>
          <title>Adding an XML File to the Database</title>
          <source><![CDATA[
package org.apache.xindice.examples;

import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

import java.io.*;

public class AddDocument {

public static void main(String[] args) throws Exception {
  Collection col = null;
  try {
    String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
    Class c = Class.forName(driver);

    Database database = (Database) c.newInstance();
    DatabaseManager.registerDatabase(database);
    col =
      DatabaseManager.getCollection("xmldb:xindice:///db/addressbook");

    String data = readFileFromDisk(args[0]);

    XMLResource document =
      (XMLResource) col.createResource(null, "XMLResource");
    document.setContent(data);
    col.storeResource(document);
    System.out.println("Document " + args[0] + " inserted");
  }
  catch (XMLDBException e) {
    System.err.println("XML:DB Exception occured " + e.errorCode);
  }
  finally {
    if (col != null) {
      col.close();
    }
  }
}

public static String readFileFromDisk(String fileName) throws Exception {
  File file = new File(fileName);
  FileInputStream insr = new FileInputStream(file);

  byte[] fileBuffer = new byte[(int)file.length()];

  insr.read(fileBuffer);
  insr.close();

  return new String(fileBuffer);
}
}
          ]]></source>
        </section>
        <p>
          Much of this program is similar to what we've already seen in our
          other XML:DB programs. Really the only difference is the code to add
          the document.
        </p>
        <p>
          Documents are added to the server by first creating a new resource
          implementation from a collection,
          setting its content and then storing the resource to the collection.
          The type of resource that is created is an XMLResource this can be
          used to store XML as either text, a DOM Node or a SAX
          ContentHandler.
        </p>
        <p>
          If you had your content already in a DOM tree you could also add
          the document as a DOM.
        </p>
        <source><![CDATA[
XMLResource document = (XMLResource) col.createResource(null, "XMLResource");
document.setContentAsDOM(doc); // doc is a DOM document
col.storeResource(document);
        ]]></source>
        <p>
          The only difference here is that you must have the document as a DOM
          Document already and then call <code>setContentAsDOM()</code>. From
          there the resource works the same as always.
        </p>
        <p>
          One thing to note is that a resource must be stored in the same
          collection from which it was originally created.
        </p>
        <section>
          <title>Retrieving an XML Document from the Database</title>
          <source><![CDATA[
package org.apache.xindice.examples;

import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

import java.io.*;

public class RetrieveDocument {
public static void main(String[] args) throws Exception {
  Collection col = null;
  try {
    String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
    Class c = Class.forName(driver);

    Database database = (Database) c.newInstance();
    DatabaseManager.registerDatabase(database);
    col =
      DatabaseManager.getCollection("xmldb:xindice:///db/addressbook");

    XMLResource document = (XMLResource) col.getResource(args[0]);
    if (document != null) {
      System.out.println("Document " + args[0]);
      System.out.println(document.getContent());
    }
    else {
      System.out.println("Document not found");
    }
  }
  catch (XMLDBException e) {
    System.err.println("XML:DB Exception occured " + e.errorCode);
  }
  finally {
    if (col != null) {
      col.close();
    }
  }
}
}
          ]]></source>
        </section>
        <section>
          <title>Deleting an XML Document from the Database</title>
          <source><![CDATA[
package org.apache.xindice.examples;

import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

import java.io.*;

public class DeleteDocument {
public static void main(String[] args) throws Exception {
  Collection col = null;
  try {
    String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
    Class c = Class.forName(driver);

    Database database = (Database) c.newInstance();
    DatabaseManager.registerDatabase(database);
    col =
      DatabaseManager.getCollection("xmldb:xindice:///db/addressbook");

    Resource document = col.getResource(args[0]);
    col.removeResource(document);
    System.out.println("Document " + args[0] + " removed");
  }
  catch (XMLDBException e) {
    System.err.println("XML:DB Exception occured " + e.errorCode);
  }
  finally {
    if (col != null) {
      col.close();
    }
  }
}
}
          ]]></source>
        </section>
      </section>
    </section>
    <section>
      <title>Using XPath to Query the Database</title>
      <section>
        <title>Introduction</title>
        <p>
          Xindice currently supports XPath as a query language. In many
          applications XPath is only applied at the document level but in
          Xindice XPath queries are executed at the collection level. This
          means that a query can be run against multiple documents and the
          result set will contain all matching nodes from all documents
          in the collection.
          The Xindice server also support the creation of indexes on
          particular XPaths to speed up commonly used XPath queries.
        </p>
      </section>
      <section>
        <title>Using the XML:DB Java API</title>
        <p>
          The XML:DB API defines operations for searching single documents as
          well as collections of XML documents using XPath. These operations
          are exposed through the XPathQueryService. In order to query single
          documents you use the <code>queryResource()</code> method and to query
          an entire collection you use the <code>query()</code> method.
        </p>
        <section>
          <title>Querying with XPath</title>
          <p>
            This example simply executes an XPath query against a
            collection, retrieves the results as text and prints them out.
          </p>
          <p>
            You can find the source code for this example in
            Xindice/java/examples/guide/src/org/apache/xindice/examples/Example1.java
          </p>
          <source><![CDATA[
package org.apache.xindice.examples;

import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

public class Example1 {
public static void main(String[] args) throws Exception {
  Collection col = null;
  try {
    String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
    Class c = Class.forName(driver);

    Database database = (Database) c.newInstance();
    DatabaseManager.registerDatabase(database);

    col =
      DatabaseManager.getCollection("xmldb:xindice:///db/addressbook");

    String xpath = "//person[fname='John']";
    XPathQueryService service =
      (XPathQueryService) col.getService("XPathQueryService", "1.0");
    ResourceSet resultSet = service.query(xpath);
    ResourceIterator results = resultSet.getIterator();
    while (results.hasMoreResources()) {
      Resource res = results.nextResource();
      System.out.println((String) res.getContent());
    }
  }
  catch (XMLDBException e) {
    System.err.println("XML:DB Exception occured " + e.errorCode);
  }
  finally {
    if (col != null) {
      col.close();
    }
  }
}
}
          ]]></source>
        </section>
        <p>TODO: cover namespace support</p>
      </section>
    </section>
    <section>
      <title>Using XUpdate to Modify the Database</title>
      <section>
        <title>Introduction</title>
        <p>
          XUpdate is a specification under development by the XML:DB Initiative
          to enable simpler updating of XML documents. It is useful within the
          context of an XML database as well as in standalone implementations
          for general XML applications. XUpdate gives you a declarative method
          to insert nodes, remove nodes, and change nodes within an XML
          document. The syntax is specified in the
          <link href="http://xmldb-org.sourceforge.net/xupdate/xupdate-wd.html">
          XUpdate working draft</link> available on the XML:DB Initiative website.
        </p>
        <p>
          The XUpdate implementation in Xindice is based around the
          Lexus XUpdate implementation that was developed by the
          <link href="http://www.infozone-group.org/">Infozone Group</link>.
        </p>
        <p>
          The general model around XUpdate is to use an
          <code>xupdate:modifications</code>
          container to batch a series of XUpdate commands. All commands
          will be performed in series against either a single XML document or
          an entire collection of XML documents as specified by the developer.
        </p>
        <p>
          Execution of XUpdate commands is performed in two phases. First
          selecting a node set within the document or collection and then
          applying a change to the selected nodes.
        </p>
        <section>
          <title>Basic XUpdate Insert Command</title>
          <source><![CDATA[
<xupdate:modifications version="1.0"
  xmlns:xupdate="http://www.xmldb.org/xupdate">

<xupdate:insert-after select="/addresses/address[1]" >

<xupdate:element name="address">
<xupdate:attribute name="id">2</xupdate:attribute>
<fullname>John Smith</fullname>
<born day='2' month='12' year='1974'/>
<country>Germany</country>
</xupdate:element>

</xupdate:insert-after>
</xupdate:modifications>
          ]]></source>
        </section>
      </section>
      <section>
        <title>XUpdate Commands</title>
        <ul>
          <li>
            <code>xupdate:insert-before</code> - Inserts a new node in document order before the selected node.
          </li>
          <li>
            <code>xupdate:insert-after</code> - Inserts a new node in document order after the selected node.
          </li>
          <li>
            <code>xupdate:update</code> - Replaces all child nodes of the selected node with the specified nodes.
          </li>
          <li>
            <code>xupdate:append</code> - Appends the specified node to the content of the selected node.
          </li>
          <li>
            <code>xupdate:remove</code> - Remove the selected node
          </li>
          <li>
            <code>xupdate:rename</code> - Renames the selected node
          </li>
          <li>
            <code>xupdate:variable</code> - Defines a variable containing a node list that can be reused in later operations.
          </li>
        </ul>
      </section>
      <section>
        <title>XUpdate Node Construction</title>
        <ul>
          <li>
            <code>xupdate:element</code> - Creates a new element in the document.
          </li>
          <li>
            <code>xupdate:attribute</code> - Creates a new attribute node
            associated with an <code>xupdate:element</code>.
          </li>
          <li>
            <code>xupdate:text</code> - Creates a text content node in the document.
          </li>
          <li>
            <code>xupdate:processing-instruction</code> - Creates a
            processing instruction node in the document.
          </li>
          <li>
            <code>xupdate:comment</code> - Creates a new comment node in the
            document.
          </li>
        </ul>
      </section>
      <section>
         <title>Using the XML:DB API for XUpdate</title>
         <p>
           The XML:DB API provides an XUpdateQueryService to enable executing
           XUpdate commands against single documents or collections of
           documents. To update a single document you use the
           <code>updateResource()</code> method and to apply the updates
           to an entire collection you use the <code>update()</code> method.
         </p>
         <p>
           The next example program applies a set of XUpdate modifications to
           an entire collection of data. It first removes all elements that
           match the XPath
           <code>/person/phone[@type = 'home']</code>
           and then adds a new entry after all elements that match the XPath
           <code>/person/phone[@type = 'work']</code>
         </p>
         <section>
           <title>Using XUpdate to modify the database</title>
           <source><![CDATA[
import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;

/**
* Simple XML:DB API example to update the database.
*/
public class XUpdate {
public static void main(String[] args) throws Exception {
  Collection col = null;
  try {
    String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
    Class c = Class.forName(driver);

    Database database = (Database) c.newInstance();
    DatabaseManager.registerDatabase(database);
    col =
      DatabaseManager.getCollection("xmldb:xindice:///db/addressbook");

    String xupdate = "<xu:modifications version=\"1.0\"" +
      "      xmlns:xu=\"http://www.xmldb.org/xupdate\">" +
      "   <xu:remove select=\"/person/phone[@type = 'home']\"/>" +
      "   <xu:update select=\"/person/phone[@type = 'work']\">" +
      "       480-300-3003" +
      "   </xu:update>" +
      "</xu:modifications>";

    XUpdateQueryService service =
      (XUpdateQueryService) col.getService("XUpdateQueryService", "1.0");
    service.update(xupdate);
  }
  catch (XMLDBException e) {
    System.err.println("XML:DB Exception occured " + e.errorCode + " " +
    e.getMessage());
  }
  finally {
    if (col != null) {
      col.close();
    }
  }
}
}
           ]]></source>
         </section>
       </section>
     </section>
     <section>
       <title>Storing metadata</title>
       <p>
         Xindice allows a developer to store metadata that is associated with
         any collection or document. Metadata is data that is associated with
         a document or collection but is not part of that document or collection.
         For example, a filesystem lists the last modified time of a file or
         directory. That last modified time is metadata about the file or directory.
       </p>
       <p>
         Within Xindice, when metadata is turned on, each document and collection
         has a MetaData object associated with it. The MetaData object is composed
         of three sections and is represented in XML like this:
       </p>
       <source><![CDATA[
  <meta>
    <system type="doc">
      <attr name="created" value="10128378882" />
      <attr name="modified" value="10128378882" />
    </system>
    <attrs>
      <attr name="key" value="value"/>
      <attr name="foo" value="bar"/>
    </attrs>
    <custom>
      <myspecial>
        any <valid /> xml
      </myspecial>
    </custom>
  </meta>
       ]]></source>
       <p>
         The first section is enclosed by the &lt;system&gt; element and is controlled
         by the core of Xindice.  It currently tracks the type of resource referenced,
         creation time and last modification time of the resource.  The &lt;system&gt;
         element has an attribute "type" which is either "doc" for document or "col"
         for collection.  Within the &lt;system&gt; element are &lt;attr&gt; elements.
         Each &lt;attr&gt; element has two attributes, name and value.  The creation
         and modification times are stored in individual &lt;attr&gt; elements.
         The value of these attributes are recorded as milliseconds since midnight
         Jan 1, 1970 (just as System.currentTimeMills() ).
       </p>
       <p>
         The second section is a map of key-value pairs and is enclosed by the &lt;attrs&gt; element.  Each key-value
         pair is represented in a single &lt;attr&gt; element.  The key-value pairs are completely controlled by the user.  You
         can add or remove any key-value pair in this section.  Note that the map is from Object to Object, so you
         can store any object your application requires.
       </p>
       <p>
         The third section is a custom XML document.  This too is completely controlled
         by the user.  The only prerequisite is that the document stored is well-formed
         XML.
       </p>
       <section>
         <title>Enabling metadata</title>
         <p>
           To turn on metadata storage in Xindice, edit the system.xml configuration
           file and set the "use-metadata" attribute of the root-collection element to
           "on".  Restart your container, and metadata storage will be enabled.
         </p>
         <p>
           If properly configured, when you restart your container, you will see a
           log message that looks like this:
         </p>
         <source>
  Dec 30, 2002 10:21:51 AM org.apache.xindice.core.Database setConfig
  INFO: Meta information initialized
         </source>
         <note>
           This example is from the output of Tomcat.  The output from other
           containers might look different, but the message ("Meta information
           initialized") should be identical.
         </note>
       </section>
       <section>
         <title>Using metadata</title>
         <p>
           How you use metadata is really up to you, the application developer.
           There are many potential uses depending on your application.  One
           example is a content management system in which each document has a
           series of states through which it must pass.  The states might be
           controlled by a finite state machine, but each document's current
           state would be stored in the metadata associated with it.
         </p>
       </section>
       <section>
         <title>Sample metadata code</title>
         <p>
           Currently the metadata accessors are implemented as non-standard meta
           information service which can be obtained via XML:DB API (name
           "MetaService", version "1.0"), and it also available via the XML-RPC code.
         </p>
         <p>
           The Xindice XML-RPC server has four metadata related methods:
           GetCollectionMeta, GetDocumentMeta, SetCollectionMeta, SetDocumentMeta.
           Here's quick perl script which creates a collection and then dumps out
           its metadata contents, and then sets some values inside the metadata.
         </p>
         <source><![CDATA[
#!/usr/local/bin/perl -w

use strict;
use Frontier::Client;
use Data::Dumper;

my($server,$result,$url);

$url = 'http://localhost:8888/xindice';
$server = Frontier::Client->new('url'=>$url,'debug'=>0);

## try listing the collections
## look at org/apache/xindice/server/rpc/messages/*.java
## for the 'message' possibilities.  The parameters are there as well.

my $colname = 'ninemetatest';
my $args = {};

#first, add the collection directly under the /db root.
$args->{'message'} = 'CreateCollection';
$args->{'collection'} = '/db';
$args->{'name'} = $colname;
$result = $server->call('run',$args);

## now get the collection's meta
$args = {};
$args->{'message'} = 'GetCollectionMeta';
$args->{'collection'} = '/db/'.$colname;
$result = $server->call('run',$args);

## this should print out the xml for the
## collection's metadata.
print Dumper($result);


## now add some stuff to the metadata
my $meta=<<EOF;
<?xml version="1.0"?>
    <meta>
        <!-- since the system is controlled by
          Xindice, this doesn't matter...
        -->
        <system type="col">
            <attr name="created" value="1" />
            <attr name="modified" value="5" />
        </system>
        <attrs>
            <attr name="test" value="added" />
        </attrs>
        <custom>
              <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
                  <test>the rdf example</test>
              </rdf:RDF>
        </custom>
    </meta>
EOF
$args = {};
$args->{'message'} = 'SetCollectionMeta';
$args->{'collection'} = '/db/'.$colname;
$args->{'meta'} = $meta;
$result = $server->call('run',$args);

## this should print out the xml for the
## collection's revised metadata.
print Dumper($result);
         ]]></source>
       </section>
       <fixme author="dviner">
         Make this example java instead of perl.
       </fixme>
       <note>Metadata is currently only exposed in the XML-RPC accessor.</note>
    </section>
    <section>
      <title>Example Application</title>
      <section>
        <title>Address Book</title>
        <p>
          The address book example is a simple servlet based application
          constructued using Xindice. For more information on this example look
          in the <code>Xindice/java/examples/addressbook</code> directory.
        </p>
        <p>
          TODO: Add more detail about building servlet applications.
        </p>
      </section>
    </section>

    <section>
      <title>Experimental Features</title>
      <p>
        There are a couple of features in Xindice that are definitely
        experimental. These features can be interesing to explore to see some
        things that could be useful in future versions of Xindice but they should
        not be considered complete or stable.
      </p>
    </section>
  </body>
</document>
