db-jdo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From an...@apache.org
Subject svn commit: r949989 [8/8] - in /db/jdo/site: docs/ docs/guides/ docs/releases/ xdocs/
Date Tue, 01 Jun 2010 10:02:45 GMT
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&lt;Object&gt;</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&lt;Object[]&gt;</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"/>



Mime
View raw message