Author: sergiykarpenko Date: 2010-08-04 03:59:52 -0400 (Wed, 04 Aug 2010) New Revision: 2869 Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-descendant.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-path-or-name.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-property.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-score.xml Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/jcr-query-usecases.xml Log: EXOJCR-869: jcr-query-usecases : order by ported 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-03 15:08:05 UTC (rev 2868) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/jcr-query-usecases.xml 2010-08-04 07:59:52 UTC (rev 2869) @@ -203,20 +203,22 @@ <itemizedlist> <listitem> - <para><link linkend="???">JCR.Order by Property</link></para> + <para><link linkend="JCR.OrderByProperty">Order by + Property</link></para> </listitem> <listitem> - <para><link linkend="???">JCR.Order by Descendant Node + <para><link linkend="JCR.OrderByDescendant">Order by Descendant Node Property</link></para> </listitem> <listitem> - <para><link linkend="???">JCR.Order by Score</link></para> + <para><link linkend="JCR.OrderByScore">Order by Score</link></para> </listitem> <listitem> - <para><link linkend="???">JCR.Order by Path or Name</link></para> + <para><link linkend="JCR.OrderByPathOrName">Order by Path or + Name</link></para> </listitem> </itemizedlist> </section> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-descendant.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-descendant.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-descendant.xml 2010-08-04 07:59:52 UTC (rev 2869) @@ -0,0 +1,171 @@ +<?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.OrderByDescendant"> + <title>Order by Descendant Nodes Property (XPath only)</title> + + <para>Find all nodes with the primary type 'nt:unstructured' and sort them + by the property value of descendant nodes with the relative path + '/a/b'.</para> + + <note> + <para>This ORDER BY construction only works in XPath!</para> + </note> + + <section> + <title>Repository structure:</title> + + <itemizedlist> + <listitem> + <para>root</para> + + <itemizedlist> + <listitem> + <para>node1 (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>a (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>b (nt:unstructured)</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>node2 (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>a (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>b (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>c (nt:unstructured) prop = "a"</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>node3 (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>a (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>b (nt:unstructured)</para> + + <itemizedlist> + <listitem> + <para>c (nt:unstructured) prop = "b"</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </section> + + <section> + <title>Query Execution</title> + + <para><emphasis role="bold">XPath</emphasis></para> + + <programlisting>// make XPath query +QueryManager queryManager = workspace.getQueryManager(); +// create query +String xpathStatement = "/jcr:root/* order by a/b/c/@prop descending; +Query query = queryManager.createQuery(xpathStatement, Query.XPATH); +// execute query and fetch result +QueryResult result = query.execute();</programlisting> + </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 nodes in the following order - + "node3","node2" and "node1".</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:</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>/testroot/node3</entry> + + <entry>1000</entry> + </row> + + <row> + <entry>nt:unstructured</entry> + + <entry>/testroot/node2</entry> + + <entry>1000</entry> + </row> + + <row> + <entry>nt:unstructured</entry> + + <entry>/testroot/node1</entry> + + <entry>1000</entry> + </row> + </tbody> + </tgroup> + </table> + </section> +</section> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-path-or-name.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-path-or-name.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-path-or-name.xml 2010-08-04 07:59:52 UTC (rev 2869) @@ -0,0 +1,34 @@ +<?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.OrderByPathOrName"> + <title>Order by Path or Name</title> + + <warning> + <para>Order by jcr:path or jcr:name does not supported.</para> + </warning> + + <para>There is two ways to ordering results, when path may be used as + criteria:</para> + + <itemizedlist> + <listitem> + <para>order by property with value type NAME or PATH (jcr supports + it)</para> + </listitem> + + <listitem> + <para>order by jcr:path or jcr:name - sort by exact path or name of node + (jcr do not supports it)</para> + </listitem> + </itemizedlist> + + <para>If no order specification is supplied in the query statement, + implementations may support document order on the result nodes (see 6.6.4.2 + Document Order). And its sorted by order number.</para> + + <para>By default (if query do not contains any ordering statements) result + nodes is sorted by document order.</para> + + <programlisting>SELECT * FROM nt:unstructured WHERE jcr:path LIKE 'testRoot/%'</programlisting> +</section> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-property.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-property.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-property.xml 2010-08-04 07:59:52 UTC (rev 2869) @@ -0,0 +1,150 @@ +<?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.OrderByProperty"> + <title>Sort Nodes by Property</title> + + <para>Select all nodes with the mixin type ''mix:title' and order them by + the 'prop_pagecount' property.</para> + + <section> + <title>Repository Structure</title> + + <para>The repository contains several mix:title nodes, where + prop_pagecount has different values.</para> + + <itemizedlist> + <listitem> + <para>root</para> + + <itemizedlist> + <listitem> + <para>document1 (mix:title) jcr:title="War and peace" + jcr:description="roman" prop_pagecount=4</para> + </listitem> + + <listitem> + <para>document2 (mix:title) jcr:title="Cinderella" + jcr:description="fairytale" prop_pagecount=7</para> + </listitem> + + <listitem> + <para>document3 (mix:title) jcr:title="Puss in Boots" + jcr:description="fairytale" prop_pagecount=1</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 ORDER BY prop_pagecount ASC"; +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) order by prop_pagecount ascending"; +Query query = queryManager.createQuery(xpathStatement, Query.XPATH); +// execute query and fetch result +QueryResult result = query.execute();</programlisting> + </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>The NodeIterator will return nodes in the following order + "document3", "document1", "document2".</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:</para> + + <table> + <title>Table content</title> + + <tgroup cols="5"> + <thead> + <row> + <entry>jcr:title</entry> + + <entry>jcr:description</entry> + + <entry>prop_pagecount</entry> + + <entry> jcr:path</entry> + + <entry>jcr:score</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Puss in Boots</entry> + + <entry>fairytale</entry> + + <entry>1</entry> + + <entry>/document3</entry> + + <entry>1405</entry> + </row> + + <row> + <entry>War and peace</entry> + + <entry>roman</entry> + + <entry>4</entry> + + <entry>/document1</entry> + + <entry>1405</entry> + </row> + + <row> + <entry>Cinderella</entry> + + <entry>fairytale</entry> + + <entry>7</entry> + + <entry>/document2</entry> + + <entry>1405</entry> + </row> + </tbody> + </tgroup> + </table> + </section> +</section> Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-score.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-score.xml (rev 0) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/searching/order-by-score.xml 2010-08-04 07:59:52 UTC (rev 2869) @@ -0,0 +1,166 @@ +<?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.OrderByScore"> + <title>Order by Score</title> + + <para>Select all nodes with the mixin type 'mix:title' containing any word + from the set {'brown','fox','jumps'}. Then sort result by the score in + ascending node. This way nodes that matches better the query statement are + ordered at the last positions in the result list.</para> + + <section> + <title>Info</title> + + <para>SQL and XPath queries support both score constructions jcr:score and + jcr:score()</para> + + <programlisting>SELECT * FROM nt:base ORDER BY jcr:score [ASC|DESC] +SELECT * FROM nt:base ORDER BY jcr:score()[ASC|DESC] + +//element(*,nt:base) order by jcr:score() [descending] +//element(*,nt:base) order by @jcr:score [descending]</programlisting> + + <para>Do not use "ascending" combined with jcr:score in XPath. The + following XPath statement may throw an exception:</para> + + <programlisting>... order by jcr:score() ascending</programlisting> + + <para>Do not set any ordering specifier - ascending is default:</para> + + <programlisting>... order by jcr:score()</programlisting> + </section> + + <section> + <title>Repository Structure</title> + + <para>The repository contains mix:title nodes, where the jcr:description + has different values.</para> + + <itemizedlist> + <listitem> + <para>root</para> + + <itemizedlist> + <listitem> + <para>document1 (mix:title) jcr:description="The quick brown fox + jumps over the lazy dog."</para> + </listitem> + + <listitem> + <para>document2 (mix:title) jcr:description="The brown fox lives + in the forest."</para> + </listitem> + + <listitem> + <para>document3 (mix:title) jcr:description="The fox is a nice + animal."</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(*, 'brown OR fox OR jumps') ORDER BY jcr:score() ASC"; +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(., 'brown OR fox OR jumps')] order by jcr:score()"; +Query query = queryManager.createQuery(xpathStatement, Query.XPATH); +// execute query and fetch result +QueryResult result = query.execute();</programlisting> + </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 nodes in the following order: "document3", + "document2", "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:</para> + + <table> + <title>Table content</title> + + <tgroup cols="4"> + <thead> + <row> + <entry> jcr:description</entry> + + <entry>...</entry> + + <entry>jcr:path</entry> + + <entry>jcr:score</entry> + </row> + </thead> + + <tbody> + <row> + <entry>The fox is a nice animal.</entry> + + <entry>...</entry> + + <entry>/document3</entry> + + <entry>2512</entry> + </row> + + <row> + <entry>The brown fox lives in the forest.</entry> + + <entry>...</entry> + + <entry>/document2</entry> + + <entry>3595</entry> + </row> + + <row> + <entry>The quick brown fox jumps over the lazy dog.</entry> + + <entry>...</entry> + + <entry>/document1</entry> + + <entry>5017</entry> + </row> + </tbody> + </tgroup> + </table> + </section> +</section>