Modified: websites/production/db/content/jdo/jdoql.html ============================================================================== --- websites/production/db/content/jdo/jdoql.html (original) +++ websites/production/db/content/jdo/jdoql.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -209,247 +209,247 @@
- - -

JDOQL

-

- JDO defines ways of querying objects persisted into the datastore. It provides - its own object-based query language (JDOQL). JDOQL is designed as the Java - developers way of having the power of SQL queries, yet retaining the Java - object relationship that exist in their application model. - A typical JDOQL query may be set up in one of 2 ways. Here's an example -

-
-Declarative JDOQL :
-Query q = pm.newQuery(mydomain.Person.class, "lastName == \"Jones\" && age < age_limit");
-q.declareParameters("double age_limit");
-List results = (List)q.execute(20.0);
-
-Single-String JDOQL :
-Query q = pm.newQuery("SELECT FROM mydomain.Person WHERE lastName == \"Jones\"" +
-                      " && age < :age_limit PARAMETERS double age_limit");
-List results = (List)q.execute(20.0);
-

- So here in our example we select all "Person" objects with surname of "Jones" - and where the persons age is below 20. The language is intuitive for Java - developers, and is intended as their interface to accessing the persisted - data model. As can be seen above, the query is made up of distinct parts. - The class being selected (the SELECT clause in SQL), the filter (which equates - to the WHERE clause in SQL), together with any sorting (the ORDER BY clause - in SQL), etc. -

-

- Before giving details on JDOQL, you can download a quick - reference guide here -

-
- - -

Single-String JDOQL

-

- In traditional (declarative) JDOQL (JDO 1.0) it was necessary to specify - the component parts (filter, candidate class, ordering, etc) of the query - using the mutator methods on the Query. In JDO 2 you can now specify it - all in a single string. This string has to follow a particular pattern, - but provides the convenience that many people have been asking for. - The pattern to use is as follows -

-
-SELECT [UNIQUE] [<result>] [INTO <result-class>]
-        [FROM <candidate-class> [EXCLUDE SUBCLASSES]]
-        [WHERE <filter>]
-        [VARIABLES <variable declarations>]
-        [PARAMETERS <parameter declarations>]
-        [<import declarations>]
-        [GROUP BY <grouping>]
-        [ORDER BY <ordering>]
-        [RANGE <start>, <end>]
-

- The "keywords" in the query are shown in UPPER CASE but can be in - UPPER or lower case. -

-

- Lets give an example of a query using this syntax -

-
SELECT UNIQUE FROM org.datanucleus.samples.Employee ORDER BY departmentNumber
-

- so we form the parts of the query as before, yet here we just specify it - all in a single call. -

-
- -

Accessing Fields

-

- In JDOQL you access fields in the query by referring to the field name. - For example, if you are querying a class called Product and it has - a field "price", then you access it like this -

-
-Query query = pm.newQuery(mydomain.Product.class, "price < 150.0");
-

- In addition to the persistent fields, you can also access - "public static final" fields of any class. You can do this as follows -

-
-Query query = pm.newQuery(mydomain.Product.class, 
-       "taxPercent < mydomain.Product.TAX_BAND_A");
-

- So this will find all products that include a tax percentage less than - some "BAND A" level. Where you are using "public static final" fields you - can either fully-qualify the class name or you can include it in the - "imports" section of the query (see later). -

-
- -

Data types : literals

-

- JDOQL supports the following literals: IntegerLiteral, - FloatingPointLiteral, BooleanLiteral, CharacterLiteral, StringLiteral, - and NullLiteral. -

-
- -

Operators precedence

-

- The following list describes the operator precedence in JDOQL. -

-
    -
  1. Cast
  2. -
  3. Unary ("~") ("!")
  4. -
  5. Unary ("+") ("-")
  6. -
  7. Multiplicative ("*") ("/") ("%")
  8. -
  9. Additive ("+") ("-")
  10. -
  11. Relational (">=") (">") ("<=") ("<") ("instanceof")
  12. -
  13. Equality ("==") ("!=")
  14. -
  15. Boolean logical AND ("&")
  16. -
  17. Boolean logical OR ("|")
  18. -
  19. Conditional AND ("&&")
  20. -
  21. Conditional OR ("||")
  22. -
-
- -

Concatenation Expressions

-

- The concatenation operator(+) concatenates a String to either another - String or Number. Concatenations of String or Numbers to null results in - null. -

-
- -

Example 1 - Use of Explicit Parameters

-

- Here's a simple example for finding the elements of a class with a field - below a particular threshold level. Here we pass in the threshold value - (limit), and sort the output in order of ascending price. -

-
-Declarative JDOQL :
-Query query = pm.newQuery(mydomain.Product.class,"price < limit");
-query.declareParameters("double limit");
-query.setOrdering("price ascending");
-List results = (List)query.execute(150.00);
-
-Single-String JDOQL :
-Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " +
-                "price < limit PARAMETERS double limit ORDER BY price ASCENDING");
-List results = (List)query.execute(150.00);
-

- For completeness, the class is shown here -

-
-class Product
-{
-    String name;
-    double price;
-    java.util.Date endDate;
-    ...
-}
-
-<jdo>
-    <package name="mydomain">
-        <class name="Product">
-            <field name="name">
-                <column length="100" jdbc-type="VARCHAR"/>
-            </field>
-            <field name="abreviation">
-                <column length="20" jdbc-type="VARCHAR"/>
-            </field>
-            <field name="price"/>
-            <field name="endDate"/>
-        </class>
-    </package>
-</jdo>
-
-
- -

Example 2 - Use of Implicit Parameters

-

- Let's repeat the previous query but this time using implicit - parameters. -

-
-Declarative JDOQL :
-Query query = pm.newQuery(mydomain.Product.class,"price < :limit");
-query.setOrdering("price ascending");
-List results = (List)query.execute(150.00);
-
-Single-String JDOQL :
-Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " +
-                "price < :limit ORDER BY price ASCENDING");
-List results = (List)query.execute(150.00);
-

- So we omitted the declaration of the parameter and just prefixed it with - a colon (:) -

-
-
- -

Example 3 - Comparison against Dates

-

- Here's another example using the same Product class as above, but this - time comparing to a Date field. Because we are using a type in our query, - we need to import it ... - just like you would in a Java class if you were using it there. -

-
-Declarative JDOQL :
-Query query = pm.newQuery(domain.Product.class,
-                          "endDate > best_before_limit");
-query.declareImports("import java.util.Date");
-query.declareParameters("Date best_before_limit");
-query.setOrdering("endDate descending");
-Collection results = (Collection)query.execute(my_date_limit);
-
-Single-String JDOQL :
-Query query = pm.newQuery("SELECT FROM mydomain.Product " +
-                "WHERE endDate > best_before_limit " +
-                "PARAMETERS Date best_before_limit " +
-                "import java.util.Date ORDER BY endDate DESC");
-List results = (List)query.execute(my_date_limit);
-
-
- -

Example 4 - Instanceof

-

- This example demonstrates use of the "instanceof" operator. We have a - class A that has a field "b" of type B and B has subclasses B1, B2, B3. - Clearly the field "b" of A can be of type B, B1, B2, B3 etc, and we want - to find all objects of type A that have the field "b" that is of type B2. - We do it like this -

-
-Declarative JDOQL :
-Query query = pm.newQuery(mydomain.A.class);
-query.setFilter("b instanceof mydomain.B2");
-List results = (List)query.execute();
-
-Single-String JDOQL :
-Query query = pm.newQuery("SELECT FROM mydomain.A WHERE b instanceof mydomain.B2");
-List results = (List)query.execute();
-
-
- - + + +

JDOQL

+

+ JDO defines ways of querying objects persisted into the datastore. It provides + its own object-based query language (JDOQL). JDOQL is designed as the Java + developers way of having the power of SQL queries, yet retaining the Java + object relationship that exist in their application model. + A typical JDOQL query may be set up in one of 2 ways. Here's an example +

+
+Declarative JDOQL :
+Query q = pm.newQuery(mydomain.Person.class, "lastName == \"Jones\" && age < age_limit");
+q.declareParameters("double age_limit");
+List results = (List)q.execute(20.0);
+
+Single-String JDOQL :
+Query q = pm.newQuery("SELECT FROM mydomain.Person WHERE lastName == \"Jones\"" +
+                      " && age < :age_limit PARAMETERS double age_limit");
+List results = (List)q.execute(20.0);
+

+ So here in our example we select all "Person" objects with surname of "Jones" + and where the persons age is below 20. The language is intuitive for Java + developers, and is intended as their interface to accessing the persisted + data model. As can be seen above, the query is made up of distinct parts. + The class being selected (the SELECT clause in SQL), the filter (which equates + to the WHERE clause in SQL), together with any sorting (the ORDER BY clause + in SQL), etc. +

+

+ Before giving details on JDOQL, you can download a quick + reference guide here +

+
+ + +

Single-String JDOQL

+

+ In traditional (declarative) JDOQL (JDO 1.0) it was necessary to specify + the component parts (filter, candidate class, ordering, etc) of the query + using the mutator methods on the Query. In JDO 2 you can now specify it + all in a single string. This string has to follow a particular pattern, + but provides the convenience that many people have been asking for. + The pattern to use is as follows +

+
+SELECT [UNIQUE] [<result>] [INTO <result-class>]
+        [FROM <candidate-class> [EXCLUDE SUBCLASSES]]
+        [WHERE <filter>]
+        [VARIABLES <variable declarations>]
+        [PARAMETERS <parameter declarations>]
+        [<import declarations>]
+        [GROUP BY <grouping>]
+        [ORDER BY <ordering>]
+        [RANGE <start>, <end>]
+

+ The "keywords" in the query are shown in UPPER CASE but can be in + UPPER or lower case. +

+

+ Lets give an example of a query using this syntax +

+
SELECT UNIQUE FROM org.datanucleus.samples.Employee ORDER BY departmentNumber
+

+ so we form the parts of the query as before, yet here we just specify it + all in a single call. +

+
+ +

Accessing Fields

+

+ In JDOQL you access fields in the query by referring to the field name. + For example, if you are querying a class called Product and it has + a field "price", then you access it like this +

+
+Query query = pm.newQuery(mydomain.Product.class, "price < 150.0");
+

+ In addition to the persistent fields, you can also access + "public static final" fields of any class. You can do this as follows +

+
+Query query = pm.newQuery(mydomain.Product.class, 
+       "taxPercent < mydomain.Product.TAX_BAND_A");
+

+ So this will find all products that include a tax percentage less than + some "BAND A" level. Where you are using "public static final" fields you + can either fully-qualify the class name or you can include it in the + "imports" section of the query (see later). +

+
+ +

Data types : literals

+

+ JDOQL supports the following literals: IntegerLiteral, + FloatingPointLiteral, BooleanLiteral, CharacterLiteral, StringLiteral, + and NullLiteral. +

+
+ +

Operators precedence

+

+ The following list describes the operator precedence in JDOQL. +

+
    +
  1. Cast
  2. +
  3. Unary ("~") ("!")
  4. +
  5. Unary ("+") ("-")
  6. +
  7. Multiplicative ("*") ("/") ("%")
  8. +
  9. Additive ("+") ("-")
  10. +
  11. Relational (">=") (">") ("<=") ("<") ("instanceof")
  12. +
  13. Equality ("==") ("!=")
  14. +
  15. Boolean logical AND ("&")
  16. +
  17. Boolean logical OR ("|")
  18. +
  19. Conditional AND ("&&")
  20. +
  21. Conditional OR ("||")
  22. +
+
+ +

Concatenation Expressions

+

+ The concatenation operator(+) concatenates a String to either another + String or Number. Concatenations of String or Numbers to null results in + null. +

+
+ +

Example 1 - Use of Explicit Parameters

+

+ Here's a simple example for finding the elements of a class with a field + below a particular threshold level. Here we pass in the threshold value + (limit), and sort the output in order of ascending price. +

+
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class,"price < limit");
+query.declareParameters("double limit");
+query.setOrdering("price ascending");
+List results = (List)query.execute(150.00);
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " +
+                "price < limit PARAMETERS double limit ORDER BY price ASCENDING");
+List results = (List)query.execute(150.00);
+

+ For completeness, the class is shown here +

+
+class Product
+{
+    String name;
+    double price;
+    java.util.Date endDate;
+    ...
+}
+
+<jdo>
+    <package name="mydomain">
+        <class name="Product">
+            <field name="name">
+                <column length="100" jdbc-type="VARCHAR"/>
+            </field>
+            <field name="abreviation">
+                <column length="20" jdbc-type="VARCHAR"/>
+            </field>
+            <field name="price"/>
+            <field name="endDate"/>
+        </class>
+    </package>
+</jdo>
+
+
+ +

Example 2 - Use of Implicit Parameters

+

+ Let's repeat the previous query but this time using implicit + parameters. +

+
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class,"price < :limit");
+query.setOrdering("price ascending");
+List results = (List)query.execute(150.00);
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.Product WHERE " +
+                "price < :limit ORDER BY price ASCENDING");
+List results = (List)query.execute(150.00);
+

+ So we omitted the declaration of the parameter and just prefixed it with + a colon (:) +

+
+
+ +

Example 3 - Comparison against Dates

+

+ Here's another example using the same Product class as above, but this + time comparing to a Date field. Because we are using a type in our query, + we need to import it ... + just like you would in a Java class if you were using it there. +

+
+Declarative JDOQL :
+Query query = pm.newQuery(domain.Product.class,
+                          "endDate > best_before_limit");
+query.declareImports("import java.util.Date");
+query.declareParameters("Date best_before_limit");
+query.setOrdering("endDate descending");
+Collection results = (Collection)query.execute(my_date_limit);
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.Product " +
+                "WHERE endDate > best_before_limit " +
+                "PARAMETERS Date best_before_limit " +
+                "import java.util.Date ORDER BY endDate DESC");
+List results = (List)query.execute(my_date_limit);
+
+
+ +

Example 4 - Instanceof

+

+ This example demonstrates use of the "instanceof" operator. We have a + class A that has a field "b" of type B and B has subclasses B1, B2, B3. + Clearly the field "b" of A can be of type B, B1, B2, B3 etc, and we want + to find all objects of type A that have the field "b" that is of type B2. + We do it like this +

+
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.A.class);
+query.setFilter("b instanceof mydomain.B2");
+List results = (List)query.execute();
+
+Single-String JDOQL :
+Query query = pm.newQuery("SELECT FROM mydomain.A WHERE b instanceof mydomain.B2");
+List results = (List)query.execute();
+
+
+ +
Modified: websites/production/db/content/jdo/jdoql_methods.html ============================================================================== --- websites/production/db/content/jdo/jdoql_methods.html (original) +++ websites/production/db/content/jdo/jdoql_methods.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -209,299 +209,299 @@
- - -

JDOQL : Methods

-

- 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. -

-
-

String Methods

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MethodDescription
startsWith(String)Returns if the string starts with the passed string
startsWith(String, int)Returns if the string starts with the passed string, after the specified position
endsWith(String)Returns if the string ends with the passed string
indexOf(String)Returns the first position of the passed string
indexOf(String, int)Returns the position of the passed string, after the passed position
substring(int)Returns the substring starting from the passed position
substring(int, int)Returns the substring between the passed positions
toLowerCase()Returns the string in lowercase
toUpperCase()Retuns the string in UPPERCASE
matches(String pattern)Returns whether string matches the passed expression. The pattern argument follows the rules of - java.lang.String.matches method.
trim()Retuns the string with leading/trailing spaces trimmed
length()Retuns the length of the string
charAt(int)Returns the character at the specified position of the string
-

- 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. -

-
-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");
-
-

- Here's another example, demonstrating the "matches" method. - Consult the javadocs for Java regular expressions for the - syntax of the matches input. -

-
-Declarative JDOQL :
-Query query = pm.newQuery(mydomain.Product.class);
-query.setFilter("this.abbreviation.matches(\"a*b\")");
-List results = (List)query.execute();
-
-Single-String JDOQL :
-Query query = pm.newQuery(
-    "SELECT FROM mydomain.Product " +
-    "WHERE this.abbreviation.matches(\"a*b\")");
-List results = (List)query.execute();
-
-
- -

Collection Methods

- - - - - - - - - - - - - - - - - -
MethodDescription
isEmpty()Returns whether the collection is empty
contains(value)Returns whether the collection contains the passed element
size()Returns the number of elements in the collection
-

- 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 (prd to represent the Product being - contained -

-
-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();
-
-
- -

List Methods

- - - - - - - - - -
MethodDescription
get(position)Returns the element at that position in the List (JDO3.1)
-
-
- -

Map Methods

- - - - - - - - - - - - - - - - - - - - - - - - - -
MethodDescription
isEmpty()Returns whether the map is empty
containsKey(key)Returns whether the map contains the passed key
containsValue(value)Returns whether the map contains the passed value
get(key)Returns the value from the map with the passed key
size()Returns the number of entries in the map
-

- 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". -

-
-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();
-
-
- -

Temporal Methods

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MethodDescription
getDay()Returns the day of the month
getMonth()Returns the month of the year
getYear()Returns the year
getHour()Returns the hour
getMinute()Returns the minute
getSecond()Returns the second
-
-
- -

Enum Methods

- - - - - - - - - - - - - -
MethodDescription
ordinal()Returns the ordinal of the enum
toString()Returns the string form of the enum
-
-
- -

Other Methods

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MethodDescription
Math.abs(number)Returns the absolute value of the passed number
Math.sqrt(number)Returns the square root of the passed number
Math.cos(number)Returns the cosine of the passed number
Math.sin(number)Returns the sine of the passed number
Math.tan(number)Returns the tangent of the passed number
JDOHelper.getObjectId(object)Returns the object identity of the passed persistent object
JDOHelper.getVersion(object)Returns the version of the passed persistent object
-
-
- + + +

JDOQL : Methods

+

+ 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. +

+
+

String Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
startsWith(String)Returns if the string starts with the passed string
startsWith(String, int)Returns if the string starts with the passed string, after the specified position
endsWith(String)Returns if the string ends with the passed string
indexOf(String)Returns the first position of the passed string
indexOf(String, int)Returns the position of the passed string, after the passed position
substring(int)Returns the substring starting from the passed position
substring(int, int)Returns the substring between the passed positions
toLowerCase()Returns the string in lowercase
toUpperCase()Retuns the string in UPPERCASE
matches(String pattern)Returns whether string matches the passed expression. The pattern argument follows the rules of + java.lang.String.matches method.
trim()Retuns the string with leading/trailing spaces trimmed
length()Retuns the length of the string
charAt(int)Returns the character at the specified position of the string
+

+ 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. +

+
+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");
+
+

+ Here's another example, demonstrating the "matches" method. + Consult the javadocs for Java regular expressions for the + syntax of the matches input. +

+
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.Product.class);
+query.setFilter("this.abbreviation.matches(\"a*b\")");
+List results = (List)query.execute();
+
+Single-String JDOQL :
+Query query = pm.newQuery(
+    "SELECT FROM mydomain.Product " +
+    "WHERE this.abbreviation.matches(\"a*b\")");
+List results = (List)query.execute();
+
+
+ +

Collection Methods

+ + + + + + + + + + + + + + + + + +
MethodDescription
isEmpty()Returns whether the collection is empty
contains(value)Returns whether the collection contains the passed element
size()Returns the number of elements in the collection
+

+ 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 (prd to represent the Product being + contained +

+
+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();
+
+
+ +

List Methods

+ + + + + + + + + +
MethodDescription
get(position)Returns the element at that position in the List (JDO3.1)
+
+
+ +

Map Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
isEmpty()Returns whether the map is empty
containsKey(key)Returns whether the map contains the passed key
containsValue(value)Returns whether the map contains the passed value
get(key)Returns the value from the map with the passed key
size()Returns the number of entries in the map
+

+ 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". +

+
+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();
+
+
+ +

Temporal Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
getDay()Returns the day of the month
getMonth()Returns the month of the year
getYear()Returns the year
getHour()Returns the hour
getMinute()Returns the minute
getSecond()Returns the second
+
+
+ +

Enum Methods

+ + + + + + + + + + + + + +
MethodDescription
ordinal()Returns the ordinal of the enum
toString()Returns the string form of the enum
+
+
+ +

Other Methods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodDescription
Math.abs(number)Returns the absolute value of the passed number
Math.sqrt(number)Returns the square root of the passed number
Math.cos(number)Returns the cosine of the passed number
Math.sin(number)Returns the sine of the passed number
Math.tan(number)Returns the tangent of the passed number
JDOHelper.getObjectId(object)Returns the object identity of the passed persistent object
JDOHelper.getVersion(object)Returns the version of the passed persistent object
+
+
+
Modified: websites/production/db/content/jdo/jdoql_result.html ============================================================================== --- websites/production/db/content/jdo/jdoql_result.html (original) +++ websites/production/db/content/jdo/jdoql_result.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -209,106 +209,106 @@
- - -

JDOQL : Result

-

- As we have seen, a JDOQL query is made up of different parts. In this section we look at the - result 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 result clause. -

-
    -
  • this - the candidate instance
  • -
  • A field name
  • -
  • A variable
  • -
  • A parameter (though why you would want a parameter returning is hard to see since you input - the value in the first place)
  • -
  • An aggregate (count(), avg(), sum(), min(), max())
  • -
  • An expression involving a field (e.g "field1 + 1")
  • -
  • A navigational expression (navigating from one field to another ... e.g "field1.field4")
  • -
-

- The result is specified in JDOQL like this -

-
query.setResult("count(field1), field2");
-

- In Single-String JDOQL you would specify it directly. -

-
- -

Result type

-

- What you specify in the result defines what form of result you get back. -

-
    -
  • Object - 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)")
  • -
  • Object[] - this is returned if you have only a single row in the results, but more - than 1 column (e.g "max(field1), avg(field2)")
  • -
  • List<Object> - 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")
  • -
  • List<Object[]> - 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)")
  • -
-
- -

Aggregates

-

- 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 -

-
    -
  • avg(val) - returns the average of "val". "val" can be a field, numeric field expression - or "distinct field".
  • -
  • sum(val) - returns the sum of "val". "val" can be a field, numeric field expression, - or "distinct field".
  • -
  • count(val) - returns the count of records of "val". "val" can be a field, or can be - "this", or "distinct field".
  • -
  • min(val) - returns the minimum of "val". "val" can be a field
  • -
  • max(val) - returns the maximum of "val". "val" can be a field
  • -
-

- So to utilise these you could specify something like -

-
-Query q = pm.newQuery("SELECT max(price), min(price) FROM mydomain.Product WHERE status == 1");
-

- 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. -

-
-
- -

Example - Use of aggregates

-

- 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". -

-
-Declarative JDOQL :
-Query query = pm.newQuery(mydomain.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 mydomain.Product WHERE name == \"CD Player\"");
-List results = (List)query.execute();
-Iterator iter = c.iterator();
-Double max_price = (Double)iter.next();
-
-
- -
- - + + +

JDOQL : Result

+

+ As we have seen, a JDOQL query is made up of different parts. In this section we look at the + result 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 result clause. +

+
    +
  • this - the candidate instance
  • +
  • A field name
  • +
  • A variable
  • +
  • A parameter (though why you would want a parameter returning is hard to see since you input + the value in the first place)
  • +
  • An aggregate (count(), avg(), sum(), min(), max())
  • +
  • An expression involving a field (e.g "field1 + 1")
  • +
  • A navigational expression (navigating from one field to another ... e.g "field1.field4")
  • +
+

+ The result is specified in JDOQL like this +

+
query.setResult("count(field1), field2");
+

+ In Single-String JDOQL you would specify it directly. +

+
+ +

Result type

+

+ What you specify in the result defines what form of result you get back. +

+
    +
  • Object - 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)")
  • +
  • Object[] - this is returned if you have only a single row in the results, but more + than 1 column (e.g "max(field1), avg(field2)")
  • +
  • List<Object> - 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")
  • +
  • List<Object[]> - 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)")
  • +
+
+ +

Aggregates

+

+ 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 +

+
    +
  • avg(val) - returns the average of "val". "val" can be a field, numeric field expression + or "distinct field".
  • +
  • sum(val) - returns the sum of "val". "val" can be a field, numeric field expression, + or "distinct field".
  • +
  • count(val) - returns the count of records of "val". "val" can be a field, or can be + "this", or "distinct field".
  • +
  • min(val) - returns the minimum of "val". "val" can be a field
  • +
  • max(val) - returns the maximum of "val". "val" can be a field
  • +
+

+ So to utilise these you could specify something like +

+
+Query q = pm.newQuery("SELECT max(price), min(price) FROM mydomain.Product WHERE status == 1");
+

+ 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. +

+
+
+ +

Example - Use of aggregates

+

+ 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". +

+
+Declarative JDOQL :
+Query query = pm.newQuery(mydomain.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 mydomain.Product WHERE name == \"CD Player\"");
+List results = (List)query.execute();
+Iterator iter = c.iterator();
+Double max_price = (Double)iter.next();
+
+
+ +
+ +
Modified: websites/production/db/content/jdo/jdoquery_dtd.html ============================================================================== --- websites/production/db/content/jdo/jdoquery_dtd.html (original) +++ websites/production/db/content/jdo/jdoquery_dtd.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -223,45 +223,45 @@
- - -

Meta-Data - JDOQuery

-

- JDO2 defines XML MetaData in jdo files as well as orm files, but also - specifies that named queries can be defined in jdoquery files. - As always with XML, the metadata must match the defined DTD/XSD for that file type. - This section describes the content of the jdoquery files. - All jdoquery files must contain a valid DTD/DOCTYPE specification. - You can use PUBLIC or SYSTEM versions of these. -

-

- Here are a few examples valid for jdoquery files eith DTD specification -

-
-<!DOCTYPE jdoquery PUBLIC
-    "-//Sun Microsystems, Inc.//DTD Java Data Objects Query Metadata 3.0//EN"
-    "http://java.sun.com/dtd/jdoquery_3_0.dtd">
-
-
-<!DOCTYPE jdoquery SYSTEM "file:/javax/jdo/jdoquery.dtd">
-
-

- Here is an example valid for jdoquery files with XSD specification -

-
-<?xml version="1.0" encoding="UTF-8" ?>
-<jdo xmlns="http://java.sun.com/xml/ns/jdo/jdo"
-     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-     xsi:schemaLocation="http://java.sun.com/xml/ns/jdo/jdoquery
-        http://java.sun.com/xml/ns/jdo/jdoquery_3_0.xsd">
-    ...
-</jdo>
-

- Your MetaData should match either the DTD - or the XSD specification. -

-
- + + +

Meta-Data - JDOQuery

+

+ JDO2 defines XML MetaData in jdo files as well as orm files, but also + specifies that named queries can be defined in jdoquery files. + As always with XML, the metadata must match the defined DTD/XSD for that file type. + This section describes the content of the jdoquery files. + All jdoquery files must contain a valid DTD/DOCTYPE specification. + You can use PUBLIC or SYSTEM versions of these. +

+

+ Here are a few examples valid for jdoquery files eith DTD specification +

+
+<!DOCTYPE jdoquery PUBLIC
+    "-//Sun Microsystems, Inc.//DTD Java Data Objects Query Metadata 3.0//EN"
+    "http://java.sun.com/dtd/jdoquery_3_0.dtd">
+
+
+<!DOCTYPE jdoquery SYSTEM "file:/javax/jdo/jdoquery.dtd">
+
+

+ Here is an example valid for jdoquery files with XSD specification +

+
+<?xml version="1.0" encoding="UTF-8" ?>
+<jdo xmlns="http://java.sun.com/xml/ns/jdo/jdo"
+     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+     xsi:schemaLocation="http://java.sun.com/xml/ns/jdo/jdoquery
+        http://java.sun.com/xml/ns/jdo/jdoquery_3_0.xsd">
+    ...
+</jdo>
+

+ Your MetaData should match either the DTD + or the XSD specification. +

+
+
Modified: websites/production/db/content/jdo/mail-lists.html ============================================================================== --- websites/production/db/content/jdo/mail-lists.html (original) +++ websites/production/db/content/jdo/mail-lists.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -12,7 +12,7 @@ - + @@ -210,88 +210,88 @@
- - -

Apache JDO Mailing Lists

- -

-There are several publicly available mailing lists for JDO. -The user list is for general discussion of the Apache JDO project and JDO technology. -The dev list is for internal discussion among the JDO developers. It is -open to the public if you are interested in seeing how the sausage is made. -For those dedicated to the project who want to follow its development even more -closely there's the commits mailing list! -

- - - - - - - - - - - - - - - - - - - - -
-

User List : - jdo-user@db.apache.org

-
-

- Subscribe

-
-

- Unsubscribe

-
-

-Archive -

-
-

Dev List : jdo-dev@db.apache.org

-
-

Subscribe

-
-

Unsubscribe

-
-

-Archive -

-
-

Commits List : jdo-commits@db.apache.org

-
-

Subscribe

-
-

Unsubscribe

-
-

-Archive -

-
- -
- + + +

Apache JDO Mailing Lists

+ +

+There are several publicly available mailing lists for JDO. +The user list is for general discussion of the Apache JDO project and JDO technology. +The dev list is for internal discussion among the JDO developers. It is +open to the public if you are interested in seeing how the sausage is made. +For those dedicated to the project who want to follow its development even more +closely there's the commits mailing list! +

+ + + + + + + + + + + + + + + + + + + + +
+

User List : + jdo-user@db.apache.org

+
+

+ Subscribe

+
+

+ Unsubscribe

+
+

+Archive +

+
+

Dev List : jdo-dev@db.apache.org

+
+

Subscribe

+
+

Unsubscribe

+
+

+Archive +

+
+

Commits List : jdo-commits@db.apache.org

+
+

Subscribe

+
+

Unsubscribe

+
+

+Archive +

+
+ +
+
Modified: websites/production/db/content/jdo/metadata.html ============================================================================== --- websites/production/db/content/jdo/metadata.html (original) +++ websites/production/db/content/jdo/metadata.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -223,57 +223,57 @@
- - -

Persistence MetaData

-

- JDO 1.0 and JDO 2.0 support specification of persistence using XML MetaData. - JDO 2.1 adds on the ability to specify persistence using Java5 annotations. -

-

XML MetaData

-

- JDO (1.0.1, 2.0, 2.1) expects any XML MetaData to be specified in a file or files - in particular positions in the file system. For example, if you have a class - com.mycompany.sample.MyExample, JDO will look for any of the following files - until it finds one (in the order stated) :- -

-
-META-INF/package.jdo
-WEB-INF/package.jdo
-package.jdo
-com/package.jdo
-com/mycompany/package.jdo
-com/mycompany/sample/package.jdo
-com/mycompany/sample/MyExample.jdo
-

- In addition to specifying XML MetaData in a jdo file, if defining O/R mapping - information you can also split this out into an ORM file. The locations for ORM files - are similar in nature to those for JDO files. -

-
-META-INF/package-{mapping}.orm
-WEB-INF/package-{mapping}.orm
-package-{mapping}.orm
-com/package-{mapping}.orm
-com/mycompany/package-{mapping}.orm
-com/mycompany/sample/package-{mapping}.orm
-com/mycompany/sample/MyExample-{mapping}.orm
-

- where {mapping} is a property specified by the user and may be "mysql" for - ORM information for MySQL datastores, and "oracle" for ORM information for Oracle - datastores, and so on. -

-
-
- -

Annotations

-

- JDO 2.1 provides support for annotations. Classes and fields/properties can be annotated - defining the persistence and, optionally, any ORM information. -

-
-
- + + +

Persistence MetaData

+

+ JDO 1.0 and JDO 2.0 support specification of persistence using XML MetaData. + JDO 2.1 adds on the ability to specify persistence using Java5 annotations. +

+

XML MetaData

+

+ JDO (1.0.1, 2.0, 2.1) expects any XML MetaData to be specified in a file or files + in particular positions in the file system. For example, if you have a class + com.mycompany.sample.MyExample, JDO will look for any of the following files + until it finds one (in the order stated) :- +

+
+META-INF/package.jdo
+WEB-INF/package.jdo
+package.jdo
+com/package.jdo
+com/mycompany/package.jdo
+com/mycompany/sample/package.jdo
+com/mycompany/sample/MyExample.jdo
+

+ In addition to specifying XML MetaData in a jdo file, if defining O/R mapping + information you can also split this out into an ORM file. The locations for ORM files + are similar in nature to those for JDO files. +

+
+META-INF/package-{mapping}.orm
+WEB-INF/package-{mapping}.orm
+package-{mapping}.orm
+com/package-{mapping}.orm
+com/mycompany/package-{mapping}.orm
+com/mycompany/sample/package-{mapping}.orm
+com/mycompany/sample/MyExample-{mapping}.orm
+

+ where {mapping} is a property specified by the user and may be "mysql" for + ORM information for MySQL datastores, and "oracle" for ORM information for Oracle + datastores, and so on. +

+
+
+ +

Annotations

+

+ JDO 2.1 provides support for annotations. Classes and fields/properties can be annotated + defining the persistence and, optionally, any ORM information. +

+
+
+