jbates 2002/12/18 06:15:41
Modified: src/documentation/content/xdocs/dev guide-internals.xml
Log:
Completed XUpdate chapter
Revision Changes Path
1.10 +83 -6
xml-xindice/src/documentation/content/xdocs/dev/guide-internals.xml
Index: guide-internals.xml
===================================================================
RCS file:
/home/cvs/xml-xindice/src/documentation/content/xdocs/dev/guide-internals.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- guide-internals.xml 18 Dec 2002 13:22:20 -0000 1.9
+++ guide-internals.xml 18 Dec 2002 14:15:40 -0000 1.10
@@ -775,20 +775,20 @@
two important methods: <code>query()</code> and
<code>compileQuery()</code>.
Both model a complete invokation of a query <em>on a
collection</em>. They
accept the following parameters:</p>
- <ul><li><code>org.apache.xindice.core.Collection
<b>context</b></code>: This
+ <ul><li><code>org.apache.xindice.core.Collection</code>
<strong><code>context</code></strong>: This
is the collection in which the query is to be invoked.
All results will be
fragments of XML from documents in this collection.
Cross-collection queries
are never possible in Xindice.</li>
- <li><code>java.lang.String <b>query</b></code>: This is
the query expression
+ <li><code>java.lang.String</code>
<strong><code>query</code></strong>: This is the query expression
to be invoked. The syntax of the expression depends on
the query language being
implemented by the resolver.</li>
- <li><code>org.apache.xindice.xml.NamespaceMap
<b>nsMap</b></code>: The query
+ <li><code>org.apache.xindice.xml.NamespaceMap</code>
<strong><code>nsMap</code></strong>: The query
expression will generally contain element names. Both
XPath and XUpdate allow
using element names in their syntax. Often these element
names will be
<em>qualified</em> by a namespace prefix, which needs to
be <em>resolved</em> by
the query resolver in order to find the exact namespace
uri being represented.
This namespace map allows a query resolver to do just
that.</li>
- <li><code>org.apache.xindice.core.data.Key[]
<b>keys</b></code>: This parameter,
+ <li><code>org.apache.xindice.core.data.Key[]</code>
<strong><code>keys</code></strong>: This parameter,
if not <code>null</code> provides a set of <em>doccument
names</em> (called keys
internally) in the collection that should be considered
by the query invokation.
If the parameter <em>is</em> <code>null</code>, then
<em>all</em> documents in the
@@ -843,7 +843,84 @@
</section>
</section>
<section>
- <title>5.2. XUpdate Queries</title>
+ <title>5.3. XUpdate Queries</title>
+ <p>XUpdate queries are used to send update instructions to
Xindice. An
+ XUpdate query is actually a complete XML document which
can contain
+ any number of update instructions. As it is an XML
document of itself,
+ the namespace bindings for prefixes used in the XUpdate
instructions
+ can be specified in the XUpdate string itself. They can
also be specified
+ as a <code>NamespaceMap</code> when calling a query
method on the resolver.
+ This may cause a conflict if the same prefix is bound
both in the XUpdate,
+ and in the provided <code>NamespaceMap</code>. By
default, Xindice will
+ take into account the value specified in the
<code>NamespaceMap</code> in
+ this case, though the behaviour can be altered by
modifying the
+
<code>org.apache.xindice.core.xupdate.XUpdateImpl.API_NS_PRECEDENCE</code>
+ constant in the source code and recompiling.</p>
+ <p>The
<code>org.apache.xindice.core.xupdate.XUpdateQueryResolver</code>
+ class provides a query resolver for XUpdate queries. Just
as the
+ XPath resolver, it always first compiles queries to a
+
<code>org.apache.xindice.core.xupdate.XUpdateQueryResolver.XUpdateQuery</code>,
+ wich it then immediately executes if the resolver's
<code>query()</code> method
+ was called.</p>
+ <p>Xindice uses the Lexus engine, produced at infozone.org
to parse and execute
+ XUpdate instructions. The
<code>org.apache.xindice.core.xupdate.XUpdateQueryResolver.XUpdateQuery</code>
+ and
<code>org.apache.xindice.core.xupdate.XUpdateImpl</code> classes basically
+ provide some glue around Lexus.</p>
+ <p>Lexus itself doesn't contain an XPath evaluator, and so
Xindice needs
+ to provide one to use Lexus. We saw earlier that Xindice
itself uses Xalan
+ for its XPath needs. To provide a valid XPath
implementation to Lexus,
+ another class
<code>org.apache.xindice.core.xupdate.XPathQueryImpl</code> exists
+ which encapsulates Xalan's XPath classes in a manner
suitable for Lexus. Don't
+ confuse this class with
<code>org.apache.core.query.XPathQueryResolver.XPathQuery</code>,
+ which also wraps around Xalan, but for use by Xindice's
own XPath query
+ resolver.</p>
+ <section>
+ <title>5.3.1. Selecting documents to update</title>
+ <p>When an XUpdate query is submitted with a specified
set of documents,
+ the all the XUpdate modification instructions are
performed on each
+ of the documents.</p>
+ <p>If however no documents are specified, Xindice
proceeds as follows:</p>
+ <ul>
+ <li>For each of the modification instructions, it
looks up the
+ <em>selector expression</em>, that is an XPath
expression that each
+ XUpdate modification instruction contains to
indicate <em>which</em>
+ node in a document should be modified.</li>
+ <li>Next, a complete XPath query is performed on the
collection, using
+ the
<code>org.apache.xindice.core.query.XPathQueryResolver</code> to
+ find all nodes matching the XPath in documents in
the collection, and
+ these nodes' containing documents are retained. Note
that this step
+ <em>might</em> make use of any indexes set up for
XPath, as determined
+ by the behaviour of the XPath query resoolver.</li>
+ <li>The XUpdate modification instruction is
performed on the retained
+ set of documents.</li>
+ </ul>
+ </section>
+ <section>
+ <title>5.3.2. Performing the updates</title>
+ <p>Whether explicitly passed as an argument to the query
method, or whether
+ determined by evaluating the selector expression on
the collection, the
+ set of documents is always processed as follows:</p>
+ <ul><li>Each document in the set is read in to a DOM
tree in memory using
+ the DOM Compressor and B-Tree filer classes.</li>
+ <li>Lexus updates this in-memory DOM representation
according to
+ the modification instructions.</li>
+ <li>Xindice writes the <em>entire document</em> back
using the
+ same DOM Compressor and B-Tree filer classes. The
modification time
+ <em>of the whole document</em> is updated
appropriately.</li>
+ </ul>
+ </section>
+ <section>
+ <title>5.3.3. Result</title>
+ <p>Xindice queries must always return results. XUpdate
queries always
+ return a result with exactly one XML resource that
looks like this:</p>
+<source><![CDATA[
+<?xml version="1.0"?>
+<src:modified
xmlns:src="http://xml.apache.org/xindice/Query";>4</src:modified>
+]]></source>
+ <p>It essentially indicates the number of updates that
the query performed.
+ To change the format of this XML, you'll have to
modify the
+ XUpdate query resolver's source code.</p>
+ </section>
</section>
</section>
<section>
