vgritsenko 2004/03/13 05:47:48
Modified: src/documentation/content/xdocs book.xml
Added: src/documentation/content/xdocs guide-xpath.xml
Log:
Add XPath guide to cover querying Documents, Elements, Text nodes, String,
Numbers
Revision Changes Path
1.11 +3 -2 xml-xindice/src/documentation/content/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-xindice/src/documentation/content/xdocs/book.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- book.xml 25 Feb 2004 13:38:03 -0000 1.10
+++ book.xml 13 Mar 2004 13:47:48 -0000 1.11
@@ -40,6 +40,7 @@
<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-tools.html"/>
+ <menu-item label="XPath Guide" href="guide-xpath.html"/>
<menu-item label="FAQ" href="faq.html"/>
<menu-item label="Wiki" href="http://wiki.apache.org/xindice"/>
<menu-item label="Javadocs" href="api/index.html"/>
1.1
xml-xindice/src/documentation/content/xdocs/guide-xpath.xml
Index: guide-xpath.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!--
- Copyright 1999-2004 The Apache Software Foundation.
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
-
- CVS $Id: guide-xpath.xml,v 1.1 2004/03/13 13:47:48 vgritsenko Exp $
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<!--
- Version: $Revision: 1.1 $ $Date: 2004/03/13 13:47:48 $
- Author: Vadim Gritsenko ([EMAIL PROTECTED])
-->
<document>
<header>
<title>Xindice 1.1 XPath Guide</title>
<version>$Revision: 1.1 $</version>
<authors>
<person id="VG" name="Vadim Gritsenko" email=""/>
</authors>
<notice/>
<abstract/>
</header>
<body>
<note>
If you notice incorrectness in this documentation, please
<link href="mail.html">notify</link> Xindice community. Your feedback
will help create better documentation.
</note>
<section>
<title>Querying the Database</title>
<p>
Xindice currently supports XPath as a query language. Queries can
be executed from within client application (please refer to the
<link href="guide-developer.html">developers giude</link>), through
XML-RPC interface, or via a command line (please refer to the
<link href="guide-tools.html">command line tool guide</link>).
This document describes what XPath queries are supported and what are
the results of the query.
</p>
</section>
<section>
<title>Sample Database</title>
<p>
XPath queries and results described below were run against sample
/db/addressbook collection. Documents in the addressbook collection
have following structure:
</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>
]]></source>
</section>
<section>
<title>Query for Document</title>
<p>
One of the common usages for XPath is to obtain documents satisfying
some criteria. Suppose we want to find everybody with the cell phone:
</p>
<source> xindice xpath -c /db/addressbook -q
"/person[phone/@type='cell']" </source>
<p>
Result of the query will be one or more documents. If you have only
two
person entries in the collection, then only one result will be found:
</p>
<source><![CDATA[
<person xmlns:src="http://xml.apache.org/xindice/Query";
src:col="/db/addressbook" src:key="address2">
<fname>SlackJawedLocal</fname>
<lname>Cletus</lname>
<phone type="work">123-456-7890</phone>
<phone type="home">234-567-8901</phone>
<phone type="cell">345-678-9012</phone>
<email type="home">[EMAIL PROTECTED]</email>
<email type="work">[EMAIL PROTECTED]</email>
<address type="home">1234 S. Elm St.</address>
<address type="work">4567 W. Pine St.</address>
</person>
]]></source>
</section>
<section>
<title>Query for Element</title>
<p>
Here we will issue a query resulting only in some elements from the
document.
Suppose we want to find everybody's home phone numbers:
</p>
<source> xindice xpath -c /db/addressbook -q "/person/[EMAIL
PROTECTED]'home']" </source>
<p>
Result of the query will be all elements satisfying criteria from all
documents.
</p>
<source><![CDATA[
<phone src:col="/db/addressbook" src:key="address1"
xmlns:src="http://xml.apache.org/xindice/Query";
type="home">534-567-8901</phone>
<phone src:col="/db/addressbook" src:key="address2"
xmlns:src="http://xml.apache.org/xindice/Query";
type="home">234-567-8901</phone>
]]></source>
</section>
<section>
<title>Query for Text Node</title>
<p>
With Xindice 1.1b4 and above, it is possible to query for text nodes.
Each
resulting text node will be wrapped into <code>result</code> element
in the
Query namespace.
</p>
<source> xindice xpath -c /db/addressbook -q
"/person[fname='John']/phone/text()" </source>
<p>
Result of the query will be all phones for all Johns in the
collection.
</p>
<source><![CDATA[
<xq:result xmlns:xq="http://xml.apache.org/xindice/Query";
xq:col="/db/addressbook"
xq:key="address1">563-456-7890</xq:result>
<xq:result xmlns:xq="http://xml.apache.org/xindice/Query";
xq:col="/db/addressbook"
xq:key="address1">534-567-8901</xq:result>
]]></source>
</section>
<section>
<title>Query for String</title>
<p>
XPath expressions with String result are also supported.
</p>
<source> xindice xpath -c /db/addressbook -q
"string(/person[fname='John']/phone)" </source>
<p>
Result of the query will be first phone number for all Johns in the
collection,
and empty result for each non-John.
</p>
<source><![CDATA[
<xq:result xmlns:xq="http://xml.apache.org/xindice/Query";
xq:col="/db/addressbook"
xq:key="address1">563-456-7890</xq:result>
<xq:result xmlns:xq="http://xml.apache.org/xindice/Query";
xq:col="/db/addressbook" xq:key="address2"></xq:result>
]]></source>
<note>
Because XPath is evaluated against each document, and because
<code>string()</code> function always returns a result, such query
will produce
result from each document in the collection. In this example, result
from second
document is empty, as criteria <code>fname='John'</code> was not
satisfied.
</note>
</section>
<section>
<title>Query for Number</title>
<p>
XPath expressions with Number result are also supported.
</p>
<source> xindice xpath -c /db/addressbook -q "count(/person/phone)"
</source>
<p>
This XPath will return count of phone numbers on file for each
person. If person
does not have phone numbers, result for this person will be
<code>0.0</code>.
</p>
<source><![CDATA[
<xq:result xmlns:xq="http://xml.apache.org/xindice/Query";
xq:col="/db/addressbook" xq:key="address1">2.0</xq:result>
<xq:result xmlns:xq="http://xml.apache.org/xindice/Query";
xq:col="/db/addressbook" xq:key="address2">3.0</xq:result>
]]></source>
</section>
</body>
</document>
