xml-general-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From vgritse...@apache.org
Subject svn commit: r602294 [2/10] - in /xml/site/targets/xindice: ./ 1.0/ 1.1/ 1.1/howto/ 1.2/ 1.2/howto/ dev/ skin/ skin/images/
Date Sat, 08 Dec 2007 02:01:42 GMT
Added: xml/site/targets/xindice/1.1/guide-developer.html
URL: http://svn.apache.org/viewvc/xml/site/targets/xindice/1.1/guide-developer.html?rev=602294&view=auto
==============================================================================
--- xml/site/targets/xindice/1.1/guide-developer.html (added)
+++ xml/site/targets/xindice/1.1/guide-developer.html Fri Dec  7 18:01:36 2007
@@ -0,0 +1,1729 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta content="Apache Forrest" name="Generator">
+<meta name="Forrest-version" content="0.8">
+<meta name="Forrest-skin-name" content="pelt">
+<title>Xindice 1.1 Developer Guide</title>
+<link type="text/css" href="../skin/basic.css" rel="stylesheet">
+<link media="screen" type="text/css" href="../skin/screen.css" rel="stylesheet">
+<link media="print" type="text/css" href="../skin/print.css" rel="stylesheet">
+<link type="text/css" href="../skin/profile.css" rel="stylesheet">
+<script src="../skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="../skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="../skin/fontsize.js" language="javascript" type="text/javascript"></script>
+<link rel="shortcut icon" href="../">
+</head>
+<body onload="init()">
+<script type="text/javascript">ndeSetTextSize();</script>
+<div id="top">
+<!--+
+    |breadtrail
+    +-->
+<div class="breadtrail">
+<a href="http://www.apache.org/">apache</a> &gt; <a href="http://xml.apache.org/">xml.apache</a> &gt; <a href="http://xml.apache.org/xindice/">xindice</a><script src="../skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
+</div>
+<!--+
+    |header
+    +-->
+<div class="header">
+<!--+
+    |start group logo
+    +-->
+<div class="grouplogo">
+<a href="http://xml.apache.org"><img class="logoImage" alt="XML Apache" src="../images/group-logo.gif" title="Apache XML Project"></a>
+</div>
+<!--+
+    |end group logo
+    +-->
+<!--+
+    |start Project Logo
+    +-->
+<div class="projectlogo">
+<a href="http://xml.apache.org/xindice/"><img class="logoImage" alt="Xindice" src="../images/xindice.gif" title="Apache Xindice: Native XML database"></a>
+</div>
+<!--+
+    |end Project Logo
+    +-->
+<!--+
+    |start Search
+    +-->
+<div class="searchbox">
+<form action="http://www.google.com/search" method="get" class="roundtopsmall">
+<input value="xml.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp; 
+                    <input name="Search" value="Search" type="submit">
+</form>
+</div>
+<!--+
+    |end search
+    +-->
+<!--+
+    |start Tabs
+    +-->
+<ul id="tabs">
+<li>
+<a class="unselected" href="../index.html">Home</a>
+</li>
+<li>
+<a class="unselected" href="../1.0/index.html">1.0</a>
+</li>
+<li class="current">
+<a class="selected" href="../1.1/index.html">1.1</a>
+</li>
+<li>
+<a class="unselected" href="../1.2/index.html">1.2-Dev</a>
+</li>
+<li>
+<a class="unselected" href="../dev/index.html">Dev</a>
+</li>
+</ul>
+<!--+
+    |end Tabs
+    +-->
+</div>
+</div>
+<div id="main">
+<div id="publishedStrip">
+<!--+
+    |start Subtabs
+    +-->
+<div id="level2tabs"></div>
+<!--+
+    |end Endtabs
+    +-->
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+//  --></script>
+</div>
+<!--+
+    |breadtrail
+    +-->
+<div class="breadtrail">
+
+             &nbsp;
+           </div>
+<!--+
+    |start Menu, mainarea
+    +-->
+<!--+
+    |start Menu
+    +-->
+<div id="menu">
+<div onclick="SwitchMenu('menu_1.1', '../skin/')" id="menu_1.1Title" class="menutitle">Overview</div>
+<div id="menu_1.1" class="menuitemgroup">
+<div class="menuitem">
+<a href="../1.1/index.html">Overview</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_selected_1.2', '../skin/')" id="menu_selected_1.2Title" class="menutitle" style="background-image: url('../skin/images/chapter_open.gif');">Documentation</div>
+<div id="menu_selected_1.2" class="selectedmenuitemgroup" style="display: block;">
+<div class="menuitem">
+<a href="../1.1/guide-administrator.html">Administrator Guide</a>
+</div>
+<div class="menuitem">
+<a href="../1.1/guide-user.html">User Guide</a>
+</div>
+<div class="menupage">
+<div class="menupagetitle">Developer Guide</div>
+</div>
+<div class="menuitem">
+<a href="../1.1/guide-tools.html">Tool Guide</a>
+</div>
+<div class="menuitem">
+<a href="../1.1/guide-xpath.html">XPath Guide</a>
+</div>
+<div class="menuitem">
+<a href="../1.1/faq.html">FAQ</a>
+</div>
+<div class="menuitem">
+<a href="http://wiki.apache.org/xindice">Wiki</a>
+</div>
+<div class="menuitem">
+<a href="http://xml.apache.org/xindice/1.1/api/index.html">Javadocs</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3', '../skin/')" id="menu_1.3Title" class="menutitle">How-Tos</div>
+<div id="menu_1.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../1.1/howto/index.html">Overview</a>
+</div>
+<div onclick="SwitchMenu('menu_1.3.2', '../skin/')" id="menu_1.3.2Title" class="menutitle">Compilation</div>
+<div id="menu_1.3.2" class="menuitemgroup">
+<div class="menuitem">
+<a href="../1.1/howto/compilation-unix.html">Unix</a>
+</div>
+<div class="menuitem">
+<a href="../1.1/howto/compilation-windows.html">Windows</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3.3', '../skin/')" id="menu_1.3.3Title" class="menutitle">Installation</div>
+<div id="menu_1.3.3" class="menuitemgroup">
+<div class="menuitem">
+<a href="../1.1/howto/installation-tomcat.html">Tomcat How-to</a>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.3.4', '../skin/')" id="menu_1.3.4Title" class="menutitle">Upgrading</div>
+<div id="menu_1.3.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="../1.1/howto/upgrading-one-one.html">From 1.1b1 and up</a>
+</div>
+<div class="menuitem">
+<a href="../1.1/howto/upgrading-one-oh.html">From 1.0</a>
+</div>
+</div>
+</div>
+<div onclick="SwitchMenu('menu_1.4', '../skin/')" id="menu_1.4Title" class="menutitle">Resources</div>
+<div id="menu_1.4" class="menuitemgroup">
+<div class="menuitem">
+<a href="http://wiki.apache.org/xindice">Wiki</a>
+</div>
+<div class="menuitem">
+<a href="http://xmldb-org.sourceforge.net/">XML:DB Initiative</a>
+</div>
+</div>
+<div id="credit"></div>
+<div id="roundbottom">
+<img style="display: none" class="corner" height="15" width="15" alt="" src="../skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
+<!--+
+  |alternative credits
+  +-->
+<div id="credit2"></div>
+</div>
+<!--+
+    |end Menu
+    +-->
+<!--+
+    |start content
+    +-->
+<div id="content">
+<script language="Javascript" type="text/javascript">
+function printit() {
+  if (window.print) {
+    window.focus();
+    window.print();
+  }
+}
+        </script><script language="Javascript" type="text/javascript">
+var NS = (navigator.appName == "Netscape");
+var VERSION = parseInt(navigator.appVersion);
+if (VERSION > 3) {
+  document.write('<div title="Print this Page" class="printlink">');
+  document.write('  <a class="dida" href="javascript:printit()">');
+  document.write('    <img alt="print - icon" src="../skin/images/printer.gif" class="skin">');
+  document.write('    <br>');
+  document.write('  PRINT</a>');
+  document.write('</div>');
+}
+        </script>
+<div title="Portable Document Format" class="pdflink">
+<a class="dida" href="guide-developer.pdf"><img alt="PDF -icon" src="../skin/images/pdfdoc.gif" class="skin"><br>
+        PDF</a>
+</div>
+<h1>Xindice 1.1 Developer Guide</h1>
+<div id="minitoc-area">
+<ul class="minitoc">
+<li>
+<a href="#Introduction+to+Programming+Xindice">Introduction to Programming Xindice</a>
+<ul class="minitoc">
+<li>
+<a href="#Accessing+the+Server">Accessing the Server</a>
+<ul class="minitoc">
+<li>
+<a href="#API%27s">API's</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Introducing+the+XML%3ADB+XML+Database+API">Introducing the XML:DB XML Database API</a>
+</li>
+<li>
+<a href="#Setting+up+Your+Build+Environment">Setting up Your Build Environment</a>
+</li>
+<li>
+<a href="#Preparing+the+Server+For+the+Examples">Preparing the Server For the Examples</a>
+</li>
+<li>
+<a href="#Diving+in+With+an+Example+Program">Diving in With an Example Program</a>
+<ul class="minitoc">
+<li>
+<a href="#Simple+XML%3ADB+Example+Program">Simple XML:DB Example Program</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Accessing+Xindice+Remotely">Accessing Xindice Remotely</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Managing+Documents">Managing Documents</a>
+<ul class="minitoc">
+<li>
+<a href="#Creating+a+Collection">Creating a Collection</a>
+<ul class="minitoc">
+<li>
+<a href="#Creating+a+Collection-N10225">Creating a Collection</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Working+with+Documents">Working with Documents</a>
+<ul class="minitoc">
+<li>
+<a href="#Example+Document">Example Document</a>
+</li>
+<li>
+<a href="#Adding+an+XML+File+to+the+Database">Adding an XML File to the Database</a>
+</li>
+<li>
+<a href="#Retrieving+an+XML+Document+from+the+Database">Retrieving an XML Document from the Database</a>
+</li>
+<li>
+<a href="#Deleting+an+XML+Document+from+the+Database">Deleting an XML Document from the Database</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Using+XPath+to+Query+the+Database">Using XPath to Query the Database</a>
+<ul class="minitoc">
+<li>
+<a href="#Introduction">Introduction</a>
+</li>
+<li>
+<a href="#Using+the+XML%3ADB+Java+API">Using the XML:DB Java API</a>
+<ul class="minitoc">
+<li>
+<a href="#Querying+with+XPath">Querying with XPath</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Using+XUpdate+to+Modify+the+Database">Using XUpdate to Modify the Database</a>
+<ul class="minitoc">
+<li>
+<a href="#Introduction-N102CB">Introduction</a>
+<ul class="minitoc">
+<li>
+<a href="#Basic+XUpdate+Insert+Command">Basic XUpdate Insert Command</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#XUpdate+Commands">XUpdate Commands</a>
+</li>
+<li>
+<a href="#XUpdate+Node+Construction">XUpdate Node Construction</a>
+</li>
+<li>
+<a href="#Using+the+XML%3ADB+API+for+XUpdate">Using the XML:DB API for XUpdate</a>
+<ul class="minitoc">
+<li>
+<a href="#Using+XUpdate+to+modify+the+database">Using XUpdate to modify the database</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Storing+metadata">Storing metadata</a>
+<ul class="minitoc">
+<li>
+<a href="#Enabling+metadata">Enabling metadata</a>
+</li>
+<li>
+<a href="#Using+metadata">Using metadata</a>
+</li>
+<li>
+<a href="#Sample+metadata+code">Sample metadata code</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Example+Application">Example Application</a>
+<ul class="minitoc">
+<li>
+<a href="#Address+Book">Address Book</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#Experimental+Features">Experimental Features</a>
+</li>
+</ul>
+</div>
+    
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+      If you notice incorrectness in this documentation, please
+      <a href="../mail.html">notify</a> Xindice community. Your feedback
+      will help create better documentation.
+    </div>
+</div>
+    
+<a name="N10025"></a><a name="Introduction+to+Programming+Xindice"></a>
+<h2 class="h3">Introduction to Programming Xindice</h2>
+<div class="section">
+<a name="N1002B"></a><a name="Accessing+the+Server"></a>
+<h3 class="h4">Accessing the Server</h3>
+<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 <a href="guide-user.html">Xindice Users Guide</a>.
+        </p>
+<a name="N10038"></a><a name="API%27s"></a>
+<h4>API's</h4>
+<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>
+<p>
+          The most common API for end user applications is the XML:DB XML
+          Database API that was developed by the
+          <a href="http://xmldb-org.sourceforge.net/">XML:DB Initiative</a>.
+          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,
+          <a href="http://xmldb-org.sourceforge.net/">http://xmldb-org.sourceforge.net</a>. 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>
+<a name="N10066"></a><a name="Introducing+the+XML%3ADB+XML+Database+API"></a>
+<h3 class="h4">Introducing the XML:DB XML Database API</h3>
+<p>
+          XML:DB API is being developed by the
+          <a href="http://xmldb-org.sourceforge.net/">XML:DB Initiative</a> 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
+          <span class="codefrag">xindice/java/src/org/apache/xindice/tools/command</span>.
+        </p>
+<a name="N100B3"></a><a name="Setting+up+Your+Build+Environment"></a>
+<h3 class="h4">Setting up Your Build Environment</h3>
+<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 <span class="codefrag">CLASSPATH</span>.
+        </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 <span class="codefrag">JAVA_HOME</span> environment variable and
+          <span class="codefrag">PATH</span> 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 <span class="codefrag">CLASSPATH</span>. The following list of
+          jars are required and should be made available on your
+          <span class="codefrag">CLASSPATH</span>. All required jars can be found in
+          <span class="codefrag">xindice/java/lib</span>
+        
+</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>
+<a name="N10105"></a><a name="Preparing+the+Server+For+the+Examples"></a>
+<h3 class="h4">Preparing the Server For the Examples</h3>
+<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>
+<pre class="code">  xindice lc -c /db  </pre>
+<p>
+          If you don't see 'addressbook' listed in the result then you need to create
+          the collection. To create it just run:
+        </p>
+<pre class="code">  xindice ac -c /db -n addressbook  </pre>
+<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
+          <span class="codefrag">java/examples/guide/xml</span>. Run these commands to add
+          the documents.
+        </p>
+<pre class="code">
+  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
+        </pre>
+<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>
+<a name="N1012D"></a><a name="Diving+in+With+an+Example+Program"></a>
+<h3 class="h4">Diving in With an Example Program</h3>
+<a name="N10133"></a><a name="Simple+XML%3ADB+Example+Program"></a>
+<h4>Simple XML:DB Example Program</h4>
+<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>
+<pre class="code">
+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();
+    }
+  }
+}
+
+}
+          </pre>
+<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>
+<pre class="code">
+  cd $XINDICE_HOME/java/examples/guide
+  ./run org.apache.xindice.examples.Example1
+        </pre>
+<p>
+          If all goes well, you should see a result that looks something like this.
+        </p>
+<pre class="code">&lt;?xml version="1.0"?&gt;
+&lt;person xmlns:src="http://xml.apache.org/xindice/Query"
+        src:col="/db/addressbook" src:key="address1"&gt;
+  &lt;fname&gt;John&lt;/fname&gt;
+  &lt;lname&gt;Smith&lt;/lname&gt;
+  &lt;phone type="work"&gt;563-456-7890&lt;/phone&gt;
+  &lt;phone type="home"&gt;534-567-8901&lt;/phone&gt;
+  &lt;email type="home"&gt;jsmith@somemail.com&lt;/email&gt;
+  &lt;email type="work"&gt;john@lovesushi.com&lt;/email&gt;
+  &lt;address type="home"&gt;34 S. Colon St.&lt;/address&gt;
+  &lt;address type="work"&gt;9967 W. Shrimp Ave.&lt;/address&gt;
+&lt;/person&gt;
+        </pre>
+<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>
+<pre class="code">
+  import org.xmldb.api.base.*;
+  import org.xmldb.api.modules.*;
+  import org.xmldb.api.*;
+        </pre>
+<p>
+          These import the basic classes required by the API.
+          <span class="codefrag">import org.xmldb.api.base.*;</span> is the base API module
+          and is required for all XML:DB applications.
+          <span class="codefrag">import org.xmldb.api.*;</span> imports the all
+          important <span class="codefrag">DatabaseManager</span> class which is the
+          entry point into the API.
+          <span class="codefrag">import org.xmldb.api.modules.*;</span> brings in the
+          optional modules defined for the API. In this case the module we're
+          interested in is <span class="codefrag">XPathQueryService</span>.
+        </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 <span class="codefrag">org.apache.xindice.client.xmldb.DatabaseImpl</span>
+          for our driver and register it with the <span class="codefrag">DatabaseManager</span>
+        
+</p>
+<pre class="code">
+String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
+Class c = Class.forName(driver);
+
+Database database = (Database) c.newInstance();
+DatabaseManager.registerDatabase(database);
+        </pre>
+<p>
+          Now that our driver is registered we're ready to retrieve the
+          collection that we want to work with.
+        </p>
+<pre class="code">
+String uri = "xmldb:xindice:///db/addressbook";
+Collection col =
+  DatabaseManager.getCollection(uri);
+        </pre>
+<p>
+          In the XML:DB API collections are retrieved by calling
+          <span class="codefrag">getCollection</span> 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
+          <span class="codefrag">xmldb:</span> and be followed by a database specific database
+          name, <span class="codefrag">xindice:</span> 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 <span class="codefrag">db</span>. 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>
+<pre class="code">
+  xindice:///db/news
+  xindice:///db2/news
+        </pre>
+<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 <span class="codefrag">XPathQueryService</span>
+          service for that collection.
+        </p>
+<pre class="code">
+String xpath = "//person[fname='John']";
+XPathQueryService service =
+(XPathQueryService) col.getService("XPathQueryService", "1.0");
+ResourceSet resultSet = service.query(xpath);
+        </pre>
+<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 <span class="codefrag">XPathQueryService</span> 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
+          <span class="codefrag">XPathQueryService</span> 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
+          <span class="codefrag">XPathQueryService</span> defines a method
+          <span class="codefrag">query()</span> that takes an XPath string as an argument.
+          Different services will define different sets of methods.
+        </p>
+<p>
+          Now that we have an <span class="codefrag">XPathQueryService</span> reference
+          and have called the <span class="codefrag">query()</span> method we get a
+          <span class="codefrag">ResourceSet</span> 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>
+<pre class="code">
+ResourceIterator results = resultSet.getIterator();
+while (results.hasMoreResources()) {
+    Resource res = results.nextResource();
+    System.out.println((String) res.getContent());
+}
+        </pre>
+<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 <span class="codefrag">getContentAsDom()</span> 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>
+<pre class="code">
+finally {
+    if (col != null) {
+        col.close();
+    }
+}
+        </pre>
+<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>
+<a name="N101E1"></a><a name="Accessing+Xindice+Remotely"></a>
+<h3 class="h4">Accessing Xindice Remotely</h3>
+<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
+          <span class="codefrag">xmldb:xindice://localhost:8888</span>.
+          To access the collection /db/addressbook on host xml.apache.org port
+          8000 the URI would look something like this
+          <span class="codefrag">xmldb:xindice://xml.apache.org:8000/db/addressbook</span>. 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
+          <span class="codefrag">/xindice</span> servlet context. To do this, you just need to rename
+          Xindice WAR file to <span class="codefrag">xindice.war</span>, and deploy this renamed WAR
+          file. Alternatively, you need to specify system property
+          <span class="codefrag">xindice.xmlrpc.service-location</span>, or set property
+          <span class="codefrag">service-location</span> on the <span class="codefrag">Database</span> XML:DB object
+          right after its creation.
+        </p>
+</div>
+    
+<a name="N10204"></a><a name="Managing+Documents"></a>
+<h2 class="h3">Managing Documents</h2>
+<div class="section">
+<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>
+<a name="N10210"></a><a name="Creating+a+Collection"></a>
+<h3 class="h4">Creating a Collection</h3>
+<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 <span class="codefrag">CollectionManager</span> 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
+          <span class="codefrag">org/apache/xindice/tools/commands</span>.
+        </p>
+<p>
+          The collection we want to create will be named
+          <span class="codefrag">mycollection</span> and will be a child of the root
+          collection.
+        </p>
+<a name="N10225"></a><a name="Creating+a+Collection-N10225"></a>
+<h4>Creating a Collection</h4>
+<pre class="code">
+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 =
+      "&lt;collection compressed=\"true\" " +
+      "            name=\"" + collectionName + "\"&gt;" +
+      "   &lt;filer class=\"org.apache.xindice.core.filer.BTreeFiler\"/&gt;" +
+      "&lt;/collection&gt;";
+
+    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();
+    }
+  }
+}
+}
+          </pre>
+<p>
+          With this example you can see a basic example of how to create the
+          <span class="codefrag">CollectionManager</span> 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
+          <span class="codefrag">createCollection</span> 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>
+<a name="N1023D"></a><a name="Working+with+Documents"></a>
+<h3 class="h4">Working with Documents</h3>
+<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>
+<a name="N10249"></a><a name="Example+Document"></a>
+<h4>Example Document</h4>
+<pre class="code">
+  &lt;person&gt;
+    &lt;fname&gt;John&lt;/fname&gt;
+    &lt;lname&gt;Smith&lt;/lname&gt;
+    &lt;phone type="work"&gt;563-456-7890&lt;/phone&gt;
+    &lt;phone type="home"&gt;534-567-8901&lt;/phone&gt;
+    &lt;email type="home"&gt;jsmith@somemail.com&lt;/email&gt;
+    &lt;email type="work"&gt;john@lovesushi.com&lt;/email&gt;
+    &lt;address type="home"&gt;34 S. Colon St.&lt;/address&gt;
+    &lt;address type="work"&gt;9967 W. Shrimp Ave.&lt;/address&gt;
+  &lt;/person&gt;
+          </pre>
+<p>
+          If we store this example XML into a file we can then load it into
+          our addressbook collection using a simple program.
+        </p>
+<a name="N10257"></a><a name="Adding+an+XML+File+to+the+Database"></a>
+<h4>Adding an XML File to the Database</h4>
+<pre class="code">
+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);
+}
+}
+          </pre>
+<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>
+<pre class="code">
+XMLResource document = (XMLResource) col.createResource(null, "XMLResource");
+document.setContentAsDOM(doc); // doc is a DOM document
+col.storeResource(document);
+        </pre>
+<p>
+          The only difference here is that you must have the document as a DOM
+          Document already and then call <span class="codefrag">setContentAsDOM()</span>. 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>
+<a name="N10278"></a><a name="Retrieving+an+XML+Document+from+the+Database"></a>
+<h4>Retrieving an XML Document from the Database</h4>
+<pre class="code">
+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();
+    }
+  }
+}
+}
+          </pre>
+<a name="N10283"></a><a name="Deleting+an+XML+Document+from+the+Database"></a>
+<h4>Deleting an XML Document from the Database</h4>
+<pre class="code">
+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();
+    }
+  }
+}
+}
+          </pre>
+</div>
+    
+<a name="N10290"></a><a name="Using+XPath+to+Query+the+Database"></a>
+<h2 class="h3">Using XPath to Query the Database</h2>
+<div class="section">
+<a name="N10296"></a><a name="Introduction"></a>
+<h3 class="h4">Introduction</h3>
+<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>
+<a name="N102A0"></a><a name="Using+the+XML%3ADB+Java+API"></a>
+<h3 class="h4">Using the XML:DB Java API</h3>
+<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 <span class="codefrag">queryResource()</span> method and to query
+          an entire collection you use the <span class="codefrag">query()</span> method.
+        </p>
+<a name="N102AF"></a><a name="Querying+with+XPath"></a>
+<h4>Querying with XPath</h4>
+<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>
+<pre class="code">
+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();
+    }
+  }
+}
+}
+          </pre>
+<p>TODO: cover namespace support</p>
+</div>
+    
+<a name="N102C5"></a><a name="Using+XUpdate+to+Modify+the+Database"></a>
+<h2 class="h3">Using XUpdate to Modify the Database</h2>
+<div class="section">
+<a name="N102CB"></a><a name="Introduction-N102CB"></a>
+<h3 class="h4">Introduction</h3>
+<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
+          <a href="http://xmldb-org.sourceforge.net/xupdate/xupdate-wd.html">
+          XUpdate working draft</a> 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
+          <a href="http://www.infozone-group.org/">Infozone Group</a>.
+        </p>
+<p>
+          The general model around XUpdate is to use an
+          <span class="codefrag">xupdate:modifications</span>
+          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>
+<a name="N102E8"></a><a name="Basic+XUpdate+Insert+Command"></a>
+<h4>Basic XUpdate Insert Command</h4>
+<pre class="code">
+&lt;xupdate:modifications version="1.0"
+  xmlns:xupdate="http://www.xmldb.org/xupdate"&gt;
+
+&lt;xupdate:insert-after select="/addresses/address[1]" &gt;
+
+&lt;xupdate:element name="address"&gt;
+&lt;xupdate:attribute name="id"&gt;2&lt;/xupdate:attribute&gt;
+&lt;fullname&gt;John Smith&lt;/fullname&gt;
+&lt;born day='2' month='12' year='1974'/&gt;
+&lt;country&gt;Germany&lt;/country&gt;
+&lt;/xupdate:element&gt;
+
+&lt;/xupdate:insert-after&gt;
+&lt;/xupdate:modifications&gt;
+          </pre>
+<a name="N102F4"></a><a name="XUpdate+Commands"></a>
+<h3 class="h4">XUpdate Commands</h3>
+<ul>
+          
+<li>
+            
+<span class="codefrag">xupdate:insert-before</span> - Inserts a new node in document order before the selected node.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:insert-after</span> - Inserts a new node in document order after the selected node.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:update</span> - Replaces all child nodes of the selected node with the specified nodes.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:append</span> - Appends the specified node to the content of the selected node.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:remove</span> - Remove the selected node
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:rename</span> - Renames the selected node
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:variable</span> - Defines a variable containing a node list that can be reused in later operations.
+          </li>
+        
+</ul>
+<a name="N10328"></a><a name="XUpdate+Node+Construction"></a>
+<h3 class="h4">XUpdate Node Construction</h3>
+<ul>
+          
+<li>
+            
+<span class="codefrag">xupdate:element</span> - Creates a new element in the document.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:attribute</span> - Creates a new attribute node
+            associated with an <span class="codefrag">xupdate:element</span>.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:text</span> - Creates a text content node in the document.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:processing-instruction</span> - Creates a
+            processing instruction node in the document.
+          </li>
+          
+<li>
+            
+<span class="codefrag">xupdate:comment</span> - Creates a new comment node in the
+            document.
+          </li>
+        
+</ul>
+<a name="N10353"></a><a name="Using+the+XML%3ADB+API+for+XUpdate"></a>
+<h3 class="h4">Using the XML:DB API for XUpdate</h3>
+<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
+           <span class="codefrag">updateResource()</span> method and to apply the updates
+           to an entire collection you use the <span class="codefrag">update()</span> 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
+           <span class="codefrag">/person/phone[@type = 'home']</span>
+           and then adds a new entry after all elements that match the XPath
+           <span class="codefrag">/person/phone[@type = 'work']</span>
+         
+</p>
+<a name="N1036B"></a><a name="Using+XUpdate+to+modify+the+database"></a>
+<h4>Using XUpdate to modify the database</h4>
+<pre class="code">
+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 = "&lt;xu:modifications version=\"1.0\"" +
+      "      xmlns:xu=\"http://www.xmldb.org/xupdate\"&gt;" +
+      "   &lt;xu:remove select=\"/person/phone[@type = 'home']\"/&gt;" +
+      "   &lt;xu:update select=\"/person/phone[@type = 'work']\"&gt;" +
+      "       480-300-3003" +
+      "   &lt;/xu:update&gt;" +
+      "&lt;/xu:modifications&gt;";
+
+    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();
+    }
+  }
+}
+}
+           </pre>
+</div>
+     
+<a name="N10378"></a><a name="Storing+metadata"></a>
+<h2 class="h3">Storing metadata</h2>
+<div class="section">
+<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>
+<pre class="code">
+  &lt;meta&gt;
+    &lt;system type="doc"&gt;
+      &lt;attr name="created" value="10128378882" /&gt;
+      &lt;attr name="modified" value="10128378882" /&gt;
+    &lt;/system&gt;
+    &lt;attrs&gt;
+      &lt;attr name="key" value="value"/&gt;
+      &lt;attr name="foo" value="bar"/&gt;
+    &lt;/attrs&gt;
+    &lt;custom&gt;
+      &lt;myspecial&gt;
+        any &lt;valid /&gt; xml
+      &lt;/myspecial&gt;
+    &lt;/custom&gt;
+  &lt;/meta&gt;
+       </pre>
+<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>
+<a name="N10391"></a><a name="Enabling+metadata"></a>
+<h3 class="h4">Enabling metadata</h3>
+<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>
+<pre class="code">
+  Dec 30, 2002 10:21:51 AM org.apache.xindice.core.Database setConfig
+  INFO: Meta information initialized
+         </pre>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">
+           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.
+         </div>
+</div>
+<a name="N103A5"></a><a name="Using+metadata"></a>
+<h3 class="h4">Using metadata</h3>
+<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>
+<a name="N103AF"></a><a name="Sample+metadata+code"></a>
+<h3 class="h4">Sample metadata code</h3>
+<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>
+<pre class="code">
+#!/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-&gt;new('url'=&gt;$url,'debug'=&gt;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-&gt;{'message'} = 'CreateCollection';
+$args-&gt;{'collection'} = '/db';
+$args-&gt;{'name'} = $colname;
+$result = $server-&gt;call('run',$args);
+
+## now get the collection's meta
+$args = {};
+$args-&gt;{'message'} = 'GetCollectionMeta';
+$args-&gt;{'collection'} = '/db/'.$colname;
+$result = $server-&gt;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=&lt;&lt;EOF;
+&lt;?xml version="1.0"?&gt;
+    &lt;meta&gt;
+        &lt;!-- since the system is controlled by
+          Xindice, this doesn't matter...
+        --&gt;
+        &lt;system type="col"&gt;
+            &lt;attr name="created" value="1" /&gt;
+            &lt;attr name="modified" value="5" /&gt;
+        &lt;/system&gt;
+        &lt;attrs&gt;
+            &lt;attr name="test" value="added" /&gt;
+        &lt;/attrs&gt;
+        &lt;custom&gt;
+              &lt;rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"&gt;
+                  &lt;test&gt;the rdf example&lt;/test&gt;
+              &lt;/rdf:RDF&gt;
+        &lt;/custom&gt;
+    &lt;/meta&gt;
+EOF
+$args = {};
+$args-&gt;{'message'} = 'SetCollectionMeta';
+$args-&gt;{'collection'} = '/db/'.$colname;
+$args-&gt;{'meta'} = $meta;
+$result = $server-&gt;call('run',$args);
+
+## this should print out the xml for the
+## collection's revised metadata.
+print Dumper($result);
+         </pre>
+<div class="fixme">
+<div class="label">Fixme (dviner)</div>
+<div class="content">
+         Make this example java instead of perl.
+       </div>
+</div>
+<div class="note">
+<div class="label">Note</div>
+<div class="content">Metadata is currently only exposed in the XML-RPC accessor.</div>
+</div>
+</div>
+    
+<a name="N103C8"></a><a name="Example+Application"></a>
+<h2 class="h3">Example Application</h2>
+<div class="section">
+<a name="N103CE"></a><a name="Address+Book"></a>
+<h3 class="h4">Address Book</h3>
+<p>
+          The address book example is a simple servlet based application
+          constructued using Xindice. For more information on this example look
+          in the <span class="codefrag">Xindice/java/examples/addressbook</span> directory.
+        </p>
+<p>
+          TODO: Add more detail about building servlet applications.
+        </p>
+</div>
+
+    
+<a name="N103DF"></a><a name="Experimental+Features"></a>
+<h2 class="h3">Experimental Features</h2>
+<div class="section">
+<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>
+</div>
+  
+<p align="right">
+<font size="-2">by&nbsp;Kimbro Staken,&nbsp;Dave Viner</font>
+</p>
+<span class="version">
+          version 598114</span>
+</div>
+<!--+
+    |end content
+    +-->
+<div class="clearboth">&nbsp;</div>
+</div>
+<div id="footer">
+<!--+
+    |start bottomstrip
+    +-->
+<div class="lastmodified">
+<script type="text/javascript"><!--
+document.write("Last Published: " + document.lastModified);
+//  --></script>
+</div>
+<div class="copyright">
+        Copyright &copy;
+         2001-2007 The Apache Software Foundation.</div>
+<!--+
+    |end bottomstrip
+    +-->
+</div>
+</body>
+</html>

Propchange: xml/site/targets/xindice/1.1/guide-developer.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: xml/site/targets/xindice/1.1/guide-developer.html
------------------------------------------------------------------------------
    svn:keywords = Id Revision Author Date

Added: xml/site/targets/xindice/1.1/guide-developer.pdf
URL: http://svn.apache.org/viewvc/xml/site/targets/xindice/1.1/guide-developer.pdf?rev=602294&view=auto
==============================================================================
Binary file - no diff available.

Propchange: xml/site/targets/xindice/1.1/guide-developer.pdf
------------------------------------------------------------------------------
    svn:mime-type = application/pdf



---------------------------------------------------------------------
To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: general-cvs-help@xml.apache.org


Mime
View raw message