You are viewing a plain text version of this content. The canonical link for it is here.
Posted to jdo-commits@db.apache.org by an...@apache.org on 2010/06/01 12:02:45 UTC
svn commit: r949989 [8/8] - in /db/jdo/site: docs/ docs/guides/
docs/releases/ xdocs/
Added: db/jdo/site/xdocs/jdoql_methods.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/jdoql_methods.xml?rev=949989&view=auto
==============================================================================
--- db/jdo/site/xdocs/jdoql_methods.xml (added)
+++ db/jdo/site/xdocs/jdoql_methods.xml Tue Jun 1 10:02:44 2010
@@ -0,0 +1,184 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document>
+ <properties>
+ <title>JDOQL - Methods</title>
+ </properties>
+
+ <body>
+ <section name="JDOQL : Methods">
+ <p>
+ When writing the "filter" for a JDOQL Query you can make use of some methods on the various
+ Java types. The range of methods included as standard in JDOQL is not as flexible as with
+ the true Java types, but the ones that are available are typically of much use.
+ </p>
+ <br/>
+ <subsection name="String Methods">
+ <table>
+ <tr>
+ <th width="220">Method</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>startsWith(String)</td>
+ <td>Returns if the string starts with the passed string</td>
+ </tr>
+ <tr>
+ <td>endsWith(String)</td>
+ <td>Returns if the string ends with the passed string</td>
+ </tr>
+ <tr>
+ <td>indexOf(String)</td>
+ <td>Returns the first position of the passed string</td>
+ </tr>
+ <tr>
+ <td>indexOf(String,int)</td>
+ <td>Returns the position of the passed string, after the passed position</td>
+ </tr>
+ <tr>
+ <td>substring(int)</td>
+ <td>Returns the substring starting from the passed position</td>
+ </tr>
+ <tr>
+ <td>substring(int,int)</td>
+ <td>Returns the substring between the passed positions</td>
+ </tr>
+ <tr>
+ <td>toLowerCase()</td>
+ <td>Returns the string in lowercase</td>
+ </tr>
+ <tr>
+ <td>toUpperCase()</td>
+ <td>Retuns the string in UPPERCASE</td>
+ </tr>
+ <tr>
+ <td>matches(String pattern)</td>
+ <td>Returns whether string matches the passed expression. The pattern argument follows the rules of
+ java.lang.String.matches method.</td>
+ </tr>
+ </table>
+ <p>
+ Here's an example using a Product class, looking for objects which their abreviation is the
+ beginning of a trade name. The trade name is provided as parameter.
+ </p>
+ <source><![CDATA[
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class);
+query.setFilter(":tradeName.startsWith(this.abbreviation)");
+List results = (List)query.execute("Workbook Advanced");
+
+Single-String JDOQL :
+Query query = pm.newQuery(
+ "SELECT FROM mydomain.Product " +
+ "WHERE :tradeName.startsWith(this.abbreviation)");
+List results = (List)query.execute("Workbook Advanced");]]></source>
+ <br/>
+ </subsection>
+
+ <subsection name="Collection Methods">
+ <table>
+ <tr>
+ <th width="220">Method</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>isEmpty()</td>
+ <td>Returns whether the collection is empty</td>
+ </tr>
+ <tr>
+ <td>contains(value)</td>
+ <td>Returns whether the collection contains the passed element</td>
+ </tr>
+ <tr>
+ <td>size()</td>
+ <td>Returns the number of elements in the collection</td>
+ </tr>
+ </table>
+ <p>
+ Here's an example demonstrating use of contains(). We have an Inventory class that has a
+ Collection of Product objects, and we want to find the Inventory objects with 2 particular
+ Products in it. Here we make use of a variable (<i>prd</i> to represent the Product being
+ contained
+ </p>
+ <source><![CDATA[
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Inventory.class);
+query.setFilter("products.contains(prd) && (prd.name==\"product 1\" || prd.name==\"product 2\")");
+List results = (List)query.execute();
+
+Single-String JDOQL:
+Query query = pm.newQuery(
+ "SELECT FROM mydomain.Inventory EXCLUDE SUBCLASSES " +
+ "WHERE products.contains(prd) && (prd.name==\"product 1\" || prd.name==\"product 2\")");
+List results = (List)query.execute();]]></source>
+ <br/>
+ </subsection>
+
+ <subsection name="Map Methods">
+ <table>
+ <tr>
+ <th width="220">Method</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>isEmpty()</td>
+ <td>Returns whether the map is empty</td>
+ </tr>
+ <tr>
+ <td>containsKey(key)</td>
+ <td>Returns whether the map contains the passed key</td>
+ </tr>
+ <tr>
+ <td>containsValue(value)</td>
+ <td>Returns whether the map contains the passed value</td>
+ </tr>
+ <tr>
+ <td>get(key)</td>
+ <td>Returns the value from the map with the passed key</td>
+ </tr>
+ <tr>
+ <td>size()</td>
+ <td>Returns the number of entries in the map</td>
+ </tr>
+ </table>
+ <p>
+ Here's an example using a Product class as a value in a Map. Our example represents an
+ organisation that has several Inventories of products. Each Inventory of products is stored
+ using a Map, keyed by the Product name. The query searches for all Inventories that contain a
+ product with the name "product 1".
+ </p>
+ <source>
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Inventory.class, "products.containsKey(\"product 1\")");
+List results = (List)query.execute();
+
+Single-String JDOQL :
+Query query = pm.newQuery(
+ "SELECT FROM mydomain.Inventory EXCLUDE SUBCLASSES " +
+ "WHERE products.containsKey(\"product 1\")");
+List results = (List)query.execute();</source>
+ <br/>
+ </subsection>
+
+ <subsection name="Other Methods">
+ <table>
+ <tr>
+ <th width="220">Method</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>Math.abs(number)</td>
+ <td>Returns the absolute value of the passed number</td>
+ </tr>
+ <tr>
+ <td>Math.sqrt(number)</td>
+ <td>Returns the square root of the passed number</td>
+ </tr>
+ <tr>
+ <td>JDOHelper.getObjectId(object)</td>
+ <td>Returns the object identity of the passed persistent object</td>
+ </tr>
+ </table>
+ </subsection>
+ </section>
+ </body>
+</document>
Added: db/jdo/site/xdocs/jdoql_result.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/jdoql_result.xml?rev=949989&view=auto
==============================================================================
--- db/jdo/site/xdocs/jdoql_result.xml (added)
+++ db/jdo/site/xdocs/jdoql_result.xml Tue Jun 1 10:02:44 2010
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<document>
+ <properties>
+ <title>JDOQL - Result</title>
+ </properties>
+
+ <body>
+ <section name="JDOQL : Result">
+ <p>
+ As we have seen, a JDOQL query is made up of different parts. In this section we look at the
+ <I>result</I> part of the query. The result is what we want returning. By default (when not specifying
+ the result) the objects returned will be of the candidate class type, where they match the query
+ filter. Firstly let's look at what you can include in the <I>result</I> clause.
+ </p>
+ <ul>
+ <li><I>this</I> - the candidate instance</li>
+ <li>A field name</li>
+ <li>A variable</li>
+ <li>A parameter (though why you would want a parameter returning is hard to see since you input
+ the value in the first place)</li>
+ <li>An aggregate (count(), avg(), sum(), min(), max())</li>
+ <li>An expression involving a field (e.g "field1 + 1")</li>
+ <li>A navigational expression (navigating from one field to another ... e.g "field1.field4")</li>
+ </ul>
+ <p>
+ The result is specified in JDOQL like this
+ </p>
+ <source>query.setResult("count(field1), field2");</source>
+ <p>
+ In <B>Single-String JDOQL</B> you would specify it directly.
+ </p>
+ <br/>
+
+ <subsection name="Result type">
+ <p>
+ What you specify in the <I>result</I> defines what form of result you get back.
+ </p>
+ <ul>
+ <li><B>Object</B> - this is returned if you have only a single row in the results and a single
+ column. This is achived when you specified either UNIQUE, or just an aggregate
+ (e.g "max(field2)")</li>
+ <li><B>Object[]</B> - this is returned if you have only a single row in the results, but more
+ than 1 column (e.g "max(field1), avg(field2)")</li>
+ <li><B>List<Object></B> - this is returned if you have only a single column in the result,
+ and you don't have only aggregates in the result (e.g "field2")</li>
+ <li><B>List<Object[]></B> - this is returned if you have more than 1 column in the result,
+ and you don't have only aggregates in the result (e.g "field2, avg(field3)")</li>
+ </ul>
+ </subsection>
+
+ <subsection name="Aggregates">
+ <p>
+ There are situations when you want to return a single number for a column, representing an
+ aggregate of the values of all records. There are 5 standard JDO2 aggregate functions available.
+ These are
+ </p>
+ <ul>
+ <li><B>avg(val)</B> - returns the average of "val". "val" can be a field, numeric field expression
+ or "distinct field".</li>
+ <li><B>sum(val)</B> - returns the sum of "val". "val" can be a field, numeric field expression,
+ or "distinct field".</li>
+ <li><B>count(val)</B> - returns the count of records of "val". "val" can be a field, or can be
+ "this", or "distinct field".</li>
+ <li><B>min(val)</B> - returns the minimum of "val". "val" can be a field</li>
+ <li><B>max(val)</B> - returns the maximum of "val". "val" can be a field</li>
+ </ul>
+ <p>
+ So to utilise these you could specify something like
+ </p>
+ <source>
+Query q = pm.newQuery("SELECT max(price), min(price) FROM org.datanucleus.samples.store.Product WHERE status == 1");</source>
+ <p>
+ This will return a single row of results with 2 values, the maximum price and the minimum price of
+ all products that have status code of 1.
+ </p>
+ <br/>
+ </subsection>
+
+ <subsection name="Example - Use of aggregates">
+ <p>
+ JDO 2 introduces the ability to use aggregates in queries. Here's another example using the
+ same Product class as above, but this time looking for the maximum price of products that are
+ CD Players. Note that the result for this particular query will be of type Double since there
+ is a single double precision value being returned via the "result".
+ </p>
+ <source>
+Declarative JDOQL :
+Query query = pm.newQuery(org.datanucleus.samples.store.Product.class);
+query.setFilter("name == \"CD Player\"");
+query.setResult("max(this.price)");
+List results = (List)query.execute();
+Iterator iter = c.iterator();
+Double max_price = (Double)iter.next();
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT max(price) FROM org.datanucleus.samples.store.Product WHERE name == \"CD Player\"");
+List results = (List)query.execute();
+Iterator iter = c.iterator();
+Double max_price = (Double)iter.next();</source>
+ <br/>
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
Modified: db/jdo/site/xdocs/navigation.xml
URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/navigation.xml?rev=949989&r1=949988&r2=949989&view=diff
==============================================================================
--- db/jdo/site/xdocs/navigation.xml (original)
+++ db/jdo/site/xdocs/navigation.xml Tue Jun 1 10:02:44 2010
@@ -35,7 +35,10 @@
<item name="Transactions" href="/transactions.html"/>
<item name="Object States" href="/state_transition.html"/>
<item name="Object Retrieval" href="/object_retrieval.html"/>
- <item name="JDOQL" href="/jdoql.html"/>
+ <item name="JDOQL" href="/jdoql.html" collapse="true">
+ <item name="Result" href="/jdoql_result.html"/>
+ <item name="Methods" href="/jdoql_methods.html"/>
+ </item>
<item name="Extents" href="/extents.html"/>
<item name="Guides" href="/guides.html" collapse="true">
<item name="Datastore Replication" href="/guides/replication.html"/>