[exo-jcr-commits] exo-jcr SVN: r2873 - jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching.
do-not-reply at jboss.org
do-not-reply at jboss.org
Wed Aug 4 08:33:18 EDT 2010
Author: sergiykarpenko
Date: 2010-08-04 08:33:17 -0400 (Wed, 04 Aug 2010)
New Revision: 2873
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exact-path-constraint.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/find-similar-nodes.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/higlight.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/index-boost-value.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/node-scope-index.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/regexp-indexing-rule.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/spell-checker.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/synonim-provider.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/tip-nodename-with-number.xml
Removed:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exaxt-path-constraint.xml
Modified:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/jcr-query-usecases.xml
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml
Log:
EXOJCR-869: jcr-query-usecases ported
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exact-path-constraint.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exact-path-constraint.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exact-path-constraint.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.ExactPathConstraint">
+ <title>Exact Path Constraint</title>
+
+ <para>Find a node with the primary type 'nt:file' that is located on the
+ exact path "/folder1/folder2/document1".</para>
+
+ <section>
+ <title>Repository Structure</title>
+
+ <para>Repository filled by different nodes. There are several folders
+ which contain other folders and files.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>root</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>folder1 (nt:folder)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>folder2 (nt:folder)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>document1 (nt:file) // This document we want to
+ find</para>
+ </listitem>
+
+ <listitem>
+ <para>folder3 (nt:folder)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>document1 (nt:file)</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query Execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// we want find 'document1'
+String sqlStatement = "SELECT * FROM nt:file WHERE jcr:path = '/folder1/folder2/document1'";
+// create query
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// we want to find 'document1'
+String xpathStatement = "/jcr:root/folder1[1]/folder2[1]/element(document1,nt:file)[1]";
+// create query
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para>Remark: The indexes [1] are used in order to get the same result as
+ the SQL statement. SQL by default only returns the first node, whereas
+ XPath fetches by default all nodes.</para>
+ </section>
+
+ <section>
+ <title>Fetching the Result</title>
+
+ <para>Let's get nodes:</para>
+
+ <programlisting>NodeIterator it = result.getNodes();
+
+if(it.hasNext())
+{
+ Node findedNode = it.nextNode();
+}</programlisting>
+
+ <para>NodeIterator will return expected "document1".</para>
+
+ <para>We can also get a table:</para>
+
+ <programlisting>String[] columnNames = result.getColumnNames();
+RowIterator rit = result.getRows();
+while (rit.hasNext())
+{
+ Row row = rit.nextRow();
+ // get values of the row
+ Value[] values = row.getValues();
+}</programlisting>
+
+ <para>Table content is: <table>
+ <title>Table content</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>jcr:path</entry>
+
+ <entry>jcr:score</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>/folder1/folder2/document1</entry>
+
+ <entry>1030</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </section>
+</section>
Deleted: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exaxt-path-constraint.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exaxt-path-constraint.xml 2010-08-04 12:10:15 UTC (rev 2872)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/exaxt-path-constraint.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -1,129 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<section id="JCR.ExactPathConstraint">
- <title>Exact Path Constraint</title>
-
- <para>Find a node with the primary type 'nt:file' that is located on the
- exact path "/folder1/folder2/document1".</para>
-
- <section>
- <title>Repository Structure</title>
-
- <para>Repository filled by different nodes. There are several folders
- which contain other folders and files.</para>
-
- <itemizedlist>
- <listitem>
- <para>root</para>
-
- <itemizedlist>
- <listitem>
- <para>folder1 (nt:folder)</para>
-
- <itemizedlist>
- <listitem>
- <para>folder2 (nt:folder)</para>
-
- <itemizedlist>
- <listitem>
- <para>document1 (nt:file) // This document we want to
- find</para>
- </listitem>
-
- <listitem>
- <para>folder3 (nt:folder)</para>
-
- <itemizedlist>
- <listitem>
- <para>document1 (nt:file)</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Query Execution</title>
-
- <para><emphasis role="bold">SQL</emphasis></para>
-
- <programlisting>// make SQL query
-QueryManager queryManager = workspace.getQueryManager();
-// we want find 'document1'
-String sqlStatement = "SELECT * FROM nt:file WHERE jcr:path = '/folder1/folder2/document1'";
-// create query
-Query query = queryManager.createQuery(sqlStatement, Query.SQL);
-// execute query and fetch result
-QueryResult result = query.execute();</programlisting>
-
- <para><emphasis role="bold">XPath</emphasis></para>
-
- <programlisting>// make SQL query
-QueryManager queryManager = workspace.getQueryManager();
-// we want to find 'document1'
-String xpathStatement = "/jcr:root/folder1[1]/folder2[1]/element(document1,nt:file)[1]";
-// create query
-Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
-// execute query and fetch result
-QueryResult result = query.execute();</programlisting>
-
- <para>Remark: The indexes [1] are used in order to get the same result as
- the SQL statement. SQL by default only returns the first node, whereas
- XPath fetches by default all nodes.</para>
- </section>
-
- <section>
- <title>Fetching the Result</title>
-
- <para>Let's get nodes:</para>
-
- <programlisting>NodeIterator it = result.getNodes();
-
-if(it.hasNext())
-{
- Node findedNode = it.nextNode();
-}</programlisting>
-
- <para>NodeIterator will return expected "document1".</para>
-
- <para>We can also get a table:</para>
-
- <programlisting>String[] columnNames = result.getColumnNames();
-RowIterator rit = result.getRows();
-while (rit.hasNext())
-{
- Row row = rit.nextRow();
- // get values of the row
- Value[] values = row.getValues();
-}</programlisting>
-
- <para>Table content is: <table>
- <title>Table content</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>jcr:path</entry>
-
- <entry>jcr:score</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>/folder1/folder2/document1</entry>
-
- <entry>1030</entry>
- </row>
- </tbody>
- </tgroup>
- </table></para>
- </section>
-</section>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/find-similar-nodes.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/find-similar-nodes.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/find-similar-nodes.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,196 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.FindSimilarNodes">
+ <title>Find Similar Nodes</title>
+
+ <para>Find similar nodes to node by path '/baseFile/jcr:content'.</para>
+
+ <para>In our example, baseFile will contain text where "terms" word happens
+ many time. Thats why existanse of this word will be used as a criteria of
+ node similarity (for node baseFile).</para>
+
+ <note>
+ <para>See also about Similarity and configuration - <link
+ linkend="JCR.SearchingRepositoryContent">Searching Repository
+ Content</link></para>
+ </note>
+
+ <para>Higlighting support must be added to configuration.
+ test-jcr-config.xml:</para>
+
+ <programlisting><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ ...
+ <property name="support-highlighting" value="true" />
+ ...
+ </properties>
+</query-handler></programlisting>
+
+ <section>
+ <title>Repository structure:</title>
+
+ <para>Repository contains many nt:file nodes"</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>root</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>baseFile (nt:file)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>jcr:content (nt:resource) jcr:data="Similarity is
+ determined by looking up <emphasis
+ role="bold">terms</emphasis> that are common to nodes. There
+ are some conditions that must be met for a <emphasis
+ role="bold">term</emphasis> to be considered. This is required
+ to limit the number possibly relevant <emphasis
+ role="bold">terms</emphasis>. Only <emphasis
+ role="bold">terms</emphasis> with at least 4 characters are
+ considered. Only <emphasis role="bold">terms</emphasis> that
+ occur at least 2 times in the source node are considered. Only
+ <emphasis role="bold">terms</emphasis> that occur in at least
+ 5 nodes are considered."</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>target1 (nt:file)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>jcr:content (nt:resource) jcr:data="Similarity is
+ determined by looking up <emphasis
+ role="bold">terms</emphasis> that are common to nodes."</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>target2 (nt:file)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>jcr:content (nt:resource) jcr:data="There is no you know
+ what"</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>target3 (nt:file)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>jcr:content (nt:resource) jcr:data=" <emphasis
+ role="bold">Terms</emphasis> occures here"</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String sqlStatement = "SELECT * FROM nt:resource WHERE SIMILAR(.,'/baseFile/jcr:content')";
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make XPath query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String xpathStatement = "//element(*, nt:resource)[rep:similar(., '/testroot/baseFile/jcr:content')]";
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Fetch result</title>
+
+ <para>Lets get nodes:</para>
+
+ <programlisting>NodeIterator it = result.getNodes();
+
+if(it.hasNext())
+{
+ Node findedNode = it.nextNode();
+}</programlisting>
+
+ <para>NodeIterator will return
+ "/baseFile/jcr:content","/target1/jcr:content" and
+ "/target3/jcr:content".</para>
+
+ <para>As you see base node are also in result set.</para>
+
+ <para>We can also get a table:</para>
+
+ <programlisting>String[] columnNames = result.getColumnNames();
+RowIterator rit = result.getRows();
+while (rit.hasNext())
+{
+ Row row = rit.nextRow();
+ // get values of the row
+ Value[] values = row.getValues();
+}</programlisting>
+
+ <para>The table content is</para>
+
+ <table>
+ <title>Table content</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>jcr:path</entry>
+
+ <entry>...</entry>
+
+ <entry>jcr:score</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>/baseFile/jcr:content</entry>
+
+ <entry>...</entry>
+
+ <entry>2674</entry>
+ </row>
+
+ <row>
+ <entry>/target1/jcr:content </entry>
+
+ <entry>...</entry>
+
+ <entry>2674</entry>
+ </row>
+
+ <row>
+ <entry>/target3/jcr:content </entry>
+
+ <entry>...</entry>
+
+ <entry>2674</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+</section>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/higlight.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/higlight.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/higlight.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.HiglightResultofFulltextSearch">
+ <title>Higlight Result of Fulltext Search</title>
+
+ <para>Also its called excerption (see Excerpt configuration in <link
+ linkend="JCR.SearchConfiguration">Search Configuration</link> and in <link
+ linkend="JCR.SearchingRepositoryContent.Highlighting">Searching
+ Repository</link> article).</para>
+
+ <para>The goal of this query is find words "eXo" and "implementation" with
+ fulltext search and highlight this words in result value.</para>
+
+ <section>
+ <title>Base info</title>
+
+ <para>Highlighting is not default feature so we must set it in
+ jcr-config.xml, also excerpt provider must be defined:</para>
+
+ <programlisting><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ ...
+ <property name="support-highlighting" value="true" />
+ <property name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.WeightedHTMLExcerpt"/>
+ ...
+ <properties>
+</query-handler></programlisting>
+
+ <para>Also remember that we can make indexing rules, as in example
+ below:</para>
+
+ <para>Let's write rule for all nodes with primary node type
+ 'nt:unstructed' where property 'rule' equal to "excerpt" string. For those
+ nodes we will exclude property "title" from highlighting and set "text"
+ property as highlightable. indexing-configuration.xml must containt next
+ rule:</para>
+
+ <programlisting><index-rule nodeType="nt:unstructured" condition="@rule='excerpt'">
+ <property useInExcerpt="false">title</property>
+ <property>text</property>
+</index-rule></programlisting>
+ </section>
+
+ <section>
+ <title>Repository structure:</title>
+
+ <para>We have single node with primary type 'nt:unstructured'</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>document (nt:unstructured)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>rule = "excerpt"</para>
+ </listitem>
+
+ <listitem>
+ <para>title = "eXoJCR"</para>
+ </listitem>
+
+ <listitem>
+ <para>text = "eXo is a JCR implementation"</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String sqlStatement = "SELECT rep:excerpt() FROM nt:unstructured WHERE CONTAINS(*, 'eXo implementation')";
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make XPath query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String xpathStatement = "//element(*,nt:unstructured)[jcr:contains(., 'eXo implementation')]/rep:excerpt(.)";
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Fetch result</title>
+
+ <para>Now lets see on result table:</para>
+
+ <programlisting>String[] columnNames = result.getColumnNames();
+RowIterator rit = result.getRows();
+while (rit.hasNext())
+{
+ Row row = rit.nextRow();
+ // get values of the row
+ Value[] values = row.getValues();
+}</programlisting>
+
+ <para>Table content is </para>
+
+ <table>
+ <title>Table content</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>rep:excerpt()</entry>
+
+ <entry>jcr:path</entry>
+
+ <entry>jcr:score</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>\<div\>\<span\>\<strong\>eXo\</strong\>
+ is a JCR
+ \<strong\>implementation\</strong\>\</span\>\</div\></entry>
+
+ <entry>/testroot/node1</entry>
+
+ <entry>335</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>As you see, words "eXo" and "implamentation" is highlighted.</para>
+
+ <para>Also we can get exactly "rep:excerpt" value:</para>
+
+ <programlisting>RowIterator rows = result.getRows();
+Value excerpt = rows.nextRow().getValue("rep:excerpt(.)");
+// excerpt will be equal to "<div><span\><strong>eXo</strong> is a JCR <strong>implementation</strong></span></div>"</programlisting>
+ </section>
+</section>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/index-boost-value.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/index-boost-value.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/index-boost-value.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.IndexBoostRule">
+ <title>Change Priority of Node</title>
+
+ <para>In this example, we will set different boost values for predefined
+ nodes, and will check effect by selecting those nodes and order them by
+ jcr:score.</para>
+
+ <para>The default boost value is 1.0. Higher boost values (a reasonable
+ range is 1.0 - 5.0) will yield a higher score value and appear as more
+ relevant.</para>
+
+ <note>
+ <para>See 4.2.2 Index Boost Value <link
+ linkend="JCR.SearchConfiguration">Search Configuration</link> </para>
+ </note>
+
+ <section>
+ <title>Indexing configuration</title>
+
+ <para>In next configuration we will set boost values for nt:ustructured
+ nodes 'text' property. </para>
+
+ <para>indexing-config.xml:</para>
+
+ <programlisting><!--
+This rule actualy do nothing. 'text' property has default boost value.
+-->
+<index-rule nodeType="nt:unstructured" condition="@rule='boost1'">
+ <!-- default boost: 1.0 -->
+ <property>text</property>
+</index-rule>
+
+<!--
+Set boost value as 2.0 for 'text' property in nt:unstructured nodes where property 'rule' equal to 'boost2'
+-->
+<index-rule nodeType="nt:unstructured" condition="@rule='boost2'">
+ <!-- boost: 2.0 -->
+ <property boost="2.0">text</property>
+</index-rule>
+
+<!--
+Set boost value as 3.0 for 'text' property in nt:unstructured nodes where property 'rule' equal to 'boost3'
+-->
+<index-rule nodeType="nt:unstructured" condition="@rule='boost3'">
+ <!-- boost: 3.0 -->
+ <property boost="3.0">text</property>
+</index-rule></programlisting>
+ </section>
+
+ <section>
+ <title>Repository structure:</title>
+
+ <para>Repository contains many nodes with primary type nt:unstructured.
+ Each node contains 'text' property and 'rule' property with different
+ values.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>root</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>node1(nt:unstructured) rule='boost1' text='The quick brown
+ fox jump...'</para>
+ </listitem>
+
+ <listitem>
+ <para>node2(nt:unstructured) rule='boost2' text='The quick brown
+ fox jump...'</para>
+ </listitem>
+
+ <listitem>
+ <para>node3(nt:unstructured) rule='boost3' text='The quick brown
+ fox jump...'</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String sqlStatement = "SELECT * FROM nt:unstructured WHERE CONTAINS(text, 'quick') ORDER BY jcr:score() DESC";
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make XPath query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String xpathStatement = "//element(*,nt:unstructured)[jcr:contains(@text, 'quick')] order by @jcr:score descending";
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Fetch result</title>
+
+ <para>Lets get nodes:</para>
+
+ <programlisting>NodeIterator it = result.getNodes();
+
+if(it.hasNext())
+{
+ Node findedNode = it.nextNode();
+}</programlisting>
+
+ <para>NodeIterator will return nodes in next order "node3", "node2",
+ "node1".</para>
+ </section>
+</section>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/jcr-query-usecases.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/jcr-query-usecases.xml 2010-08-04 12:10:15 UTC (rev 2872)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/jcr-query-usecases.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -1,317 +1,414 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="JCR.QueryUsecases">
- <title>JCR Query Usecases</title>
-
- <section>
- <title>Intro</title>
-
- <para>JCR supports two query languages - JCR and XPath. A query, whether
- XPath or SQL, specifies a subset of nodes within a workspace, called the
- result set. The result set constitutes all the nodes in the workspace that
- meet the constraints stated in the query.</para>
- </section>
-
- <section>
- <title>Query Lifecycle</title>
-
- <section>
- <title>Query Creation and Execution</title>
-
- <para><emphasis role="bold">SQL</emphasis></para>
-
- <programlisting>// get QueryManager
-QueryManager queryManager = workspace.getQueryManager();
-// make SQL query
-Query query = queryManager.createQuery("SELECT * FROM nt:base ", Query.SQL);
-// execute query
-QueryResult result = query.execute();</programlisting>
-
- <para><emphasis role="bold">XPath</emphasis></para>
-
- <programlisting>// get QueryManager
-QueryManager queryManager = workspace.getQueryManager();
-// make XPath query
-Query query = queryManager.createQuery("//element(*,nt:base)", Query.XPATH);
-// execute query
-QueryResult result = query.execute();</programlisting>
- </section>
-
- <section>
- <title>Query Result Processing</title>
-
- <programlisting>// fetch query result
-QueryResult result = query.execute();</programlisting>
-
- <para>Now we can get result in an iterator of nodes:</para>
-
- <programlisting>NodeIterator it = result.getNodes();</programlisting>
-
- <para>or we get the result in a table:</para>
-
- <programlisting>// get column names
-String[] columnNames = result.getColumnNames();
-// get column rows
-RowIterator rowIterator = result.getRows();
-while(rowIterator.hasNext()){
- // get next row
- Row row = rowIterator.nextRow();
- // get all values of row
- Value[] values = row.getValues();
-}</programlisting>
- </section>
-
- <section>
- <title>Scoring</title>
-
- <para>The result returns a score for each row in the result set. The
- score contains a value that indicates a rating of how well the result
- node matches the query. A high value means a better matching than a low
- value. This score can be used for ordering the result.</para>
-
- <para>eXo JCR Scoring is a mapping of Lucene scoring. For a more
- in-depth understanding, please study <ulink
- url="http://lucene.apache.org/java/2_4_1/scoring.html">Lucene
- documentation</ulink>.</para>
-
- <para>jcr:score counted in next way - (lucene score)*1000f.</para>
-
- <para>Score may be increased for specified nodes, see <ulink
- url="Index Boost Value">Index Boost Value</ulink></para>
-
- <para>Also, see an example <link linkend="JCR.OrderByScore">Order by
- Score</link></para>
- </section>
- </section>
-
- <section>
- <title>Query Examples</title>
-
- <section>
- <title>Query result settings</title>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="JCR.SetOffsetandSetLimit">Set Offset And
- Limit</link></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Type Constraints</title>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="JCR.FindAllNodes">Find All Nodes</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.FindNodesByPrimaryType">Find Nodes by
- Primary Type</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.FindNodesByMixinType">Find Nodes by Mixin
- Type</link></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Property Constraints</title>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="JCR.PropertyComparison">Property
- Comparison</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.LIKEConstraint">LIKE
- Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.EscapinginLIKEStatements">Escaping in LIKE
- Statements</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.NOTConstraint">NOT Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.ANDConstraint">AND Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.ORConstraint">OR Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.PropertyExistenceConstraint">Property
- Existence Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.FindNodesCaseInsensitive">Upper and Lower
- Case Constraints</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.DatePropertyComparison">Date Property
- Comparison</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.NodeNameConstraint">Node Name
- Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.MultivaluePropertyComparison">Multivalue
- Property Comparison</link></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Path Constraint</title>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="JCR.ExactPathConstraint">Exact Path
- Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.ChildNodeConstraint">Child Node
- Constraint</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.FindAllDescendantNodes">Find All Descendant
- Nodes</link></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Ordering specifing</title>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="JCR.OrderByProperty">Order by
- Property</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.OrderByDescendant">Order by Descendant Node
- Property</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.OrderByScore">Order by Score</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.OrderByPathOrName">Order by Path or
- Name</link></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title><link linkend="JCR.FulltextSearchAndSettings">Fulltext
- Search</link></title>
-
- <itemizedlist>
- <listitem>
- <para><link linkend="JCR.FulltextSearchByProperty">Fulltext Search
- by Property</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.FulltextSearchByAllProperties">Fulltext
- Search by All Properties</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.AggregationRule">Find nt:file document by
- content of child jcr:content node</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="JCR.IgnoreAccentSymbols">How to set new
- Analyzer. Accent symblos ignoring</link></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Indexing rules and additional features</title>
-
- <itemizedlist>
- <listitem>
- <para><ulink url="Aggregation rule">Aggregation rule</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="JCR.Search Result Highlighting">JCR.Search Result
- Highlighting</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="Index Boost Value">Index Boost
- Value</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink
- url="Exclusion from the Node Scope Index>JCR.Node Scope Index">Exclusion
- from the Node Scope Index>JCR.Node Scope Index</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink
- url="Regular expressions as property name in indexing rule > Regexp Indexing Rule">Regular
- expressions as property name in indexing rule > Regexp Indexing
- Rule</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="Synonim Provider">Synonim Provider</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="Spell Checking">Spell Checking</ulink></para>
- </listitem>
-
- <listitem>
- <para><ulink url="Find Similar Nodes">Find Similar
- Nodes</ulink></para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>List of examples</title>
-
- <xi:include href="offset-and-limit.xml"
- xmlns:xi="http://www.w3.org/2001/XInclude" />
- </section>
- </section>
-
- <section>
- <title>Tips and tricks</title>
-
- <itemizedlist>
- <listitem>
- <para><ulink url="Xpath and numbers in node names">Xpath and numbers
- in node names</ulink></para>
- </listitem>
- </itemizedlist>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.QueryUsecases">
+ <?dbhtml filename="ch-jcr-query-usecases.html"?>
+
+ <title>JCR Query Usecases</title>
+
+ <section>
+ <title>Intro</title>
+
+ <para>JCR supports two query languages - JCR and XPath. A query, whether
+ XPath or SQL, specifies a subset of nodes within a workspace, called the
+ result set. The result set constitutes all the nodes in the workspace that
+ meet the constraints stated in the query.</para>
+ </section>
+
+ <section>
+ <title>Query Lifecycle</title>
+
+ <section>
+ <title>Query Creation and Execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// get QueryManager
+QueryManager queryManager = workspace.getQueryManager();
+// make SQL query
+Query query = queryManager.createQuery("SELECT * FROM nt:base ", Query.SQL);
+// execute query
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// get QueryManager
+QueryManager queryManager = workspace.getQueryManager();
+// make XPath query
+Query query = queryManager.createQuery("//element(*,nt:base)", Query.XPATH);
+// execute query
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Query Result Processing</title>
+
+ <programlisting>// fetch query result
+QueryResult result = query.execute();</programlisting>
+
+ <para>Now we can get result in an iterator of nodes:</para>
+
+ <programlisting>NodeIterator it = result.getNodes();</programlisting>
+
+ <para>or we get the result in a table:</para>
+
+ <programlisting>// get column names
+String[] columnNames = result.getColumnNames();
+// get column rows
+RowIterator rowIterator = result.getRows();
+while(rowIterator.hasNext()){
+ // get next row
+ Row row = rowIterator.nextRow();
+ // get all values of row
+ Value[] values = row.getValues();
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Scoring</title>
+
+ <para>The result returns a score for each row in the result set. The
+ score contains a value that indicates a rating of how well the result
+ node matches the query. A high value means a better matching than a low
+ value. This score can be used for ordering the result.</para>
+
+ <para>eXo JCR Scoring is a mapping of Lucene scoring. For a more
+ in-depth understanding, please study <ulink
+ url="http://lucene.apache.org/java/2_4_1/scoring.html">Lucene
+ documentation</ulink>.</para>
+
+ <para>jcr:score counted in next way - (lucene score)*1000f.</para>
+
+ <para>Score may be increased for specified nodes, see <ulink
+ url="Index Boost Value">Index Boost Value</ulink></para>
+
+ <para>Also, see an example <link linkend="JCR.OrderByScore">Order by
+ Score</link></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Query result settings</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.SetOffsetandSetLimit">Set Offset And
+ Limit</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Type Constraints</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.FindAllNodes">Find All Nodes</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.FindNodesByPrimaryType">Find Nodes by Primary
+ Type</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.FindNodesByMixinType">Find Nodes by Mixin
+ Type</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Property Constraints</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.PropertyComparison">Property
+ Comparison</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.LIKEConstraint">LIKE Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.EscapinginLIKEStatements">Escaping in LIKE
+ Statements</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.NOTConstraint">NOT Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.ANDConstraint">AND Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.ORConstraint">OR Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.PropertyExistenceConstraint">Property
+ Existence Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.FindNodesCaseInsensitive">Upper and Lower
+ Case Constraints</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.DatePropertyComparison">Date Property
+ Comparison</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.NodeNameConstraint">Node Name
+ Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.MultivaluePropertyComparison">Multivalue
+ Property Comparison</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Path Constraint</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.ExactPathConstraint">Exact Path
+ Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.ChildNodeConstraint">Child Node
+ Constraint</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.FindAllDescendantNodes">Find All Descendant
+ Nodes</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Ordering specifing</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.OrderByProperty">Order by
+ Property</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.OrderByDescendant">Order by Descendant Node
+ Property</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.OrderByScore">Order by Score</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.OrderByPathOrName">Order by Path or
+ Name</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title><link linkend="JCR.FulltextSearchAndSettings">Fulltext
+ Search</link></title>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.FulltextSearchByProperty">Fulltext Search by
+ Property</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.FulltextSearchByAllProperties">Fulltext
+ Search by All Properties</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.AggregationRule">Find nt:file document by
+ content of child jcr:content node</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.IgnoreAccentSymbols">How to set new Analyzer.
+ Accent symblos ignoring</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Indexing rules and additional features</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.AggregationRule">Aggregation
+ rule</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.HiglightResultofFulltextSearch">Search Result
+ Highlighting</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.IndexBoostRule">Index Boost
+ Value</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.NodeScopeIndex">Exclusion from the Node Scope
+ Index</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.RegexpIndexingRule">Regular expressions as
+ property name in indexing rule</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.SynonimProvider">Synonim
+ Provider</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.SpellChecker">Spell Checking</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="JCR.FindSimilarNodes">Find Similar
+ Nodes</link></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query Examples</title>
+
+ <xi:include href="offset-and-limit.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="find-all-nodes.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="find-nodes-by-primary-type.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="find-nodes-by-mixin-type.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="property-comparison.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="like-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="escaping-like-statements.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="not-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="and-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="or-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="property-existance-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="find-nodes-case-insensitive.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="date-property-comparison.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="node-name-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="multivalue-property-comparison.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="exact-path-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="child-node-constraint.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="find-all-descendant-nodes.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="order-by-property.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="order-by-descendant.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="order-by-score.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="order-by-path-or-name.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="fulltext-search-by-property.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="fulltext-search-by-all-properties.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="ignore-accent-symbols.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="aggregation-rule.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="index-boost-value.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="node-scope-index.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="regexp-indexing-rule.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="higlight.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="synonim-provider.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="regexp-indexing-rule.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="spell-checker.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <xi:include href="find-similar-nodes.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </section>
+
+ <section>
+ <title>Tips and tricks</title>
+
+ <xi:include href="tip-nodename-with-number.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <!--itemizedlist>
+ <listitem>
+ <para><link linkend="JCR.TipNodeNameWithNumber">Xpath and numbers in
+ node names</link></para>
+ </listitem>
+ </itemizedlist-->
+ </section>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/node-scope-index.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/node-scope-index.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/node-scope-index.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,144 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.NodeScopeIndex">
+ <title>Remove Nodes Property From Indexing Scope</title>
+
+ <para>In this example, we will exclude some 'text' property of
+ nt:unstructured node from indexind. And, therefore, node will not be found
+ by content of this property, even if it accept all constraints.</para>
+
+ <para>First of all, add rules to indexing-configuration.xml:</para>
+
+ <programlisting><index-rule nodeType="nt:unstructured" condition="@rule='nsiTrue'">
+ <!-- default value for nodeScopeIndex is true -->
+ <property>text</property>
+</index-rule>
+
+<index-rule nodeType="nt:unstructured" condition="@rule='nsiFalse'">
+ <!-- do not include text in node scope index -->
+ <property nodeScopeIndex="false">text</property>
+</index-rule></programlisting>
+
+ <note>
+ <para>See <link linkend="JCR.SearchConfiguration">Search
+ Configuration</link></para>
+ </note>
+
+ <section>
+ <title>Repository structure:</title>
+
+ <para>Repository contains nt:unstructured nodes, with same 'text'property
+ and different 'rule' properties (even null)</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>root</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>node1 (nt:unstructured) rule="nsiTrue" text="The quick brown
+ fox ..."</para>
+ </listitem>
+
+ <listitem>
+ <para>node2 (nt:unstructured) rule="nsiFalse" text="The quick
+ brown fox ..."</para>
+ </listitem>
+
+ <listitem>
+ <para>node3 (nt:unstructured) text="The quick brown fox ..." // as
+ you see this node not mentioned in indexing-coniguration</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String sqlStatement = "SELECT * FROM nt:unstructured WHERE CONTAINS(*,'quick')";
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make XPath query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String xpathStatement = "//element(*,nt:unstructured)[jcr:contains(., 'quick')]";
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Fetch result</title>
+
+ <para>Lets get nodes:</para>
+
+ <programlisting>NodeIterator it = result.getNodes();
+
+if(it.hasNext())
+{
+ Node findedNode = it.nextNode();
+}</programlisting>
+
+ <para>NodeIterator will return "node1" and "node3". Node2, as you see, is
+ not in result set.</para>
+
+ <para>Also we can get a table:</para>
+
+ <programlisting>String[] columnNames = result.getColumnNames();
+RowIterator rit = result.getRows();
+while (rit.hasNext())
+{
+ Row row = rit.nextRow();
+ // get values of the row
+ Value[] values = row.getValues();
+}</programlisting>
+
+ <para>Table contant is</para>
+
+ <table>
+ <title>Table content</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>jcr:primarytype</entry>
+
+ <entry>jcr:path</entry>
+
+ <entry>jcr:score</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>nt:unstructured</entry>
+
+ <entry>/node1</entry>
+
+ <entry>3806</entry>
+ </row>
+
+ <row>
+ <entry>nt:unstructured</entry>
+
+ <entry>/node3 </entry>
+
+ <entry>3806</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+</section>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/regexp-indexing-rule.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/regexp-indexing-rule.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/regexp-indexing-rule.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,141 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.RegexpIndexingRule">
+ <title>Regular Expression as Property Name in Indexing Rules</title>
+
+ <para>In this example, we want configure indexind in next way. All
+ properties of nt:unstructured nodes must be excluded from search, except
+ properties which names ends with 'Text' string. First of all, add rules to
+ indexing-configuration.xml:</para>
+
+ <programlisting><index-rule nodeType="nt:unstructured"">
+ <property isRegexp="true">.*Text</property>
+</index-rule></programlisting>
+
+ <note>
+ <para>See <link linkend="JCR.SearchConfiguration">Search
+ Configuration</link></para>
+ </note>
+
+ <para>Now, lets check this rule with simple query - select all nodes with
+ primary type 'nt:unstructured' and containing 'quick' string (fulltext
+ search by full node).</para>
+
+ <section>
+ <title>Repository structure:</title>
+
+ <para>Repository contains nt:unstructured nodes, with different
+ 'text'-like named properties</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>root</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>node1 (nt:unstructured) Text="The quick brown fox
+ ..."</para>
+ </listitem>
+
+ <listitem>
+ <para>node2 (nt:unstructured) OtherText="The quick brown fox
+ ..."</para>
+ </listitem>
+
+ <listitem>
+ <para>node3 (nt:unstructured) Textle="The quick brown fox
+ ..."</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String sqlStatement = "SELECT * FROM nt:unstructured WHERE CONTAINS(*,'quick')";
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make XPath query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String xpathStatement = "//element(*,nt:unstructured)[jcr:contains(., 'quick')]";
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Fetch result</title>
+
+ <para>Lets get nodes:</para>
+
+ <programlisting>NodeIterator it = result.getNodes();
+
+if(it.hasNext())
+{
+ Node findedNode = it.nextNode();
+}</programlisting>
+
+ <para>NodeIterator will return "node1" and "node2". "node3", as you see,
+ is not in result set.</para>
+
+ <para>Also we can get a table:</para>
+
+ <programlisting>String[] columnNames = result.getColumnNames();
+RowIterator rit = result.getRows();
+while (rit.hasNext())
+{
+ Row row = rit.nextRow();
+ // get values of the row
+ Value[] values = row.getValues();
+}</programlisting>
+
+ <para>Table contant is</para>
+
+ <table>
+ <title>Table content</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>jcr:primarytype</entry>
+
+ <entry>jcr:path</entry>
+
+ <entry>jcr:score</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>nt:unstructured</entry>
+
+ <entry>/node1</entry>
+
+ <entry>3806</entry>
+ </row>
+
+ <row>
+ <entry>nt:unstructured</entry>
+
+ <entry>/node2</entry>
+
+ <entry>3806</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+</section>
Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml 2010-08-04 12:10:15 UTC (rev 2872)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/searching-repository-content.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -1,374 +1,374 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="JCR.SearchingRepositoryContent">
- <?dbhtml filename="ch-jcr-searching-repository-conten.html"?>
-
- <title>Searching Repository Content</title>
-
- <section id="Introduction">
- <title>Introduction</title>
-
- <para>You can find the JCR configuration file here:
- .../portal/WEB-INF/conf/jcr/repository-configuration.xml. Please read also
- <link linkend="JCR.SearchConfiguration">Search Configuration</link> for
- more information about index configuration.</para>
- </section>
-
- <section id="BidirectionalRangeIteratorsince1.9">
- <title>Bi-directional RangeIterator (since 1.9)</title>
-
- <para>QueryResult.getNodes() will return bi-directional NodeIterator
- implementation.</para>
-
- <note>
- <para>Bi-directional NodeIterator is <emphasis role="bold">not
- supported</emphasis> in two cases:</para>
-
- <itemizedlist>
- <listitem>
- <para>SQL query: select * from nt:base</para>
- </listitem>
-
- <listitem>
- <para>XPath query: //* .</para>
- </listitem>
- </itemizedlist>
-
- <para>")</para>
- </note>
-
- <para>TwoWayRangeIterator interface:</para>
-
- <programlisting>/**
- * Skip a number of elements in the iterator.
- *
- * @param skipNum the non-negative number of elements to skip
- * @throws java.util.NoSuchElementException if skipped past the first element
- * in the iterator.
- */
-public void skipBack(long skipNum);</programlisting>
-
- <para>Usage:</para>
-
- <programlisting>NodeIterator iter = queryResult.getNodes();
-while (iter.hasNext()) {
- if (skipForward) {
- iter.skip(10); // Skip 10 nodes in forward direction
- } else if (skipBack) {
- TwoWayRangeIterator backIter = (TwoWayRangeIterator) iter;
- backIter.skipBack(10); // Skip 10 nodes back
- }
- .......
-}</programlisting>
- </section>
-
- <section id="FuzzySearchessince1.0">
- <title>Fuzzy Searches (since 1.0)</title>
-
- <para>JCR supports such features as Lucene Fuzzy Searches <ulink
- url="http://lucene.apache.org/java/2_3_2/queryparsersyntax.html">Apache
- Lucene - Query Parser Syntax</ulink>.</para>
-
- <para>To use it you have to form a query like described below:</para>
-
- <programlisting>QueryManager qman = session.getWorkspace().getQueryManager();
-Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL);
-QueryResult res = q.execute();</programlisting>
- </section>
-
- <section id="SynonymSearchsince1.9">
- <title>SynonymSearch (since 1.9)</title>
-
- <para>Searching with synonyms is integrated in the jcr:contains() function
- and uses the same syntax as synonym searches in Google. If a search term
- is prefixed by a tilde symbol ( ~ ) also synonyms of the search term are
- taken into consideration. Example:</para>
-
- <programlisting>SQL: select * from nt:resource where contains(., '~parameter')
-
-XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')</programlisting>
-
- <para>This feature is disabled per default and you need to add a
- configuration parameter to the query-handler element in your jcr
- configuration file to enable it.</para>
-
- <programlisting><param name="synonymprovider-config-path" value="..you path to configuration file....."/>
-<param name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/></programlisting>
-
- <programlisting>/**
- * <code>SynonymProvider</code> defines an interface for a component that
- * returns synonyms for a given term.
- */
-public interface SynonymProvider {
-
- /**
- * Initializes the synonym provider and passes the file system resource to
- * the synonym provider configuration defined by the configuration value of
- * the <code>synonymProviderConfigPath</code> parameter. The resource may be
- * <code>null</code> if the configuration parameter is not set.
- *
- * @param fsr the file system resource to the synonym provider
- * configuration.
- * @throws IOException if an error occurs while initializing the synonym
- * provider.
- */
- public void initialize(InputStream fsr) throws IOException;
-
- /**
- * Returns an array of terms that are considered synonyms for the given
- * <code>term</code>.
- *
- * @param term a search term.
- * @return an array of synonyms for the given <code>term</code> or an empty
- * array if no synonyms are known.
- */
- public String[] getSynonyms(String term);
-}</programlisting>
- </section>
-
- <section id="HighlightingSince1.9">
- <title>Highlighting (Since 1.9)</title>
-
- <para>An ExcerptProvider retrieves text excerpts for a node in the query
- result and marks up the words in the text that match the query
- terms.</para>
-
- <para>Per default highlighting words that matched the query is disabled
- because this feature requires that additional information is written to
- the search index. To enable this feature you need to add a configuration
- parameter to the query-handler element in your jcr configuration file to
- enable it.</para>
-
- <programlisting><param name="support-highlighting" value="true"/></programlisting>
-
- <para>Additionally there is a parameter that controls the format of the
- excerpt created. In JCR 1.9 the default is set to
- org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt.
- The configuration parameter for this setting is:</para>
-
- <programlisting><param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/></programlisting>
-
- <section id="DefaultXMLExcerpt">
- <title>DefaultXMLExcerpt</title>
-
- <para>This excerpt provider creates an XML fragment of the following
- form:</para>
-
- <programlisting><excerpt>
- <fragment>
- <highlight>exoplatform</highlight> implements both the mandatory
- XPath and optional SQL <highlight>query</highlight> syntax.
- </fragment>
- <fragment>
- Before parsing the XPath <highlight>query</highlight> in
- <highlight>exoplatform</highlight>, the statement is surrounded
- </fragment>
-</excerpt></programlisting>
- </section>
-
- <section id="DefaultHTMLExcerpt">
- <title>DefaultHTMLExcerpt</title>
-
- <para>This excerpt provider creates an HTML fragment of the following
- form:</para>
-
- <programlisting><div>
- <span>
- <strong>exoplatform</strong> implements both the mandatory XPath
- and optional SQL <strong>query</strong> syntax.
- </span>
- <span>
- Before parsing the XPath <strong>query</strong> in
- <strong>exoplatform</strong>, the statement is surrounded
- </span>
-</div></programlisting>
- </section>
-
- <section id="Howtouseit">
- <title>How to use it</title>
-
- <para>If you are using XPath you must use the rep:excerpt() function in
- the last location step, just like you would select properties:</para>
-
- <programlisting>QueryManager qm = session.getWorkspace().getQueryManager();
-Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH);
-QueryResult result = q.execute();
-for (RowIterator it = result.getRows(); it.hasNext(); ) {
- Row r = it.nextRow();
- Value title = r.getValue("Title");
- Value excerpt = r.getValue("rep:excerpt(.)");
-}</programlisting>
-
- <para>The above code searches for nodes that contain the word
- exoplatform and then gets the value of the Title property and an excerpt
- for each result node.</para>
-
- <para>It is also possible to use a relative path in the call
- Row.getValue() while the query statement still remains the same. Also
- you may use a relative path to a string property. The returned value
- will then be an excerpt based on string value of the property.</para>
-
- <para>Both available excerpt provider will create fragments of about 150
- characters and up to 3 fragments.</para>
-
- <para>In SQL the function is called excerpt() without the rep prefix,
- but the column in the RowIterator will nonetheless be labled
- rep:excerpt(.)!</para>
-
- <programlisting>QueryManager qm = session.getWorkspace().getQueryManager();
-Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL);
-QueryResult result = q.execute();
-for (RowIterator it = result.getRows(); it.hasNext(); ) {
- Row r = it.nextRow();
- Value excerpt = r.getValue("rep:excerpt(.)");
-}</programlisting>
- </section>
- </section>
-
- <section id="SpellChecker">
- <title>SpellChecker</title>
-
- <para>The lucene based query handler implementation supports a pluggable
- spell checker mechanism. Per default spell checking is not available and
- you have to configure it first. See parameter spellCheckerClass on page
- <link linkend="JCR.SearchConfiguration">Search Configuration</link> JCR
- currently provides an implementation class , which uses the <ulink
- url="http://wiki.apache.org/jakarta-lucene/SpellChecker">lucene-spellchecker</ulink>
- contrib . The dictionary is derived from the fulltext indexed content of
- the workspace and updated periodically. You can configure the refresh
- interval by picking one of the available inner classes of
- org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker:</para>
-
- <itemizedlist>
- <listitem>
- <para>OneMinuteRefreshInterval</para>
- </listitem>
-
- <listitem>
- <para>FiveMinutesRefreshInterval</para>
- </listitem>
-
- <listitem>
- <para>ThirtyMinutesRefreshInterval</para>
- </listitem>
-
- <listitem>
- <para>OneHourRefreshInterval</para>
- </listitem>
-
- <listitem>
- <para>SixHoursRefreshInterval</para>
- </listitem>
-
- <listitem>
- <para>TwelveHoursRefreshInterval</para>
- </listitem>
-
- <listitem>
- <para>OneDayRefreshInterval</para>
- </listitem>
- </itemizedlist>
-
- <para>E.g. if you want a refresh interval of six hours the class name is:
- org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval.
- If you use
- org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker
- the refresh interval will be one hour.</para>
-
- <para>The spell checker dictionary is stored as a lucene index under
- <emphasis role="bold">"index-dir"/spellchecker</emphasis>. If it does not
- exist, a background thread will create it on startup. Similarly the
- dictionary refresh is also done in a background thread to not block
- regular queries.</para>
-
- <section id="HowdoIuseit">
- <title>How do I use it?</title>
-
- <para>You can spell check a fulltext statement either with an XPath or a
- SQL query:</para>
-
- <programlisting>// rep:spellcheck('explatform') will always evaluate to true
-Query query = qm.createQuery("/jcr:root[rep:spellcheck('explatform')]/(rep:spellcheck())", Query.XPATH);
-RowIterator rows = query.execute().getRows();
-// the above query will always return the root node no matter what string we check
-Row r = rows.nextRow();
-// get the result of the spell checking
-Value v = r.getValue("rep:spellcheck()");
-if (v == null) {
- // no suggestion returned, the spelling is correct or the spell checker
- // does not know how to correct it.
-} else {
- String suggestion = v.getString();
-}</programlisting>
-
- <para>And the same using SQL:</para>
-
- <programlisting>// SPELLCHECK('exoplatform') will always evaluate to true
-Query query = qm.createQuery("SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('explatform')", Query.SQL);
-RowIterator rows = query.execute().getRows();
-// the above query will always return the root node no matter what string we check
-Row r = rows.nextRow();
-// get the result of the spell checking
-Value v = r.getValue("rep:spellcheck()");
-if (v == null) {
- // no suggestion returned, the spelling is correct or the spell checker
- // does not know how to correct it.
-} else {
- String suggestion = v.getString();
-}</programlisting>
- </section>
- </section>
-
- <section id="SimilaritySince1.12">
- <title>Similarity (Since 1.12)</title>
-
- <para>Starting with version, 1.12 JCR allows you to search for nodes that
- are similar to an existing node.</para>
-
- <para>Similarity is determined by looking up terms that are common to
- nodes. There are some conditions that must be met for a term to be
- considered. This is required to limit the number possibly relevant
- terms.</para>
-
- <itemizedlist>
- <listitem>
- <para>Only terms with at least 4 characters are considered.</para>
- </listitem>
-
- <listitem>
- <para>Only terms that occur at least 2 times in the source node are
- considered.</para>
- </listitem>
-
- <listitem>
- <para>Only terms that occur in at least 5 nodes are considered.</para>
- </listitem>
- </itemizedlist>
-
- <para>Note: The similarity functionality requires that the
- supportHightlighting is enabled. Please make sure that you have the
- following parameter set for the query handler in your
- workspace.xml.</para>
-
- <programlisting><param name="support-highlighting" value="true"/></programlisting>
-
- <para>The functions are called rep:similar() (in XPath) and similar() (in
- SQL) and have two arguments:</para>
-
- <para>relativePath: a relative path to a descendant node or . for the
- current node. absoluteStringPath: a string literal that contains the path
- to the node for which to find similar nodes.</para>
-
- <warning>
- <para>Relative path is not supported yet.</para>
- </warning>
-
- <para>Examples:</para>
-
- <programlisting>//element(*, nt:resource)[rep:similar(., '/parentnode/node.txt/jcr:content')]</programlisting>
-
- <para>Finds nt:resource nodes, which are similar to node by path
- /parentnode/node.txt/jcr:content.</para>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="JCR.SearchingRepositoryContent">
+ <?dbhtml filename="ch-jcr-searching-repository-conten.html"?>
+
+ <title>Searching Repository Content</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>You can find the JCR configuration file here:
+ .../portal/WEB-INF/conf/jcr/repository-configuration.xml. Please read also
+ <link linkend="JCR.SearchConfiguration">Search Configuration</link> for
+ more information about index configuration.</para>
+ </section>
+
+ <section>
+ <title>Bi-directional RangeIterator (since 1.9)</title>
+
+ <para>QueryResult.getNodes() will return bi-directional NodeIterator
+ implementation.</para>
+
+ <note>
+ <para>Bi-directional NodeIterator is <emphasis role="bold">not
+ supported</emphasis> in two cases:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>SQL query: select * from nt:base</para>
+ </listitem>
+
+ <listitem>
+ <para>XPath query: //* .</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>")</para>
+ </note>
+
+ <para>TwoWayRangeIterator interface:</para>
+
+ <programlisting>/**
+ * Skip a number of elements in the iterator.
+ *
+ * @param skipNum the non-negative number of elements to skip
+ * @throws java.util.NoSuchElementException if skipped past the first element
+ * in the iterator.
+ */
+public void skipBack(long skipNum);</programlisting>
+
+ <para>Usage:</para>
+
+ <programlisting>NodeIterator iter = queryResult.getNodes();
+while (iter.hasNext()) {
+ if (skipForward) {
+ iter.skip(10); // Skip 10 nodes in forward direction
+ } else if (skipBack) {
+ TwoWayRangeIterator backIter = (TwoWayRangeIterator) iter;
+ backIter.skipBack(10); // Skip 10 nodes back
+ }
+ .......
+}</programlisting>
+ </section>
+
+ <section>
+ <title>Fuzzy Searches (since 1.0)</title>
+
+ <para>JCR supports such features as Lucene Fuzzy Searches <ulink
+ url="http://lucene.apache.org/java/2_3_2/queryparsersyntax.html">Apache
+ Lucene - Query Parser Syntax</ulink>.</para>
+
+ <para>To use it you have to form a query like described below:</para>
+
+ <programlisting>QueryManager qman = session.getWorkspace().getQueryManager();
+Query q = qman.createQuery("select * from nt:base where contains(field, 'ccccc~')", Query.SQL);
+QueryResult res = q.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>SynonymSearch (since 1.9)</title>
+
+ <para>Searching with synonyms is integrated in the jcr:contains() function
+ and uses the same syntax as synonym searches in Google. If a search term
+ is prefixed by a tilde symbol ( ~ ) also synonyms of the search term are
+ taken into consideration. Example:</para>
+
+ <programlisting>SQL: select * from nt:resource where contains(., '~parameter')
+
+XPath: //element(*, nt:resource)[jcr:contains(., '~parameter')</programlisting>
+
+ <para>This feature is disabled per default and you need to add a
+ configuration parameter to the query-handler element in your jcr
+ configuration file to enable it.</para>
+
+ <programlisting><param name="synonymprovider-config-path" value="..you path to configuration file....."/>
+<param name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider"/></programlisting>
+
+ <programlisting>/**
+ * <code>SynonymProvider</code> defines an interface for a component that
+ * returns synonyms for a given term.
+ */
+public interface SynonymProvider {
+
+ /**
+ * Initializes the synonym provider and passes the file system resource to
+ * the synonym provider configuration defined by the configuration value of
+ * the <code>synonymProviderConfigPath</code> parameter. The resource may be
+ * <code>null</code> if the configuration parameter is not set.
+ *
+ * @param fsr the file system resource to the synonym provider
+ * configuration.
+ * @throws IOException if an error occurs while initializing the synonym
+ * provider.
+ */
+ public void initialize(InputStream fsr) throws IOException;
+
+ /**
+ * Returns an array of terms that are considered synonyms for the given
+ * <code>term</code>.
+ *
+ * @param term a search term.
+ * @return an array of synonyms for the given <code>term</code> or an empty
+ * array if no synonyms are known.
+ */
+ public String[] getSynonyms(String term);
+}</programlisting>
+ </section>
+
+ <section id="JCR.SearchingRepositoryContent.Highlighting">
+ <title>Highlighting (Since 1.9)</title>
+
+ <para>An ExcerptProvider retrieves text excerpts for a node in the query
+ result and marks up the words in the text that match the query
+ terms.</para>
+
+ <para>Per default highlighting words that matched the query is disabled
+ because this feature requires that additional information is written to
+ the search index. To enable this feature you need to add a configuration
+ parameter to the query-handler element in your jcr configuration file to
+ enable it.</para>
+
+ <programlisting><param name="support-highlighting" value="true"/></programlisting>
+
+ <para>Additionally there is a parameter that controls the format of the
+ excerpt created. In JCR 1.9 the default is set to
+ org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt.
+ The configuration parameter for this setting is:</para>
+
+ <programlisting><param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/></programlisting>
+
+ <section>
+ <title>DefaultXMLExcerpt</title>
+
+ <para>This excerpt provider creates an XML fragment of the following
+ form:</para>
+
+ <programlisting><excerpt>
+ <fragment>
+ <highlight>exoplatform</highlight> implements both the mandatory
+ XPath and optional SQL <highlight>query</highlight> syntax.
+ </fragment>
+ <fragment>
+ Before parsing the XPath <highlight>query</highlight> in
+ <highlight>exoplatform</highlight>, the statement is surrounded
+ </fragment>
+</excerpt></programlisting>
+ </section>
+
+ <section>
+ <title>DefaultHTMLExcerpt</title>
+
+ <para>This excerpt provider creates an HTML fragment of the following
+ form:</para>
+
+ <programlisting><div>
+ <span>
+ <strong>exoplatform</strong> implements both the mandatory XPath
+ and optional SQL <strong>query</strong> syntax.
+ </span>
+ <span>
+ Before parsing the XPath <strong>query</strong> in
+ <strong>exoplatform</strong>, the statement is surrounded
+ </span>
+</div></programlisting>
+ </section>
+
+ <section>
+ <title>How to use it</title>
+
+ <para>If you are using XPath you must use the rep:excerpt() function in
+ the last location step, just like you would select properties:</para>
+
+ <programlisting>QueryManager qm = session.getWorkspace().getQueryManager();
+Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH);
+QueryResult result = q.execute();
+for (RowIterator it = result.getRows(); it.hasNext(); ) {
+ Row r = it.nextRow();
+ Value title = r.getValue("Title");
+ Value excerpt = r.getValue("rep:excerpt(.)");
+}</programlisting>
+
+ <para>The above code searches for nodes that contain the word
+ exoplatform and then gets the value of the Title property and an excerpt
+ for each result node.</para>
+
+ <para>It is also possible to use a relative path in the call
+ Row.getValue() while the query statement still remains the same. Also
+ you may use a relative path to a string property. The returned value
+ will then be an excerpt based on string value of the property.</para>
+
+ <para>Both available excerpt provider will create fragments of about 150
+ characters and up to 3 fragments.</para>
+
+ <para>In SQL the function is called excerpt() without the rep prefix,
+ but the column in the RowIterator will nonetheless be labled
+ rep:excerpt(.)!</para>
+
+ <programlisting>QueryManager qm = session.getWorkspace().getQueryManager();
+Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL);
+QueryResult result = q.execute();
+for (RowIterator it = result.getRows(); it.hasNext(); ) {
+ Row r = it.nextRow();
+ Value excerpt = r.getValue("rep:excerpt(.)");
+}</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>SpellChecker</title>
+
+ <para>The lucene based query handler implementation supports a pluggable
+ spell checker mechanism. Per default spell checking is not available and
+ you have to configure it first. See parameter spellCheckerClass on page
+ <link linkend="JCR.SearchConfiguration">Search Configuration</link> JCR
+ currently provides an implementation class , which uses the <ulink
+ url="http://wiki.apache.org/jakarta-lucene/SpellChecker">lucene-spellchecker</ulink>
+ contrib . The dictionary is derived from the fulltext indexed content of
+ the workspace and updated periodically. You can configure the refresh
+ interval by picking one of the available inner classes of
+ org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>OneMinuteRefreshInterval</para>
+ </listitem>
+
+ <listitem>
+ <para>FiveMinutesRefreshInterval</para>
+ </listitem>
+
+ <listitem>
+ <para>ThirtyMinutesRefreshInterval</para>
+ </listitem>
+
+ <listitem>
+ <para>OneHourRefreshInterval</para>
+ </listitem>
+
+ <listitem>
+ <para>SixHoursRefreshInterval</para>
+ </listitem>
+
+ <listitem>
+ <para>TwelveHoursRefreshInterval</para>
+ </listitem>
+
+ <listitem>
+ <para>OneDayRefreshInterval</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>E.g. if you want a refresh interval of six hours the class name is:
+ org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$SixHoursRefreshInterval.
+ If you use
+ org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker
+ the refresh interval will be one hour.</para>
+
+ <para>The spell checker dictionary is stored as a lucene index under
+ <emphasis role="bold">"index-dir"/spellchecker</emphasis>. If it does not
+ exist, a background thread will create it on startup. Similarly the
+ dictionary refresh is also done in a background thread to not block
+ regular queries.</para>
+
+ <section>
+ <title>How do I use it?</title>
+
+ <para>You can spell check a fulltext statement either with an XPath or a
+ SQL query:</para>
+
+ <programlisting>// rep:spellcheck('explatform') will always evaluate to true
+Query query = qm.createQuery("/jcr:root[rep:spellcheck('explatform')]/(rep:spellcheck())", Query.XPATH);
+RowIterator rows = query.execute().getRows();
+// the above query will always return the root node no matter what string we check
+Row r = rows.nextRow();
+// get the result of the spell checking
+Value v = r.getValue("rep:spellcheck()");
+if (v == null) {
+ // no suggestion returned, the spelling is correct or the spell checker
+ // does not know how to correct it.
+} else {
+ String suggestion = v.getString();
+}</programlisting>
+
+ <para>And the same using SQL:</para>
+
+ <programlisting>// SPELLCHECK('exoplatform') will always evaluate to true
+Query query = qm.createQuery("SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('explatform')", Query.SQL);
+RowIterator rows = query.execute().getRows();
+// the above query will always return the root node no matter what string we check
+Row r = rows.nextRow();
+// get the result of the spell checking
+Value v = r.getValue("rep:spellcheck()");
+if (v == null) {
+ // no suggestion returned, the spelling is correct or the spell checker
+ // does not know how to correct it.
+} else {
+ String suggestion = v.getString();
+}</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>Similarity (Since 1.12)</title>
+
+ <para>Starting with version, 1.12 JCR allows you to search for nodes that
+ are similar to an existing node.</para>
+
+ <para>Similarity is determined by looking up terms that are common to
+ nodes. There are some conditions that must be met for a term to be
+ considered. This is required to limit the number possibly relevant
+ terms.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Only terms with at least 4 characters are considered.</para>
+ </listitem>
+
+ <listitem>
+ <para>Only terms that occur at least 2 times in the source node are
+ considered.</para>
+ </listitem>
+
+ <listitem>
+ <para>Only terms that occur in at least 5 nodes are considered.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note: The similarity functionality requires that the
+ supportHightlighting is enabled. Please make sure that you have the
+ following parameter set for the query handler in your
+ workspace.xml.</para>
+
+ <programlisting><param name="support-highlighting" value="true"/></programlisting>
+
+ <para>The functions are called rep:similar() (in XPath) and similar() (in
+ SQL) and have two arguments:</para>
+
+ <para>relativePath: a relative path to a descendant node or . for the
+ current node. absoluteStringPath: a string literal that contains the path
+ to the node for which to find similar nodes.</para>
+
+ <warning>
+ <para>Relative path is not supported yet.</para>
+ </warning>
+
+ <para>Examples:</para>
+
+ <programlisting>//element(*, nt:resource)[rep:similar(., '/parentnode/node.txt/jcr:content')]</programlisting>
+
+ <para>Finds nt:resource nodes, which are similar to node by path
+ /parentnode/node.txt/jcr:content.</para>
+ </section>
+</chapter>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/spell-checker.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/spell-checker.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/spell-checker.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.SpellChecker">
+ <title>Check Spelling of Phrase</title>
+
+ <para>Check correct spelling of phrase 'quik OR (-foo bar)' according to
+ data already stored in index.</para>
+
+ <note>
+ <para>See also about SpellChecker configuration - <link
+ linkend="JCR.SearchingRepositoryContent">Searching Repository
+ Content</link></para>
+ </note>
+
+ <para>SpellChecker must be settled in query-handler config. </para>
+
+ <para>test-jcr-config.xml:</para>
+
+ <programlisting><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ ...
+ <property name="spellchecker-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.spell.LuceneSpellChecker$FiveSecondsRefreshInterval" />
+ ...
+ </properties>
+</query-handler></programlisting>
+
+ <section>
+ <title>Repository structure:</title>
+
+ <para>Repository contains node, with string property "The quick brown fox
+ jumps over the lazy dog."</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>root</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>node1 property="The quick brown fox jumps over the lazy
+ dog."</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query execution</title>
+
+ <para>Query looks only for root node, because spell checker looks for
+ suggestions by full index. So complicated query is redundant.</para>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String sqlStatement = "SELECT rep:spellcheck() FROM nt:base WHERE jcr:path = '/' AND SPELLCHECK('quik OR (-foo bar)')";
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make XPath query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String xpathStatement = "/jcr:root[rep:spellcheck('quik OR (-foo bar)')]/(rep:spellcheck())";
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Fetch result</title>
+
+ <para>Get suggestion of coorect spelling our phrase:</para>
+
+ <programlisting>RowIterator it = result.getRows();
+Row r = rows.nextRow();
+Value v = r.getValue("rep:spellcheck()");
+String correctPhrase = v.getString();</programlisting>
+
+ <para>So, correct spelling for phrase "quik OR (-foo bar)" is "quick OR
+ (-fox bar)".</para>
+ </section>
+</section>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/synonim-provider.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/synonim-provider.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/synonim-provider.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.SynonimProvider">
+ <title>Search By Synonim</title>
+
+ <para>Find all mix:title nodes where title contains synonims to 'fast'
+ word.</para>
+
+ <note>
+ <para>See also about synonim propvider configuration - <link
+ linkend="JCR.SearchingRepositoryContent">Searching Repository
+ Content</link></para>
+ </note>
+
+ <para>Synonim provider must be configured in indexing-configuration.xml
+ :</para>
+
+ <programlisting><query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ ...
+ <property name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.PropertiesSynonymProvider" />
+ <property name="synonymprovider-config-path" value="../../synonyms.properties" />
+ ...
+ </properties>
+</query-handler></programlisting>
+
+ <para>File synonim.properties contains next synonims list:</para>
+
+ <programlisting>ASF=Apache Software Foundation
+quick=fast
+sluggish=lazy</programlisting>
+
+ <section>
+ <title>Repository structure:</title>
+
+ <para>Repository contains mix:title nodes, where jcr:title has different
+ values.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>root</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>document1 (mix:title) jcr:title="The quick brown fox jumps
+ over the lazy dog."</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Query execution</title>
+
+ <para><emphasis role="bold">SQL</emphasis></para>
+
+ <programlisting>// make SQL query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String sqlStatement = "SELECT * FROM mix:title WHERE CONTAINS(jcr:title, '~fast')";
+Query query = queryManager.createQuery(sqlStatement, Query.SQL);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// make XPath query
+QueryManager queryManager = workspace.getQueryManager();
+// create query
+String xpathStatement = "//element(*,mix:title)[jcr:contains(@jcr:title, '~fast')]";
+Query query = queryManager.createQuery(xpathStatement, Query.XPATH);
+// execute query and fetch result
+QueryResult result = query.execute();</programlisting>
+ </section>
+
+ <section>
+ <title>Fetch result</title>
+
+ <para>Lets get nodes:</para>
+
+ <programlisting>NodeIterator it = result.getNodes();
+
+if(it.hasNext())
+{
+ Node findedNode = it.nextNode();
+}</programlisting>
+
+ <para>NodeIterator will return expected document1. This is a purpose of
+ synonim providers. Find by specified word, but return by all synonims
+ to.</para>
+ </section>
+</section>
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/tip-nodename-with-number.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/tip-nodename-with-number.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/tip-nodename-with-number.xml 2010-08-04 12:33:17 UTC (rev 2873)
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<section id="JCR.TipNodeNameWithNumber">
+ <title>XPath queries containing node names starting with a number</title>
+
+ <para>If you execute an XPath request like this:</para>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// get QueryManager
+QueryManager queryManager = workspace.getQueryManager();
+// make XPath query
+Query query = queryManager.createQuery("/jcr:root/Documents/Publie/2010//element(*, exo:article)", Query.XPATH);</programlisting>
+
+ <para>You will have an error : "Invalid request". This happens because XML
+ does not allow names starting with a number - and XPath is part of XML:
+ <ulink
+ url="http://www.w3.org/TR/REC-xml/#NT-Name">http://www.w3.org/TR/REC-xml/#NT-Name</ulink></para>
+
+ <para>Therefore you cannot do XPath requests using a node name that starts
+ with a number.</para>
+
+ <para>Easy workarounds:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use an SQL request.</para>
+ </listitem>
+
+ <listitem>
+ <para>Use escaping :</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><emphasis role="bold">XPath</emphasis></para>
+
+ <programlisting>// get QueryManager
+QueryManager queryManager = workspace.getQueryManager();
+// make XPath query
+Query query = queryManager.createQuery("/jcr:root/Documents/Publie/_x0032_010//element(*, exo:article)", Query.XPATH);</programlisting>
+</section>
More information about the exo-jcr-commits
mailing list