dviner 2002/12/30 10:33:20
Modified: src/documentation/content/xdocs/dev guide-developer.xml
Log:
added first documentation of metadata storage. it's
not perfect, but it has to start somewhere.
also fixed the width of the page so that no horizontal
scrollbar appears for browsers that are maximized on
1024x768 resolution monitors.
--dviner
Revision Changes Path
1.2 +406 -639
xml-xindice/src/documentation/content/xdocs/dev/guide-developer.xml
Index: guide-developer.xml
===================================================================
RCS file:
/home/cvs/xml-xindice/src/documentation/content/xdocs/dev/guide-developer.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- guide-developer.xml 17 Nov 2002 08:16:03 -0000 1.1
+++ guide-developer.xml 30 Dec 2002 18:33:20 -0000 1.2
@@ -9,6 +9,7 @@
<title>Developer Guide</title>
<authors>
<person id="ks" name="Kimbro Staken" email=""/>
+ <person name="Dave Viner" email="[EMAIL PROTECTED]" />
</authors>
<notice/>
<abstract/>
@@ -243,12 +244,12 @@
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>
+ <source>xindice lc -c /db</source>
<p>
If you don't see 'addressbook' listed in the result then you
need to create
the collection. To create it just run:
</p>
- <source><![CDATA[xindice ac -c /db -n addressbook]]></source>
+ <source>xindice ac -c /db -n addressbook</source>
<p>
Now that we have the collection, we can add a few example
documents
so that we have something to play with. You can find the
examples in your
@@ -256,11 +257,11 @@
<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>
+ <source>
+cd $XINDICE_HOME/java/examples/guide/xml
+xindice ad -c /db/addressbook -f address1.xml -n address1
+xindice ad -c /db/addressbook -f address2.xml -n address2
+ </source>
<p>
If you're on Windows you'll need to adjust the path in the cd
command
for your platform. Most of the examples in the manual will be
written for
@@ -282,43 +283,48 @@
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;
+ <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();
-}
-}
+public static void main(String[] args) throws Exception {
+ Collection col = null;
+ try {
+ String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
+ Class c = Class.forName(driver);
+
+ Database database = (Database) c.newInstance();
+ DatabaseManager.registerDatabase(database);
+
+ String uri = "xmldb:xindice:///db/addressbook";
+ col =
+ DatabaseManager.getCollection(uri);
+
+ String xpath = "//person[fname='John']";
+ XPathQueryService service =
+ (XPathQueryService) col.getService("XPathQueryService", "1.0");
+ ResourceSet resultSet = service.query(xpath);
+ ResourceIterator results = resultSet.getIterator();
+ while (results.hasMoreResources()) {
+ Resource res = results.nextResource();
+ System.out.println((String) res.getContent());
+ }
+ }
+ catch (XMLDBException e) {
+ System.err.println("XML:DB Exception occured " + e.errorCode);
+ }
+ finally {
+ if (col != null) {
+ col.close();
+ }
+ }
}
+
}]]></source>
</section>
<p>
@@ -329,15 +335,16 @@
If you have a binary build of Xindice the examples are
already built
and you can run this example by typing.
</p>
- <source><![CDATA[
+ <source>
cd $XINDICE_HOME/java/examples/guide
./run org.apache.xindice.examples.Example1
- ]]></source>
+ </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">
+<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>
@@ -357,11 +364,11 @@
<p>
To begin the program imports several XML:DB packages.
</p>
- <source><![CDATA[
+ <source>
import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
import org.xmldb.api.*;
- ]]></source>
+ </source>
<p>
These import the basic classes required by the API.
<code>import org.xmldb.api.base.*;</code> is the base API
module
@@ -394,10 +401,11 @@
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>
+ <source>
+String uri = "xmldb:xindice:///db/addressbook";
+Collection col =
+ DatabaseManager.getCollection(uri);
+ </source>
<p>
In the XML:DB API collections are retrieved
by calling
@@ -427,10 +435,10 @@
Once you do this you can switch between the instances by
simply
changing the first component of the path.
</p>
- <source><![CDATA[
+ <source>
xindice:///db/news
xindice:///db2/news
- ]]></source>
+ </source>
<p>
These paths will switch between a Xindice server
with a root collection of db and one of db2. These instances
could
@@ -480,13 +488,13 @@
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[
+ <source>
ResourceIterator results = resultSet.getIterator();
while (results.hasMoreResources()) {
-Resource res = results.nextResource();
-System.out.println((String) res.getContent());
+ Resource res = results.nextResource();
+ System.out.println((String) res.getContent());
}
- ]]></source>
+ </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
@@ -508,13 +516,13 @@
The final element about our example program worth noting is
the
finally clause.
</p>
- <source><![CDATA[
+ <source>
finally {
-if (col != null) {
-col.close();
-}
+ if (col != null) {
+ col.close();
+ }
}
- ]]></source>
+ </source>
<p>
The finally clause closes the collection that we created
earlier.
This is vitally important and should never be overlooked.
Closing
@@ -600,7 +608,8 @@
</p>
<section>
<title>Creating a Collection</title>
- <source><![CDATA[package org.apache.xindice.examples;
+ <source><![CDATA[
+package org.apache.xindice.examples;
import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
@@ -612,40 +621,44 @@
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();
-}
-}
+ Collection col = null;
+ try {
+ String driver = "org.apache.xindice.client.xmldb.DatabaseImpl";
+ Class c = Class.forName(driver);
+
+ Database database = (Database) c.newInstance();
+ DatabaseManager.registerDatabase(database);
+ String uri = "xmldb:xindice:///db/";
+ col =
+ DatabaseManager.getCollection(uri);
+
+ String collectionName = "mycollection";
+ CollectionManager service =
+ (CollectionManager) col.getService("CollectionManager", "1.0");
+
+ // Build up the Collection XML configuration.
+ String collectionConfig =
+ "<collection compressed=\"true\" " +
+ " name=\"" + collectionName + "\">" +
+ " <filer class=\"org.apache.xindice.core.filer.BTreeFiler\" "+
+ " 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>
@@ -702,7 +715,8 @@
</p>
<section>
<title>Adding an XML File to the Database</title>
- <source><![CDATA[package org.apache.xindice.examples;
+ <source><![CDATA[
+package org.apache.xindice.examples;
import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
@@ -711,45 +725,46 @@
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");
+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]);
+ 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();
-}
-}
+ 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);
+ File file = new File(fileName);
+ FileInputStream insr = new FileInputStream(file);
-byte[] fileBuffer = new byte[(int)file.length()];
+ byte[] fileBuffer = new byte[(int)file.length()];
-insr.read(fileBuffer);
-insr.close();
+ insr.read(fileBuffer);
+ insr.close();
-return new String(fileBuffer);
+ return new String(fileBuffer);
}
}]]></source>
</section>
@@ -788,7 +803,8 @@
</p>
<section>
<title>Retrieving an XML Document from the Database</title>
- <source><![CDATA[package org.apache.xindice.examples;
+ <source><![CDATA[
+package org.apache.xindice.examples;
import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
@@ -798,39 +814,40 @@
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");
+ 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();
-}
-}
+ 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;
+ <source><![CDATA[
+package org.apache.xindice.examples;
import org.xmldb.api.base.*;
import org.xmldb.api.modules.*;
@@ -840,28 +857,28 @@
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");
+ 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();
-}
-}
+ 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>
@@ -911,34 +928,35 @@
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);
+ 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);
+ Database database = (Database) c.newInstance();
+ DatabaseManager.registerDatabase(database);
-col = DatabaseManager.getCollection("xmldb:xindice:///db/addressbook");
+ 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();
-}
-}
+ 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>
@@ -1079,369 +1097,207 @@
*/
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");
+ 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/[EMAIL PROTECTED] = 'home']\"/>" +
-" <xu:update select=\"/person/[EMAIL PROTECTED] = '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();
-}
-}
+ String xupdate = "<xu:modifications version=\"1.0\"" +
+ " xmlns:xu=\"http://www.xmldb.org/xupdate\";>" +
+ " <xu:remove select=\"/person/[EMAIL PROTECTED] = 'home']\"/>" +
+ " <xu:update select=\"/person/[EMAIL PROTECTED] = '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>
+]]></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">[EMAIL PROTECTED]</email>
- <email type="work">[EMAIL PROTECTED]</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");
+ <title>Storing metadata</title>
+ <p>
+ Xindice allows a developer to store metadata that is associated
with any collection or document.
+ Metadata is data that is associated with a document or
collection but is not part of that document or collection. For
+ example, a filesystem lists the last modified time of a file or
directory. That last modified time is metadata about the
+ file or directory.
+ </p>
+ <p>
+ Within Xindice, when metadata is turned on, each document and
collection has a MetaData object associated with
+ it. The MetaData object is composed of three sections and is
represented in XML like this:
+ </p>
+ <source><![CDATA[
+<meta>
+ <system type="doc">
+ <attr name="created" value="10128378882" />
+ <attr name="modified" value="10128378882" />
+ </system>
+ <attrs>
+ <attr name="key" value="value"/>
+ <attr name="foo" value="bar"/>
+ </attrs>
+ <custom>
+ <myspecial>
+ any <valid /> xml
+ </myspecial>
+ </custom>
+</meta>
+]]>
+ </source>
+ <p>
+ The first section is enclosed by the <system> element
+ and is controlled by the core of Xindice. It currently tracks
the type of resource referenced,
+ creation time and last modification time of the resource. The
<system> element has an attribute "type" which is
+ either "doc" for document or "col" for collection. Within the
<system> element are <attr> elements. Each
+ <attr> element has two attributes, name and value. The
creation and modification times are stored in individual
+ <attr> elements. The value of these attributes are
recorded as milliseconds since midnight
+ Jan 1, 1970 (just as System.currentTimeMills() ).
+ </p>
+ <p>
+ The second section is a map of key-value pairs and is enclosed
by the <attrs> element. Each key-value
+ pair is represented in a single <attr> element. The
key-value pairs are completely controlled by the user. You
+ can add or remove any key-value pair in this section. Note
that the map is from Object to Object, so you
+ can store any object your application requires.
+ </p>
+ <p>
+ The third section is a custom XML document. This too is
completely controlled by the user. The only
+ prerequisite is that the document stored is well-formed XML.
+ </p>
+ <section>
+ <title>Enabling metadata</title>
+ <p>
+ To turn on metadata storage in Xindice, edit the system.xml
configuration file and set the "use-metadata"
+ attribute of the root-collection element to "on". Restart
your container, and metadata storage will
+ be enabled.
+ </p>
+ <p>
+ If properly configured, when you restart your container, you
will see a log message that
+ looks like this:
+ </p>
+ <source>
+Dec 30, 2002 10:21:51 AM org.apache.xindice.core.Database setConfig
+INFO: Meta information initialized
+ </source>
+ <note>
+ This example is from the output of Tomcat. The output from
other containers might
+ look different, but the message ("Meta information
initialized") should be identical.
+ </note>
+ </section>
+ <section>
+ <title>Using metadata</title>
+ <p>
+ How you use metadata is really up to you, the application
developer. There are many potential uses depending on
+ your application. One example is a content management
system in which each document has a series of states
+ through which it must pass. The states might be controlled
by a finite state machine, but each document's current
+ state would be stored in the metadata associated with it.
+ </p>
+ </section>
+ <section>
+ <title>Sample metadata code</title>
+ <p>
+ Currently the metadata accessors are only implemented in the
XML-RPC code. The Xindice XML-RPC server
+ has four metadata related methods, GetCollectionMeta,
GetDocumentMeta, SetCollectionMeta, SetDocumentMeta.
+ Here's quick perl script which creates a collection and then
dumps out its metadata contents, and then sets some
+ values inside the metadata.
+ </p>
+ <source><![CDATA[
+#!/usr/local/bin/perl -w
- 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>
- -->
+use strict;
+use Frontier::Client;
+use Data::Dumper;
+
+my($server,$result,$url);
+
+$url = 'http://localhost:8080/xindice-1.1b';
+$server = Frontier::Client->new('url'=>$url,'debug'=>0);
+
+## try listing the collections
+## look at org/apache/xindice/server/rpc/messages/*.java
+## for the 'message' possibilities. The parameters are there as well.
+
+my $colname = 'ninemetatest';
+my $args = {};
+
+#first, add the collection directly under the /db root.
+$args->{'message'} = 'CreateCollection';
+$args->{'collection'} = '/db';
+$args->{'name'} = $colname;
+$result = $server->call('run',$args);
+
+## now get the collection's meta
+$args = {};
+$args->{'message'} = 'GetCollectionMeta';
+$args->{'collection'} = '/db/'.$colname;
+$result = $server->call('run',$args);
+
+## this should print out the xml for the
+## collection's metadata.
+print Dumper($result);
+
+
+## now add some stuff to the metadata
+my $meta=<<EOF;
+<?xml version="1.0"?>
+ <meta>
+ <!-- since the system is controlled by
+ Xindice, this doesn't matter...
+ -->
+ <system type="col">
+ <attr name="created" value="1" />
+ <attr name="modified" value="5" />
+ </system>
+ <attrs>
+ <attr name="test" value="added" />
+ </attrs>
+ <custom>
+ <rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#";>
+ <test>the rdf example</test>
+ </rdf:RDF>
+ </custom>
+ </meta>
+EOF
+$args = {};
+$args->{'message'} = 'SetCollectionMeta';
+$args->{'collection'} = '/db/'.$colname;
+$args->{'meta'} = $meta;
+$result = $server->call('run',$args);
+
+## this should print out the xml for the
+## collection's revised metadata.
+print Dumper($result);
+ ]]>
+ </source>
+ </section>
+ <fixme author="dviner">
+ Make this example java instead of perl.
+ </fixme>
+ <note>Metadata is currently only exposed in the XML-RPC
accessor.</note>
+ </section>
<section>
- <title>Address Book Example Application</title>
+ <title>Example Application</title>
<section>
- <title/>
+ <title>Address Book</title>
<p>
The address book example is a simple servlet based application
constructued using Xindice. For more information on this
example look
@@ -1454,6 +1310,7 @@
</p>
</section>
</section>
+
<section>
<title>Experimental Features</title>
<p>
@@ -1462,96 +1319,6 @@
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>
