You are viewing a plain text version of this content. The canonical link for it is here.
Posted to xindice-dev@xml.apache.org by vl...@apache.org on 2002/11/17 09:16:04 UTC
cvs commit: xml-xindice/src/documentation/content/xdocs/dev book.xml guide-administrator.xml guide-commandline.xml guide-developer.xml guide-user.xml index.xml news.xml
vladimir 2002/11/17 00:16:03
Added: src/documentation/content/xdocs/dev book.xml
guide-administrator.xml guide-commandline.xml
guide-developer.xml guide-user.xml index.xml
news.xml
Log:
initial import
Revision Changes Path
1.1 xml-xindice/src/documentation/content/xdocs/dev/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "book-cocoon-v10.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2002/11/17 08:16:03 $
- Author: Vladimir R. Bossicard (vladimir@apache.org)
-->
<book software="Xindice"
title="Xindice development zone"
copyright="2002 The Apache Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink">
<menu label="Project">
<menu-item label="Overview" href="index.html"/>
<menu-item label="News" href="news.html"/>
</menu>
<menu label="Documentation">
<menu-item label="Administrator Guide" href="guide-administrator.html"/>
<menu-item label="User Guide" href="guide-user.html"/>
<menu-item label="Developer Guide" href="guide-developer.html"/>
<menu-item label="Commandline Tool Guide" href="guide-commandline.html"/>
</menu>
</book>
1.1 xml-xindice/src/documentation/content/xdocs/dev/guide-administrator.xml
Index: guide-administrator.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2002/11/17 08:16:03 $
- Author: Kimbro Staken (kstaken@xmldatabases.org)
-->
<document>
<header>
<title>Administrator guide</title>
<authors>
<person id="ks" name="Kimbro Staken" email=""/>
</authors>
<notice/>
<abstract/>
</header>
<body>
<warning>This documentation is a work in progress and is only applicable to the CVS version of Xindice. There is absolutely no guarantee that this information is accurate. You have been warned.
</warning>
<section>
<title>Database Administration</title>
<p>
Database administration of Xindice is accomplished from the command
line using the
<code>xindice</code> command. This command
allows you to view and alter the database configuration on the fly
on a running system. A complete list of available commands and more
detail about each command can be found in the
<link href="guide-tools.html">Command Line Tools Reference Guide</link>.
</p>
<section>
<title>Managing Collections</title>
<p/>
<section>
<title>Adding a Collection</title>
<p>
Adds a collection named products under the collection /db/data.
</p>
<source>xindice add_collection -c /db/data -n products</source>
</section>
<section>
<title>Deleting a Collection</title>
<p>Deletes the collection named products from the collection /db/data.</p>
<source>xindice delete_collection -c /db/data/products</source>
</section>
<section>
<title>Listing the Collections</title>
<p>This will display a list of all child collections under the collection /db/data</p>
<source>xindice list_collections -c /db/data</source>
</section>
</section>
<section>
<title>Managing Indexes</title>
<p>
The Xindice indexing system allows you to define indexes to speed
performance on commonly used XPath queries. If no indexes are defined
you can still execute queries but performance will suffer
because the
query engine will need to scan the entire collection to create the
result node-set.
</p>
<p>
Indexes can be added using the
<code>xindice</code>
command.
</p>
<section>
<title>Adding an Index</title>
<p>
Using this simple XML file you might want to index the product_id
element because searches for products by product_id are common.
</p>
<source><![CDATA[
<?xml version="1.0"?>
<product>
<product_id>120320</product_id>
<description>Glazed Ham</description>
</product>]]></source>
<p>
This can be accomplished by running the following command.
This will create an index named idindex on all product_id
elements in the collection /db/data/catalog.
</p>
<source><![CDATA[
xindice add_indexer -c /db/data/catalog -n idindex -p product_id
]]></source>
<p>
Once this is done the query engine will now use this index to
help resolve XPath queries that involve restriction on the
value of the product_id element.
</p>
</section>
<p>
The -p parameter to the command specifies the pattern to use in the
index. These patterns are used by the Indexing system to determine
best-fit and match-based Indexers for queries and index updating.
The pattern used
MUST resemble the following scheme.
</p>
<source>
<![CDATA[
Pattern Description
=========== ====================================================
elem The value of the named element
elem@attr The value of the attribute for the named element
* The value for all elements
*@attr The value of the named attribute for all elements
elem@* The value of all attributes for the named element
*@* The value of all attributes for all elements
]]></source>
<p>
Note: In order to index a namespace other than the default
namespace, you must prepend your pattern components with a
URI placed in square brackets. Example:
</p>
<source><![CDATA[
[http://www.world.org/People]person
*@[http://www.world.org/People]id
[http://www.world.org/People]person@[http://www.world.org/People]id
]]></source>
<p>
Do not include a prefix in these patterns, as the indexing
system, like most Namespace processing applications, processes
namespaced elements and attributes independently of the prefix
that is used.
</p>
<section>
<title>Indexing both Elements and Attributes</title>
<p>
Because the patterns recognize either an element or an attribute,
and not both, in order to index all element and attribute values
in a collection, you'd have to create two index entries. The *
pattern will index all elements and the *@* pattern will index
all attributes of all elements.
</p>
<source><![CDATA[
xindice add_collection_indexer -c /db/data/catalog -n idindex -p '*'
xindice add_collection_indexer -c /db/data/catalog -n idindex -p '*@*'
]]></source>
</section>
<p>
Excessive use of wildcard indexes can adversely affect the
performance of the indexing system. Best practice would be to use
specific element or attribute indexes whenever possible, and only
define wildcard indexes when it is absolutely necessary.
</p>
</section>
</section>
<section>
<title>Server Administration</title>
<section>
<title>Starting the Server</title>
<p>
The server must be started from within the Xindice directory.
A future revision of the server will fix this limitation.
</p>
<section>
<title>Starting the Server on UNIX</title>
<source><![CDATA[
cd Xindice
./start
]]></source>
</section>
<section>
<title>Starting the Server on Windows</title>
<source><![CDATA[
cd Xindice
startup
]]></source>
</section>
</section>
<section>
<title>Stopping the Server</title>
<p>
The Xindice server can be easily shutdown from the command line. You
must provide the name of the server instance to shutdown.
</p>
<section>
<title>Stopping the Server</title>
<p>
This example assumes that the Xindice/bin directory
is in your path.
</p>
<source><![CDATA[
xindice shutdown -c /db
]]></source>
</section>
</section>
<section>
<title>Backing up Your Data</title>
<p>
Currently backing up Xindice consists of simply shutting down the
server and copying the
entire contents of the Xindice/db directory to the backup
media.
</p>
<section>
<title>Backing up the server</title>
<p>
This example assumes that the Xindice/bin directory
is in your path.
</p>
<source><![CDATA[
cd Xindice
xindice shutdown
cp -pr db /backup/db
./start
]]></source>
</section>
<section>
<title>Restoring the Data</title>
<p>
Restoring the data is simply removing the current database and
reversing the backup process.
This example assumes that the Xindice/bin directory
is in your path.
</p>
<source><![CDATA[
cd Xindice
xindice shutdown
rm -rf db
cp -pr /backup/db db
./start
]]></source>
</section>
</section>
<section>
<title>Exporting the Contents of the Database</title>
<p>
Xindice includes tools to export data to a directory hierarchy and to also import
data from a directory hierarchy. Each directory in the hierachy corresponds to a
collection in Xindice. Each XML document is stored in a separate file named with
the key from the database.
</p>
<section>
<title>Exporting the database</title>
<p>
This example assumes that the Xindice/bin directory
is in your path.
</p>
<source><![CDATA[
xindice export -c /db/root -f /path/to/data
]]></source>
<p>
The entire contents of the collection /db/root will be exported to the
directory /path/to/data.
</p>
</section>
<section>
<title>Importing the database</title>
<p>
This example assumes that the Xindice/bin directory
is in your path.
</p>
<source><![CDATA[
xindice import -c /db -f /path/to/data/root
]]></source>
<p>
Each directory under /path/to/data will be used to create a collection and
all XML documents in the hierarchy will be imported in to the database. You
can also restrict the documents that are imported by adding -i and the
extension of the files you want to import.
</p>
</section>
</section>
</section>
</body>
</document>
1.1 xml-xindice/src/documentation/content/xdocs/dev/guide-commandline.xml
Index: guide-commandline.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2002/11/17 08:16:03 $
- Author: Kimbro Staken (kstaken@xmldatabases.org)
-->
<document>
<header>
<title>Commandline Tool Guide</title>
<authors>
<person id="jk" name="Jay Kalafus" email=""/>
<person id="ks" name="Kimbro Staken" email=""/>
</authors>
<notice/>
<abstract/>
</header>
<body>
<warning>This documentation is a work in progress and is only applicable to the CVS version of Xindice. There is absolutely no guarantee that this information is accurate. You have been warned.
</warning>
<section>
<title>Collection Management Commands</title>
<section>
<title>Adding a Collection</title>
<p>
Adds a new collection to the database. When adding a collection
under an existing collection hierarchy all parent collections must
already exist in the database.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice add_collection-c
(or context)
-n
(or name)
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>add_collection</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>ac</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>Admin</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to create the new
collection.
</li>
<li>
<code>-n</code> The name of the collection to create
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Creating a Top Level Collection</title>
<source><![CDATA[
xindice add_collection -c /db -n pebbles
]]></source>
</section>
<section>
<title>Creating a Sub Collection Under an Existing Collection</title>
<source><![CDATA[
xindice add_collection -c /db/pebbles -n boulder
]]></source>
</section>
</section>
<section>
<title>Deleting a Collection</title>
<p>
Deletes a collection or subcollection from the database. If deleting a collection that has subcollections and documents
they will also be deleted.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice delete_collection-c
(or context)
-n
(or name)
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>delete_collection</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>dc</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>Admin</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to delete the collection.
</li>
<li>
<code>-n</code> The name of the collection to delete.
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Deleting a Top Level Collection</title>
<source><![CDATA[
xindice delete_collection -c /db -n pebbles
]]></source>
</section>
<section>
<title>Deleting a Sub Collection</title>
<source><![CDATA[
xindice delete_collection -c /db/pebbles -n boulder
]]></source>
</section>
</section>
<section>
<title>List Collections</title>
<p>
List all collections under the collection context given. If no collection is given then the root
collection will be asumed.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice list_collections
[-c
(or context)
]
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>list_collections</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>lc</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which all sub collections are listed
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Listing the Top Level Collections</title>
<source><![CDATA[
xindice list_collections -c /db
]]></source>
</section>
<section>
<title>Listing a Sub Collection</title>
<source><![CDATA[
xindice list_collections -c /db/pebbles
]]></source>
</section>
</section>
</section>
<section>
<title>Document Management Commands</title>
<section>
<title>Adding a Document</title>
<p>
Adds a document to a collection or nested collection. Adding a document requires two parameters -
the collection it will be stored under, and the file path to the document. If a document key
is not provided an auto-generated system key will be used for the document. Documents cannot be added to
collections that do not already exist. When entering the file path be sure to include the path and
file extension.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice add_document-c
(or context)
-f
(or file path)
[-n
(or key to assign to document)
]
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>add_document</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>ad</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to add the document
</li>
<li>
<code>-f</code> The complete file path to the document being added
</li>
<li>
<code>-n</code> The key to assign to the document
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Adding a document to a collection with a key of "stones"</title>
<source><![CDATA[
xindice add_document -c /db/pebbles -f /tmp/stones.xml -n stones
]]></source>
</section>
<section>
<title>Adding a document to the root collection with an automatically generated key</title>
<source><![CDATA[
xindice add_document -c /db -f /tmp/bookmarks.xml
]]></source>
</section>
</section>
<section>
<title>Adding Multiple Documents</title>
<p>
Adds multiple documents to a collection or a nested collection. This command requires two arguments: the
collection to store the documents under and the directory path containing the documents. Documents can be added
to collections as well as subcollections as long as they exist. Documents added will be assigned their file name
as the document key. The optional "extension" parameter can be used to import documents with a certain file extension.
Document keys are shown as they are created.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice add_multiple_documents-c
(or context)
-f
(or Directory to use )
[-e
(or file extenstion )
]
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>add_multiple_documents</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>addmultiple</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to add the documents
</li>
<li>
<code>-f</code> The path to the directory to import documents from
</li>
<li>
<code>-e</code> The file extension to use when importing documents
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Adding all files from a directory to a collection</title>
<source><![CDATA[
xindice add_multiple_documents -c /db/pebbles -f /tmp/mydocs
]]></source>
</section>
<section>
<title>Adding all files from a directory with an extension of ".xml" </title>
<source><![CDATA[
xindice add_multiple_documents -c /db/pebbles -f /tmp/mydocs -e xml
]]></source>
</section>
</section>
<section>
<title>Deleting a Document</title>
<p>
Deletes an existing document from a collection or nested collection within the database.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice delete_document-c
(or context)
-n
(or document key)
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>delete_document</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>dd</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to delete the document
</li>
<li>
<code>-n</code> The key of the document to be deleted
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Deleting a Document from a collection</title>
<source><![CDATA[
xindice delete_document -c /db/pebbles -n stones
]]></source>
</section>
</section>
<section>
<title>Retrieving a Document</title>
<p>
Retrieves an existing document from a collection or nested collection within the database. The complete path where
the document will be stored is required. If the file path passed in does not exist, it will be created .
If the file argument given already exists, it will be overwritten automatically.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice retrieve_document-c
(or context)
-n
(or document key)
-f
(or file path and name )
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>retrieve_document</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>rd</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to retrieve the document
</li>
<li>
<code>-n</code> The key of the document to be retrieved
</li>
<li>
<code>-f</code> The file path to store the document under
</li>
<li>
<code>-v</code> Show verbose output
</li>
<li>
<code>-u</code> The URI for the Xindice host to use.
http://host:[port]
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Retrieving a document from a collection</title>
<source><![CDATA[
xindice retrieve_document -c /db/pebbles -n stones -f /tmp/stones.xml
]]></source>
</section>
</section>
<section>
<title>Importing a Directory Tree</title>
<p>
Adds multiple documents into a collection or a nested collection within the database, copying the directory structure into
the database as collections. This command is designed to take a directory and create a collection from it's name.
Directories under the directory will also be created as collections, duplicating the directory tree. The files within the
specified directory are converted into Documents and then stored into the newly created collection with their filenames
as the document keys. The optional "extension" parameter can be used to only import documents with a certain file extension.
If the collection name used already exists it will be overwritten. Collection and document keys will are shown as they are created.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice import-c
(or context)
-f
(or file path and name )
[-e
(or file extenstion )
]
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>import</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>import</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>Admin</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to import the documents
</li>
<li>
<code>-f</code> The path to the documents being added
</li>
<li>
<code>-e</code> The file extension to use when importing documents
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Importing all directories and documents</title>
<source><![CDATA[
xindice import -c /db/pebbles -f /tmp/flintstones
]]></source>
</section>
<section>
<title>Importing all directories and documents with an extension of ".xml" </title>
<source><![CDATA[
xindice import -c /db/pebbles -f /tmp/flintstones -e xml
]]></source>
</section>
</section>
<section>
<title>Exporting a Directory Tree</title>
<p>
Creates an identical directory tree from a collection including any subcollections.
The directory tree will be created starting at the directory passed in as an argument.
This command requires the collection which you are eporting and the directory to export to as arguments.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice export-c
(or context)
-f
(or directory path)
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>export</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>export</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to export the document tree
</li>
<li>
<code>-f</code> The directory to create the collection structure under
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Creating a directory tree indentical to a collection</title>
<source><![CDATA[
xindice export -c /db/pebbles -f /tmp/pebbles
]]></source>
</section>
</section>
</section>
<!--chapter>
<docinfo>
<title>XMLObject Management Actions</title>
</docinfo>
<sect1>
<title>Adding a XMLObject</title>
<para>
Adds a new XMLObject or nested XMLObject to the database. Adding an XMLObject requires
an implementing class and a name. In order to add the XMLObject the collection that it is being added
to must already exist. to sucessfully complete this topertation, the implementing class must be in the server's classpath.
</para>
<bridgehead renderas="sect2">Summary:</bridgehead>
<cmdsynopsis>
<command>xindice add_xmlobject</command>
<arg choice="req">-c <replaceable>context</replaceable></arg>
<arg choice="req">-i <replaceable>implementing class</replaceable></arg>
<arg choice="req">-n <replaceable>object name </replaceable></arg>
<arg choice="opt">-v <replaceable></replaceable></arg>
</cmdsynopsis>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row><entry>Action:</entry><entry><command>add_xmlobject </command></entry></row>
<row><entry>Abberviated-Action:</entry><entry><command>ao </command></entry></row>
<row><entry>Access Level:</entry><entry>Admin </entry></row>
</tbody>
</tgroup>
</informaltable>
<bridgehead renderas="sect2">Parameters:</bridgehead>
<simplelist>
<member>
<command>-c</command> The collection context under which to add the XMLObject
</member>
<member>
<command>-i</command> The fully qualified class name for the implementing class
</member>
<member>
<command>-n</command> The name to assign to the XMLObject
</member>
<member>
<command>-v</command> Show verbose output
</member>
</simplelist>
<bridgehead renderas="sect2">Examples:</bridgehead>
<example>
<title>Create a XMLObject in the pebbles collection </title>
<screen>
xindice add_xmlobject -c /db/pebbles -i example.XmlRockObject -n rockXMLObject
</screen>
</example>
<example>
<title>Create a XMLObject in a sub collection</title>
<screen>
xindice add_xmlobject -c /db/pebbles/boulder -i example.XmlRockObject -n rockXMLObject
</screen>
</example>
</sect1>
<sect1>
<title>Deleting a XMLObject</title>
<para>
Deletes an XMLObject or nested XMLObject from the database. Deleting an XMLObject requires the collection name and the
XMLObject name.
</para>
<bridgehead renderas="sect2">Summary:</bridgehead>
<cmdsynopsis>
<command>xindice delete_xmlobject</command>
<arg choice="req">-c <replaceable>context</replaceable></arg>
<arg choice="req">-n <replaceable>name </replaceable></arg>
<arg choice="opt">-v <replaceable></replaceable></arg>
</cmdsynopsis>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row><entry>Action:</entry><entry><command>delete_xmlobject </command></entry></row>
<row><entry>Abberviated-Action:</entry><entry><command>do </command></entry></row>
<row><entry>Access Level:</entry><entry>Admin </entry></row>
</tbody>
</tgroup>
</informaltable>
<bridgehead renderas="sect2">Parameters:</bridgehead>
<simplelist>
<member>
<command>-c</command> The collection context under which to delete the XMLObject
</member>
<member>
<command>-n</command> The name of the XMLObject to delete
</member>
<member>
<command>-v</command> Show verbose output
</member>
</simplelist>
<bridgehead renderas="sect2">Examples:</bridgehead>
<example>
<title>Delete an XMLObject in the pebbles collection </title>
<screen>
xindice delete_xmlobject -c /db/pebbles -n rockXMLObject
</screen>
</example>
<example>
<title>Delete an XMLObject from the boulder sub collection</title>
<screen>
xindice delete_xmlobject -c /db/pebbles/boulder -n rockXMLObject
</screen>
</example>
</sect1>
<sect1>
<title>Listing XMLObjects</title>
<para>
Lists all XMLObjects or nested XMLObjects in the database. The listing of XMLObjects works in a similar fashion to
listing collections.
</para>
<bridgehead renderas="sect2">Summary:</bridgehead>
<cmdsynopsis>
<command>xindice lists_xmlobjects</command>
<arg choice="req">-c <replaceable>context</replaceable></arg>
<arg choice="opt">-v <replaceable></replaceable></arg>
</cmdsynopsis>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row><entry>Action:</entry><entry><command>list_xmlobjects </command></entry></row>
<row><entry>Abberviated-Action:</entry><entry><command>lo </command></entry></row>
<row><entry>Access Level:</entry><entry>User </entry></row>
</tbody>
</tgroup>
</informaltable>
<bridgehead renderas="sect2">Parameters:</bridgehead>
<simplelist>
<member>
<command>-c</command> The collection context under which to list the XMLObjects
</member>
<member>
<command>-v</command> Show verbose output
</member>
</simplelist>
<bridgehead renderas="sect2">Examples:</bridgehead>
<example>
<title>List all XMLObjects in the pebbles collection </title>
<screen>
xindice list_xmlobjects -c /db/pebbles
</screen>
</example>
<example>
<title>List all XMLObjects in the boulder sub collection</title>
<screen>
xindice list_xmlobjects -c /db/pebbles/boulder
</screen>
</example>
</sect1>
<sect1>
<title>Invoke an XMLObject</title>
<para>
Allows the invocation of an XMLObject in the database.
This command requires two arguments - the collection
to invoke the object under and the URI for the XMLObject.
The URI given can be either relative or the absolute path.
(See the users guide for more information on URI's)
</para>
<bridgehead renderas="sect2">Summary:</bridgehead>
<cmdsynopsis>
<command>xindice invoke</command>
<arg choice="req">-c <replaceable>context</replaceable></arg>
<arg choice="req">-o <replaceable>object URI</replaceable></arg>
<arg choice="opt">-v <replaceable></replaceable></arg>
</cmdsynopsis>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row><entry>Action:</entry><entry><command>invoke </command></entry></row>
<row><entry>Abberviated-Action:</entry><entry><command>invoke </command></entry></row>
<row><entry>Access Level:</entry><entry>User </entry></row>
</tbody>
</tgroup>
</informaltable>
<bridgehead renderas="sect2">Parameters:</bridgehead>
<simplelist>
<member>
<command>-c</command> The collection context under which to invoke the XMLObject
</member>
<member>
<command>-o</command> The XMLObject that is being invoked
</member>
<member>
<command>-v</command> Show verbose output
</member>
</simplelist>
<bridgehead renderas="sect2">Examples:</bridgehead>
<example>
<title> Invoke the rockXMLObject in the pebbles collection</title>
<screen>
xindice invoke -c /db/pebbles -o rockXMLObject
</screen>
</example>
<example>
<title>
Invoke a rockXMLObject with a method named crush that takes a
name parameter named rock
</title>
<screen>
xindice invoke -c /db/pebbles -o rockXMLObject/crush?rock=boulder
</screen>
</example>
</sect1>
</chapter-->
<section>
<title>Collection Indexer Actions</title>
<section>
<title>Adding a Collection Indexer</title>
<p>
Adds a new collection index or nested collection index to the database. In order to add the collection index,
the collection it is being added to must already exist. This command allows you to supply optional parameters
for setting the index page size, setting the maximum key size for the index, and the index data type.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice add_indexer-c
(or context)
-n
(or index name )
-p
(or index pattern)
[--pagesize
(or pagesize)
]
[--maxkeysize
(or max key size)
]
[-t
(or index type)
]
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>add_indexer</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>ai</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>Admin</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to add the indexer
</li>
<li>
<code>-n</code> The name of the index being added
</li>
<li>
<code>-p</code> The pattern used to create the index
</li>
<li>
<code>--maxkeysize</code> The MaxKeySize for the index ( default: 0 = none )
</li>
<li>
<code>--pagesize</code> The PageSize for the index ( default: 4096)
</li>
<li>
<code>-t</code>
The data type for the index to create. Possible values are:
<code><![CDATA[ string Non-normalized string value
trimmed Normalized (whitespace stripped) string value
short 16-bit signed short integer
int 32-bit signed integer
long 64-bit signed integer
float 32-bit floating point value
double 64-bit floating point value (XPath number)
byte 8-bit signed byte
char 16-bit signed character
boolean 8-bit boolean value
name Store document keys that contain the pattern]]></code>
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>To create a collection index in the pebbles collection for docuemnts with a "rock" element</title>
<source><![CDATA[
xindice add_indexer -c /db/pebbles -n rockindex -p rock
]]></source>
</section>
<section>
<title>To create a collection index in the boulder sub collection for documents containing a rock elements with an attribute of "hard"</title>
<source><![CDATA[
xindice add_indexer -c /db/pebbles/boulder -n hardindex -p rock@type
]]></source>
</section>
</section>
<section>
<title>Deleting a Collection Indexer</title>
<p>
Deletes a collection index or a nested collection index from the database. Deleting an index requires the collection and index name.
If a collection index is deleted, the collection will still remain.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice delete_indexer-c
(or context)
-n
(or index name)
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>delete_indexer </code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>di </code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>Admin </td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to delete the index
</li>
<li>
<code>-n</code> The name of the indexer being deleted
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Delete a collecion index in the pebbles collection</title>
<source><![CDATA[
xindice delete_indexer -c /db/pebbles -n hardindex
]]></source>
</section>
</section>
<section>
<title>Listing Collection Indexers</title>
<p>
Lists all collection indexers or nested collection indexes in the database. The listing of indexes works
in a similar fashion to listing collections
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice list_indexers-c
(or context)
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>list_indexers</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>li</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>Admin</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to list the indexers
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>To list all collection indexes from the pebbles collection </title>
<source><![CDATA[
xindice list_indexers -c /db/pebbles
]]></source>
</section>
</section>
</section>
<section>
<title>Xpath Query Actions</title>
<section>
<title>Executing an Xpath Query against a Collection</title>
<p>
Execute an Xpath query against a collection or nested collection. The command requires two arguments : the collection to
query against and the query string to use.
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice xpath-c
(or context)
-q
(or query)
-s
(or prefix=namespace)
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>xpath</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>xpath</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-c</code> The collection context under which to execute the query
</li>
<li>
<code>-q</code> The query to execute against the collection
</li>
<li>
<code>-s</code> Semi-colon delimited list of namespaces for query in the form prefix=namespace-uri
</li>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>
Run an Xpath query against all documents in the pebbles collection with "rock" node that has the type
attribute = "hard"
</title>
<source><![CDATA[
xindice xpath -c /db/pebbles -q /rock[@type="hard"]
]]></source>
</section>
<section>
<title>
Run an Xpath query against all documents in the pebbles collection with "rock" node that has the type
attribute = "hard" when the rock element is in the namespace http://www.bedrock.com
</title>
<source><![CDATA[
xindice xpath -c /db/pebbles -s "br=http://www.bedrock.com" -q /br:rock[@type="hard"]
]]></source>
</section>
</section>
</section>
<section>
<title>Miscellaneous Actions</title>
<section>
<title>Shutting down the server</title>
<p>
Shutdown the Xindice server
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice shutdown
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>shutdown</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>shutdown</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>Admin</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Shutdown the server </title>
<source><![CDATA[
xindice shutdown
]]></source>
</section>
</section>
<section>
<title>Accessing online Help</title>
<p>
Show the online help
</p>
<section>
<title>Summary:</title>
</section>
<p>
<code>xindice help
[-v
(or )
]
</code>
</p>
<table>
<tr>
<td>Action:</td>
<td>
<code>help</code>
</td>
</tr>
<tr>
<td>Abberviated-Action:</td>
<td>
<code>help</code>
</td>
</tr>
<tr>
<td>Access Level:</td>
<td>User</td>
</tr>
</table>
<section>
<title>Parameters:</title>
</section>
<ul>
<li>
<code>-v</code> Show verbose output
</li>
</ul>
<section>
<title>Examples:</title>
</section>
<section>
<title>Show online Help</title>
<source><![CDATA[
xindice help
]]></source>
</section>
</section>
</section>
</body>
</document>
1.1 xml-xindice/src/documentation/content/xdocs/dev/guide-developer.xml
Index: guide-developer.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2002/11/17 08:16:03 $
- Author: Kimbro Staken (kstaken@xmldatabases.org)
-->
<document>
<header>
<title>Developer Guide</title>
<authors>
<person id="ks" name="Kimbro Staken" email=""/>
</authors>
<notice/>
<abstract/>
</header>
<body>
<warning>This documentation is a work in progress and is only applicable to the CVS version of Xindice. There is absolutely no guarantee that this information is accurate. You have been warned.
</warning>
<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>
XML:DB XML Database API used to develop Xindice applications
in Java. This is the primary API used to develop
applications and will be the API given the most coverage in
this manual. The XML:DB API is built on top of the Xindice
CORBA API. 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>
CORBA API used when accessing Xindice from a language other
then Java. The CORBA API is built on top of the Core Server
API. It is likely that the CORBA API will be replaced with a
new network API in a later version of Xindice.
</li>
<li>
Core Server API is the internal Java API of the core
database engine. This API is used to build the CORBA API and
is also used when writing XMLObject server extensions. This is
the lowest level API and is only available to software running
in the same Java VM as the database engine itself. the most
common use of this API is in developing XMLObject server
extensions.
</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://www.xmldb.org">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://www.xmldb.org/">http://www.xmldb.org</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 CORBA API that is used to
implement the XML:DB API. The CORBA API will mainly be of
interest to those who want to access Xindice from a language other
then Java. Any language that supports a CORBA binding should be
able to utilize the services of the Xindice server via the CORBA
API. This document
does not cover development with the CORBA 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 CORBA 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. <!-- that is used when
writing XMLObject server extensions. This API is the lowest level
API available for the Xindice server and will be covered briefly
when looking at the development of XMLObjects.
-->
</p>
</section>
<section>
<title>Introducing the XML:DB XML Database API</title>
<p>
XML:DB API is being developed by the
<link href="http://www.xmldb.org">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 Core Level 1 implementation plus implementations of some
of the optional services.
</p>
<p>
The additional supported services include.</p>
<ul>
<li>
XUpdateQueryService - Enables execution of XUpdate queries
against the database.
</li>
<li>
CollectionManagementService - 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>
DatabaseInstanceManager - Provides the ability to control the
operation of the server programatically.
</li>
<li>
CollectionManager - 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>
<!--
<li>
XMLObjectService - Provides a mechanism to invoke XMLObjects
within the server.
</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 must be using JDK 1.3. At this time
there appear to be problems with JDK 1.4. JDK 1.2 and below will not
work at all. 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>
xindice.jar - contains the main Xindice classes that are used by
the client API.
</li>
<li>
xmldb.jar - contains the XML:DB API interfaces.
</li>
<li>
openorb-1.2.0.jar - contains the CORBA ORB implementation used
by the client API to communicate with the server.
</li>
<li>
xerces-1.4.3.jar - contains the Xerces XML parser.
</li>
<li>
xalan-2.0.1.jar - contains the Xalan XSL-T engine. This
jar isn't absolutely required but you'll probably want it so
it's worth adding it.
</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><![CDATA[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><![CDATA[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><![CDATA[
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);
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>
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><![CDATA[
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><![CDATA[
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><![CDATA[
Collection col =
DatabaseManager.getCollection("xmldb:xindice:///db/addressbook");
]]></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><![CDATA[
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><![CDATA[
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><![CDATA[
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. 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 Xindice HTTP server is listening on. The port setting is
displayed when you start the server. By default the
configuration used is
<code>xindice://localhost:4080</code>.
To access the collection /db/addressbook on host xml.apache.org port
4090 the URI would look something like this
<code>xindice://xml.apache.org:4090/db/addressbook</code>. If you
are running the client and server on the same machine you do not
need to specify a host or port. All examples in this document assume
the client and server are on the same machine.
</p>
<p>
If you are having problems accessing Xindice remotely this may be the
result of the server publishing an incorrect IP address as part of
its CORBA IOR. The IOR is generated by the ORB using the hostname
setting of the server. If the hostname is set to a
fully qualified domain name that can not be resolved by the client
you will not be able to remotely access the server. To fix this
you must insure the host name on the server is resolvable by the
client. To see the setting of the host name on the server you should
be able to type
<code>hostname</code> at a command prompt. If
the hostname is not a fully qualified domain name then the ORB will
use the IP address of the server instead of the name and you
shouldn't have any problems.
</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);
col =
DatabaseManager.getCollection("xmldb:xindice:///db/");
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\" gzip=\"true\"/>" +
"</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);
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://www.xmldb.org/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>Using XMLObjects</title>
<section>
<title>Introduction</title>
<p>
XMLObjects provide a mechanism for extending the functionality of
the Xindice server. They are implemented in Java and are
configured at the collection level within the server. Building and
installing XMLObjects is quite simple but they still provide significant
power to extend the server with new functionality.
</p>
<p>
The uses for XMLObjects are many i.e. updating documents on the
server side, implementing a
custom query language or any other functionality where doing the
operation on the server side would be more efficient. The example
XMLObject included here will show you how you could implement a
single document query mechanism in the server even when Xindice by
default queries at the collection level.
</p>
<p>
Note: When writing XMLObjects you use the internal APIs for Xindice and
therefore have full access to the internals of the server. Because
of this you should exercise caution in the code that you write to
insure that it is robust and does not harm the operation of the
server.
</p>
</section>
<section>
<title>A Simple XMLObject</title>
<p>
XMLObjects are simply Java classes that extend SimpleXMLObject to
provide custom functionality within the server.
</p>
<p>
To get started let's take a look at a very simple Hello World XMLObject.
</p>
<section>
<title>A Hello World XMLObject</title>
<source><![CDATA[package org.apache.xindice.examples;
import org.apache.xindice.core.objects.*;
public class HelloWorldXMLObject extends SimpleXMLObject {
public String execute() {
return "Hello World";
}
}]]></source>
</section>
<p>
This simple XMLObject just defines one method
<code>execute()</code> that takes no parameters
and returns a String. The <code>execute()</code>
method name is special within the
context of XMLObjects because if no explicit method is specified
in the invocation request the XMLObject framework will call the
<code>execute()</code> method automatically.
</p>
<p>
To compile and install this XMLObject you need to make sure that you
have <code>xindice.jar</code> and the directory where the
XMLObject class file can be found in your
<code>CLASSPATH</code> environment variable. The
directory for the class file must also be available to the Xindice
server before you start it.
</p>
<p>
Once you have your classpath setup you can compile the XMLObject
like any other Java class and then install it in the
<code>/db/addressbook</code> collection.
</p>
<source><![CDATA[
xindice add_xmlobject -i org.apache.xindice.examples.HelloWorldXMLObject -n Hello -c /db/addressbook
]]></source>
<p>
And then you can run it.
</p>
<source><![CDATA[
xindice invoke -c /db/addressbook -o Hello
]]></source>
<p>
One thing to note about this is that when you invoke the
XMLObject you need to use the name that you configured with the
<code>-n</code>
parameter to <code>add_xmlobject</code> not the
name of the class. In this case we named the object
<code>Hello</code> so that is
what we use to invoke it.
</p>
<p>
If all went well you should see something like this
</p>
<source><![CDATA[
Results =
Hello World
]]></source>
</section>
<section>
<title>Building the XPath Query XMLObject</title>
<p>
By default the Xindice XPath query functionality takes an XPath and
applies it against all documents stored in a collection to find a
set of matching nodes. Depending on our application this may not be
what we really want. The
<code>XPathQueryService</code> does support
doing this but it will be instructive to look at how we could roll
our own implementation to do the same thing.
</p>
<p>
To do this we first need to decide what information is required to
execute the query. First we need the XPath we want to execute and
second we need the key of the document within the collection. We
also need the collection itself but since XMLObjects are configured
at the collection level within the system this is taken care of
automatically.
</p>
<p>
Now that we know what data we need we can see that we're going to
need a method that takes two parameters, the xpath and the id. Once
we have these parameters we'll need to retrieve the document and
then use an XPath engine to select the nodes we want from the
document. Our solution might look something like this.
</p>
<section>
<title>Single Document XPath Query XMLObject</title>
<source><![CDATA[package org.apache.xindice.examples;
import org.apache.xindice.core.*;
import org.apache.xindice.core.objects.*;
import org.apache.xindice.xml.dom.*;
import org.w3c.dom.*;
import org.apache.xpath.*;
public class XPathQueryXMLObject extends SimpleXMLObject {
public static final String [] PARAMS_query = {"xpath", "id"};
public static final String [] DEFAULTS_query = {"/", ""};
public Document query(String xpath, String id) throws Exception {
Collection col = getCollection();
Document target = col.getDocument(id);
NodeList result = XPathAPI.selectNodeList(target, xpath);
// Turn the NodeList into a document.
Document doc = new DocumentImpl();
Element root = doc.createElement("result");
doc.appendChild(root);
int i = 0;
while ( (result != null) && (i < result.getLength()) ) {
root.appendChild(doc.importNode(result.item(i), true));
i++;
}
return doc;
}
}]]></source>
</section>
<p>
Delving into this in a little more detail we see several obvious
differences from our simple example.
</p>
<p>
First we're no longer using the default
<code>execute()</code> method and have defined
our own method named <code>query()</code>.
</p>
<p>
Next, we also have now added two contants to our class
<code>PARAMS_query</code> and
<code>DEFAULTS_query</code>. <code>PARAMS_query</code>
is used to define the names of the parameters that are required by
the query method. <code>DEFAULTS_query</code> defines the
default values that are provided for those parameters if the user
leaves out a parameter when invoking the XMLObject. These constants
are necessary to provide hints to the XMLObject engine on how to map
incoming parameters to the proper parameters on the method.
</p>
<p>
This XML Object is installed just like before except this time we're
going to configure it for the
<code>addressbook</code> collection.
</p>
<source><![CDATA[
xindice add_xmlobject -i org.apache.xindice.examples.XPathQueryXMLObject -n XPath -c /db/addressbook
]]></source>
<p>
Before we can use it though we need some sample data. Again we're
using the familiar person XML. This should be
added to the database under the key address1.
</p>
<source><![CDATA[<?xml version="1.0"?>
<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>
xindice add_document -c /db/addressbook -n address1 -f address1.xml]]></source>
<p>
After adding this data we can now use our XMLObject
to retrieve nodes from just this document.
</p>
<source><![CDATA[xindice invoke -c /db/addressbook -o XPath/query?xpath='/person/fname'&id=address1]]></source>
<p>
Note: on UNIX you will need to
escape the '&' with a '\' character to prevent its evaluation
by the shell. If all goes well the result will be.
</p>
<source><![CDATA[Results =
<!xml version="1.0"?>
<result><fname>John</fname></result>]]></source>
</section>
<section>
<title>Putting the XPath Query XMLObject to Work</title>
<p>
So far we've seen how to create a couple different XMLObjects, how
to install them in the server and how to invoke them from the
command line. While this alone is very useful, XMLObjects are really
much more useful when you use them from within another program.
</p>
<p>
Note: Since XMLObjects are a proprietary feature of Xindice we have to use a
Xindice specific extension service for the XML:DB API to invoke them
from within our programs. This is important to note because
programs built to use XMLObjects will not be portable to other XML
databases.
</p>
<p>
In this example we'll use our XPathQueryXMLObject to build a very
simple program that queries for the street and then prints the the
value out.
</p>
<p>
For this example we'll use the same object configuration and sample
data as used in the previous section.
</p>
<section>
<title>Invoking the XPathQueryXMLObject via the XML:DB API</title>
<source><![CDATA[package org.apache.xindice.examples;
import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;
// Import the Xindice specific XMLObjectService
import org.apache.xindice.client.xmldb.services.*;
public class XPathQueryInvoke {
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";
String key = "address1";
XMLObjectService service =
(XMLObjectService) col.getService("XMLObjectService", "1.0");
Resource result = service.invokeXMLObject("/db/addressbook/XPath/query?xpath=" +
xpath + "&id=" + key);
System.out.println((String) result.getContent());
}
catch (XMLDBException e) {
System.err.println("XML:DB Exception occured " + e.errorCode);
}
finally {
if (col != null) {
col.close();
}
}
}
}]]></source>
</section>
<p>
As you can see from the example calling an XMLObject from a program
is pretty similar to calling it from the command line. You simply
create the <code>XMLObjectService</code>
and then call <code>invokeXMLObject()</code>
handing it the URI just like you did on the command line.
</p>
<p>
The result that you receive is a Resource that will either contain a
string result or an XML result depending on the return type of the
XMLObject. If the XMLObject returns it's result as anything other
then a DOM Node or Document then the results are treated as a string
and should only be retrieved with
<code>result.getOutput()</code>. If the
XMLObject you are calling returns a DOM
<code>Node</code> or
<code>Document</code> then you can cast the
result to an XMLObject and use the
<code>getContentAsDOM</code> and
<code>getContentAsSAX</code> methods to retrieve
the content as well.
</p>
<p>
We've now seen how to contruct XMLObjects, install them in the
server and invoke them from the command line and our custom
programs. Hopefully you see the value in these powerful server side
extensions for Xindice and can use them when necessary to improve your
applications.
</p>
</section>
</section>
-->
<section>
<title>Address Book Example Application</title>
<section>
<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 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>
<title>Auto Linking</title>
<p>
Xindice provides a facility for automating relational links between
managed documents called AutoLinking. This allows you to break out
duplicate data into shared documents or include a dynamic element
such as the output of a query or XMLObject invocation into an XML
file stored in the repository.
</p>
<p>
AutoLinking is specified by adding special attributes to the XML
tag defining the link. This works in a similar manner to Xlink from
the W3C. The attributes must use the
xmlns:db="http://xml.apache.org/xindice/XMLObject" namespace. There are two
attributes to be concerned with href and type.
</p>
<p>
db:href attribute:
Defines the URI for the resource that this AutoLink should retrieve.
</p>
<p>
db:type attribute:
Specifies how this link should be processed. The following
mechanisms are available.
</p>
<ol>
<li>
replace - Replaces the linking element with the content of
the href URI
</li>
<li>
content - Replaces all child content of the linking element
with the content of the href URI. The linking element is not
replaced.
</li>
<li>
append - Appends the content of the href URI to the content
of the linking element.
</li>
<li>
insert - Inserts the content of the href URI as the first
child of the linking element.
</li>
</ol>
<section>
<title>Auto-Linking Using Replace</title>
<p>
This example will replace the some-element element with the
contents of the URI xindice:///db/ocs/test/some-document.
</p>
<source><![CDATA[<document>
<some-element xmlns:db="http://xml.apache.org/xindice/XMLObject"
db:href="xindice:///db/ocs/test/some-document"
db:type="replace"/>
</document>]]></source>
<p>After expanding the link it will look something like this.</p>
<source><![CDATA[<document>
<some-document>
...
</some-document>
</document>]]></source>
</section>
<section>
<title>Auto-Linking Using Insert</title>
<p>
The following link will insert the content of the document found
at xindice:///db/ocs/test/some-document as the first child of
the element some-element.
</p>
<source><![CDATA[<document>
<some-element xmlns:db="http://xml.apache.org/xindice/XMLObject"
db:href="xindice:///db/ocs/test/some-document"
db:type="insert"/>
</document>]]></source>
<p>
After linking the document will look like.
</p>
<source><![CDATA[<document>
<some-element xmlns:db="http://xml.apache.org/xindice/XMLObject"
db:href="xindice:///db/ocs/test/some-document"
db:type="insert">
<some-document>
...
</some-document>
</some-element>
</document>]]></source>
</section>
</section>
-->
</section>
</body>
</document>
1.1 xml-xindice/src/documentation/content/xdocs/dev/guide-user.xml
Index: guide-user.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2002/11/17 08:16:03 $
- Author: Kimbro Staken (kstaken@xmldatabases.org)
-->
<document>
<header>
<title>User Guide</title>
<authors>
<person id="ks" name="Kimbro Staken" email=""/>
</authors>
<notice/>
<abstract/>
</header>
<body>
<warning>This documentation is a work in progress and is only applicable to the CVS version of Xindice. There is absolutely no guarantee that this information is accurate. You have been warned.
</warning>
<section>
<title>Introduction to Xindice</title>
<section>
<title>What Is Xindice</title>
<p>
The Xindice Core server is a database server designed from the
ground up to store XML data. The
Xindice server is what is termed by
the
<link href="http://www.xmldb.org">XML:DB Initiative</link>
as a Native XML Database. You could also refer to it as a
seamless XML database which might be an easier to understand
description.
</p>
<p>
What this means is that to the largest extent possible you work
with XML tools and technologies when working with the data in the
server. All data that goes into and out of the server is XML. The
query language used is XPath and the programming APIs support DOM
and SAX. All things that should be familiar to a developer used
to using XML in their applications. When working with XML data and
Xindice there is no mapping between different data models. You simply
design your data as XML and store it as XML.
</p>
<p>
What this gives you can be summed up in one word, flexibility. XML
provides an extremely flexible mechanism for modeling application
data and in many cases will allow you to model constructs that are
difficult or impossible to model in more traditional systems. This
model is a semi-structured model and for some applications it is
an essential component. By
using a native XML database such as Xindice to store this data you can
focus on building your applications and not worry about how the
complex XML construct maps to the underlying data store or trying
force a flexible data model into a rigid set of schema constraints.
</p>
<p>
Ultimately though, Xindice is a tool. It will be right for some jobs
and completely wrong for others. The job it is best at is simply
storing XML data. In fact, that's all it does. If you have lots of
XML data then Xindice may just be the right tool. However, if your
data isn't XML or if you have the need for precise control over
the structure of the data you might be better off using another
database solution.
</p>
</section>
<section>
<title>Current Status</title>
<p>
Native XML database technology is a very new area and Xindice is very
much a project still in development.
The server currently supports storing well formed XML documents.
This means it does not have any schema that constrains what
can be placed into a document collection. This makes Xindice a
semi-structured database and provides tremendous
flexiblity in how you store your data, but, also means you give up
some common database functionality such as data
types.
In its current
state Xindice is already a powerful tool for managing XML data.
However, there is still much that needs to be done. Feedback and
contributions are actively encouraged.
</p>
<p>
This document attempts to
describe those features that are working and can be used today.
You should review the README file that is part of the Xindice
distribution for the most current status on the project.
</p>
<p>
NOTE: Both the Xindice server and this document are works in
progress. Any comments are welcome and encouraged.
</p>
</section>
<section>
<title>Feature Summary</title>
<p>
Document Collections: Documents are stored in collections that can
be queried as a whole. You can create collections that contain just
documents of the same type or you can create a collection to store
all your documents together. The database doesn't care.
</p>
<p>
XPath Query Engine: To query the Document Collections you use
<link href="http://www.w3.org/TR/xpath">XPath</link> as defined
by the W3C. This provides a reasonably flexible mechanism for
querying documents by navigating and restricting the result tree
that is returned.
</p>
<p>
XML Indexing: In order to improve the performance of queries over
large numbers of documents you can define indexes on element and
attribute values. This can dramatically speed up query response
time.
</p>
<p>
XML:DB XUpdate Implementation: When you store XML in the database
you may want to be able to change that data without retrieving the
entire document. XUpdate is the mechanism to use when you want to do
server side updates of the data. It is an XML based language for
specifying XML modifications and allows those modifications to be
applied to entire document collections as well as single documents.
</p>
<p>
Java XML:DB API Implementation: For Java programmers Xindice provides
an implementation of the XML:DB API. This API is intended to bring
portability to XML database applications just as JDBC has done for
relational databases. Most applications developed for Xindice will use
the XML:DB API.
</p>
<p>
XMLObjects: XMLObject provide a server extension mechanism for
adding extra functionality to the server. They can be used to
execute complex operations within the database engine to cut down on
network bandwidth or to add functionality that doesn't currently
exist in the server.
</p>
<p>
Command Line Management Tools: To aid the administrator Xindice
provides a full suite of command line driven management tools. Just
about everything you can do through the XML:DB API can also be done
from the command line.
</p>
<p>
CORBA Network API: For developers who are interested in working in
languages other then Java, Xindice provides a CORBA API that can be
used to build applications. All functionality available through the
XML:DB API is also available through the CORBA API. In fact the
XML:DB API is built on top of the CORBA API. Most Java developers
though, will never even need to know that the CORBA API exists.
</p>
<p>
Modular Architecture: The Xindice server is constructed in a very
modular manner. This makes it easy to add and remove components to
tailor the server to a particular environment or to embed it into
another application.
</p>
</section>
<section>
<title>Database Structure</title>
<p>
The Xindice server is designed to store collections of XML documents.
Collections can be arranged in a hierarchy similar to that of a
typical UNIX or Windows file system.
</p>
<p>
In Xindice the data store is rooted in a database instance that can
also be used as a document collection. This
database instance can then contain any number of child collections.
In a default install of Xindice the database instance is called
'db' and all collection paths will begin with /db. It is possible to
rename the database instance if desired though it is not necessary
to do so.
</p>
<p>
Collections are referenced in a similar manner to how you
would work with a hierarchical file system.
</p>
<section>
<title>Collection Path Example</title>
<p>
If you had a collection
created under 'db' called my-collection and a collection under
that called my-child-collection the path used when accessing the
my-child-collection collection would be
</p>
<source><![CDATA[
/db/my-collection/my-child-collection
]]></source>
</section>
<p>
Within collections there are several types of objects that can be
stored. You can store XML documents, XMLObjects and other
collections. Each of these objects can also be referenced via a
path.</p>
<section>
<title>Collection Path Referencing a Document</title>
<p>
Extending the previous example by adding a document to
my-child-collection named my-document it to could be
referenced via a path.
</p>
<source><![CDATA[
/db/my-collection/my-child-collection/my-document
]]></source>
</section>
<p>
There is one catch to this however. Since you can have more then one
object in a collection with the same name
there is an order of precedence that is applied when evaluating a
path. The order of precendence is collection followed by XMLObject
and then document. What this means is that if you have a document
and a collection with the same name you will not be able to retrieve
the document.
</p>
<p>
You can also access collections on remote machines by specifying the host
and port of the server.
</p>
<section>
<title>Collection Path Referencing a remote Document</title>
<p>
If the previous example was on a remote machine the path would look
something like this.
</p>
<source><![CDATA[
myhost.domain.com:4080/db/my-collection/my-child-collection/my-document
]]></source>
<p>
This can also take the form of a Xindice URI.
</p>
<source><![CDATA[
xindice://myhost.domain.com:4080/db/my-collection/my-child-collection/my-document
]]></source>
</section>
</section>
<section>
<title>Introducing the Command Line Tools</title>
<p>
The Xindice server includes a command line program named
<code>xindice</code> that allows you to manage the
data stored in the server.
A complete list of available commands and more
detail about each command can be found in the
<link href="guide-tools.html">Command Line Tools Reference Guide</link>.
</p>
<p>
The
<code>xindice</code> tool is located in the
Xindice-Core/bin directory and it is
probably a good idea to add this directory to your PATH environment
variable. All examples in this manual will assume that the
Xindice-Core/bin directory is on the operating system path.
</p>
</section>
</section>
<section>
<title>Managing Documents</title>
<section>
<title>Introduction</title>
<p>
In many ways the Xindice database can be viewed as a simple file
store. This is of course a highly simplified view of things but
is a useful place to get started in learning the functionality of
the server.
</p>
<p>
The Xindice server provides facilities to store, retrieve and
delete well formed XML documents.
</p>
</section>
<section>
<title>Adding Documents</title>
<p/>
<section>
<title>Adding a Document With a Given Key</title>
<p>
The document fx102.xml will be added to the collection
/db/data/products and will be stored under the key fx102.
</p>
<source><![CDATA[
xindice add_document -c /db/data/products -f fx102.xml -n fx102
]]></source>
</section>
<section>
<title>Adding a Document Without a Key</title>
<p>
The document fx102.xml will be added to the collection
/db/data/products. No key is provided so one will be generated
automatically by the server. The generated key will look similar
to this 0625df6b0001a5d4000bc49d0060b6f5
</p>
<source><![CDATA[
xindice add_document -c /db/data/products -f fx102.xml
]]></source>
</section>
</section>
<section>
<title>Retrieving Documents</title>
<p>
Documents can be retrieved from the database using the ID that
they were inserted under.
</p>
<section>
<title>Retrieving a Document Using an ID</title>
<p>
The document identified by the key fx102 will be retrieved from
the /db/data/products collection and stored in the file fx102.xml
</p>
<source><![CDATA[
xindice retrieve_document -c /db/data/products -n fx102 -f fx102.xml
]]></source>
</section>
</section>
<section>
<title>Deleting Documents</title>
<p/>
<section>
<title>Deleting a document using an ID</title>
<p>
The document identified by the key fx102 will be removed from the
collection /db/data/products.
</p>
<source><![CDATA[
xindice delete_document -c /db/data/products -n fx102
]]></source>
</section>
</section>
</section>
<section>
<title>Querying the Database</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 can be executed at either the document level
or 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 supports the creation of indexes on
XML documents to speed up commonly used XPath queries. Please refer
to the
<link href="guide-administrator.html">Administrators
Guide</link> for more detail about configuring indexes.
</p>
<p>
You can execute XPath queries against the database using the command
line tools and the result of the query will be displayed.
</p>
<section>
<title>
Executing an XPath query against a collection of XML documents
</title>
<p>
Here we assume we have a collection /db/data/products that contains
documents that are similar to the following.
</p>
<source><![CDATA[<?xml version="1.0"?>
<product product_id="120320">
<description>Glazed Ham</description>
</product>]]></source>
<p>
The XPath /product[@product_id="120320"] will be executed against
the collection /db/data/products and all matching product entries
will be returned.
</p>
<source><![CDATA[
xindice xpath_query -c /db/data/products -q /product[@product_id="120320"]
]]></source>
<p>
The result of the query is an XPath node-set that contains one
node for each result. In this particular example there is only
one result and the node that matches is the root element so you
get back basically the whole document.
</p>
<p>
To make it easy to link the result node back to the originating
document, Xindice adds a few attributes to the result. These attributes
are added in the NodeSource namespace that has the URI
http://xml.apache.org/xindice/NodeSource. The
<code>col</code> attribute specifies the
collection where the document can be found and the
<code>key</code> attribute
provides the key of the original document. Using this information it
is possible to retrieve the original document that this node was
selected from for further processing.
</p>
<source><![CDATA[<product product_id="120320" xmlns:src="http://xml.apache.org/xindice/NodeSource"
src:col="/db/data/products" src:key="120320">
<description>Glazed Ham</description>
</product>]]></source>
<p>
If more then one result is found the results look something like
this. This could be the result of the query /product
</p>
<source><![CDATA[
<product product_id="120320" xmlns:src="http://xml.apache.org/xindice/NodeSource"
src:col="/db/data/products" src:key="120320">
<description>Glazed Ham</description>
</product>
<product product_id="120321" xmlns:src="http://xml.apache.org/xindice/NodeSource"
src:col="/db/data/products" src:key="120321">
<description>Boiled Ham</description>
</product>
<product product_id="120322" xmlns:src="http://xml.apache.org/xindice/NodeSource"
src:col="/db/data/products" src:key="120322">
<description>Honey Ham</description>
</product>]]></source>
</section>
<p>
While it is certainly useful to be able to query from the command
line it is probably more useful to be able to use the results of a
query in an application. For more information on building
applications for Xindice, please refer to the
<link href="guide-user.html">Developers Guide</link>.
</p>
</section>
<!--
<section>
<title>XMLDB Error codes</title>
<p>
public static final int UNKNOWN_ERROR = 0;
public static final int VENDOR_ERROR = 1;
public static final int NOT_IMPLEMENTED = 2;
public static final int WRONG_CONTENT_TYPE = 3;
public static final int PERMISSION_DENIED = 4;
public static final int INVALID_URI = 5;
public static final int NO_SUCH_SERVICE = 100;
public static final int NO_SUCH_COLLECTION = 200;
public static final int INVALID_COLLECTION = 201;
public static final int COLLECTION_CLOSED = 202;
public static final int NO_SUCH_RESOURCE = 300;
public static final int INVALID_RESOURCE = 301;
public static final int UNKNOWN_RESOURCE_TYPE = 302;
public static final int NO_SUCH_DATABASE = 400;
public static final int INVALID_DATABASE = 401;
</p>
</section>
-->
</body>
</document>
1.1 xml-xindice/src/documentation/content/xdocs/dev/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2002/11/17 08:16:03 $
- Author: Vladimir R. Bossicard (vladimir@apache.org)
-->
<document>
<header>
<title>Dev Zone</title>
<authors>
<person name="Vladimir R. Bossicard" email="vladimir@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Introduction</title>
<p>The Xindice team is currently preparing a major release and try to
catch up with the numerous points still open. These pages describe
what has been done but also the amount of work that still needs to
be done. If you have interest in the project, your help is welcome!</p>
</section>
<section>
<title>Development Status</title>
<p>The project really needs your help in the following areas:</p>
<ul>
<li>
<strong>bug reports</strong>: according to the number of bugs
found in the bug database, Xindice has almost no bugs at all.
Well the experience shows that the reality is different. We
can't fix bugs if we don't know where they are! So if you find
a bug, please report it with information.
</li>
<li>
<strong>new documentation</strong>: everyone who uses Xindice
must contribute to the documentation. Period. Simply read the
guides, correct the mistakes and send a patch would already
help tremendoulsy.
</li>
<li>
<strong>accurate how-tos</strong>: installing Xindice is for a
lot of users a real nightmare. And this shouldn't be the case.
The goal is to provide simple and detailed
<link href="../howto/index.html">how-tos</link>. If you are
installing Xindice, please follow the how-to and review its
accuracy. If there is none, you'll have to write and and send
it to use.
</li>
<li>
<strong>local patches</strong>: if you have locally modified
Xindice to fix a bug, please provide a patch! Or at least
discuss the modifications on the
<link href="../mail.html">mailing list</link>.
</li>
</ul>
</section>
</body>
</document>
1.1 xml-xindice/src/documentation/content/xdocs/dev/news.xml
Index: news.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2002/11/17 08:16:03 $
- Author: Vladimir R. Bossicard (vladimir@apache.org)
-->
<document>
<header>
<title>Dev News</title>
</header>
<body>
<ul>
<li>
<strong>17 November 2002</strong>: the new website is published.
Many thanks to Kevin (guides), Nicola (logo) and Jeff (Forrest
hotline). And me (Vladimir) for the overall migration :-)
</li>
</ul>
</body>
</document>