JDO 2.0 Quick Reference



Back to the Speedo documentation

javax.jdo.Query Interface

Method
Description
void setClass (Class candidateCls) set the class to query on
void setCandidates (Collection candidates)
query onthe objects in the collection
void setCandidates (Extent extent) query on all objects in the extent
void setFilter (String filter) set the query string to use to filter candidates
void declareParameters (String variables) comma separated list of parameters
void declareVariables (String variables) semi-colon separated list of variables
void declareImports (String imports) semi-colon separated list of imports
void setOrdering (String ordering) comma separated list of ordering statements
void setResult (String result) comma separated list of aggregates/projections
void setResultClass (Class resultClass) pack results into the given class
void setUnique (boolean unique) return a single instance rather than a collection
void setGrouping (String grouping) comma separated list of grouping statements
void setRange (int from, int to) limit results to the given subset of results
void setIgnoreCache (boolean ignore)
boolean getIgnoreCache ()
indicate if a query should ignore changes in transaction
void compile () compile the filter for use
Object execute ()
Object execute (Object parameter)
Object execute (Object parameter1, Object p2)
Object execute (Object p1, Object p2, Object p3)
Object executeWithArray (Object[] parameters)
Object executeWithMap (Map parameters)
Execute with the given parameters.
Array must be in the same order as declaration,
while Map keys must match the name of declared parameters
PersistenceManager getPersistenceManager () return the associated PersistenceManager instance
void close (Object result)
void closeAll ()
close the result collection and any associated resources
void setExtension (Map extensions)
void addExtension (String key, Object value)
add vendor dependent extensions to the query
FetchPlan getFetchPlan () return the current fetch configuration for the query

javax.jdo.Query Interface

Symbol
Description
Example
==equalfirstname== John
!=not equalage != 22
>greater than
$lt;lesser than
>=greater than or equal
$lt;=lesser than or equal
&&conditional ANDfirstname== John & &age == 25
||conditional OR
|boolean logical OR
-subtraction or sign conversion
+addition or string concatenation
*multiply
/divide
%modulo
!logical complement!(firstname== John )
~bitwise complement
instanceofinstanceof

JDOQL Methods

Method
Type to apply
Example
toLowerCase ()Stringfirstname.toUpperCase () == JOHN
toUpperCase ()String
indexOf (String)Stringname.indexOf ( h ) == 2
indexOf (String, int) String
matches (String)Stringfirstname.matches ( .*ohn.* )
substring (int)String
substring (int, int)String
startsWith (String)String
endsWith (String)String
contains (Object)Collection
containsKey(Object)Map
containsValue(Object)Map
Math.abs (numeric)numeric typesMath.abs (balance) > 500
Math.sqrt (numeric)double
JDOHelper.getObjectIdObjectuse identity in a query

Using Queries

class Person { 
	int age; 
	String firstname;
	String lastname; 
	Address address; 
	Set children;
	// ... // 
}

Basic example:

Find all people with the first name John . Iterate over the results, printing each Person s last name.

Query query = pm.newQuery (Person.class,  "firstname== John"); 
Collection people = (Collection) query.execute (); 
for (Iterator i = people.iterator (); i.hasNext ();) {
	System.out.println(((Person) i.next ()).getLastname ()); 
}
query.closeAll (); // Close query resources 

Using Parameters

Parameters allow queries to use known data, including primitives and other persistent instances in JDOQL filters.

Simple parameters:

Find all people named John . Parameters allow using known data in the query, in this case a String.

Query q = pm.newQuery (Person.class,  "firstname==param");
q.declareParameters ( String param ); 
Collection people = (Collection) q.execute ( John ); 

Using persistent instances as parameters:

Find all people with a given address who are also older than 21.

Address address
= (Address) pm.getObjectById (...); 
Query query = pm.newQuery (Person.class, 
	"address==param1 && age>param2"); 
query.declareParameter (Address param1, int param2 ); 
Collection people = (Collection) query.execute (address, new Integer
(21));
.

JDOQL 2.0 Using Variables

Variables allow queries to query on related or unknown fields. Like parameters, variable declarations must also be matched with proper import declarations.

Querying on a related instance:

Find all parents of a Person named John .
Query query = pm.newQuery (Person.class);
query.declareVariables (Person p ); 
query.setFilter ( children.contains (p) && p.firstname ==  John ); 
Collection parents = (Collection) query.execute (); 

Ordering Query Results Query

Results can be ordered on one or more fields using the keywords ascending and descending.

Ordering on a single field:

Order query results by age, oldest first.

query.setOrdering ( age descending ); 

Ordering on multiple fields:

Order query results by name, from A to Z, and then by age, from oldest to youngest.

query.setOrdering ( firstname ascending, age descending );

Optimizing Query Behavior

Limiting/paging query results:

The query can be configured to only return a subset of the results so that unused elements will not be instantiated. The start point is included, while the element at the limit is not.

query.setRange (10, 20); 

Ignore PersistenceManager cache:

Ignoring changes in the PersistenceManager can speed up queries.

query.setIgnoreCache (true);

Indicate unique result:

This option tells the JDO implementation that only one result is expected and to return only the single instance instead of a Collection

query.setUnique(true); 
Person john = (Person) query.execute ();

Aggregates / Projections

Aggregates are calculations over multiple results, such as the sum of a field. Projections allow queries to return individual fields instead of the entire object. Both aggregates and projections can be packed into result classes.

Returning simple results:

Return just the first name of Person.

Query query = pm.newQuery (Person.class) 
query.setResult ( firstname); 
Collection names = (Collection) query.execute ();
for (Iterator i = names.iterator (); i.hasNext ();) {
	System.out.println((String) i.next ()); 
}

Using aggregate functions:

Return the sum of all ages.

Query query = pm.newQuery (Person.class);
query.setResult ( sum (age) ); 
Double sum = (Double) query.execute ();

Returning only distinct results:

Return the values of first name with no repeat

values. Query query = pm.newQuery (Person.class); 
query.setResult ( distinct firstname ); 

Using custom result class:

Return values in a class designed to hold the results.

public class Name { 
	public String firstname; 
	public String lastname;
	public String getFullname () { return firstname +" " + lastname; } 
} 
Query query = pm.newQuery (Person.class); 
query.setResult ( firstname, lastname ); 
query.setResultClass (Name.class);
Collection names = (Collection) query.execute (); 
for (Iterator i = names.iterator (); i.hasNext ();) {
	System.out.println ((Name) i.next ()).getFullname ()); 
}

Aggregate Functions

Function
Description
count (<expression>) The count of the expression, which can include this
sum (<numeric>) Return the sum of the numeric expression
avg (<numeric>) Return the average value of the numeric expression
min (<comparable>) Return the smallest value of the comparable expression
max (<comparable>) Return the largest value of the comparable expression

Grouping Results

Grouping allows aggregates and projections to be grouped by a given field, and optionally limiting those groups by a having expression.

Simple grouping:

Group by firstname.

query.setGrouping ( firstname ); 

Limiting grouping with having expression:

Group by firstname where the firstname starts with J

query.setGrouping (firstname having   + firstname.startsWith ( J ) );

SQL Queries

Queries can use SQL instead of JDOQL queries when accessing a relational database.

SQL Query:

Find people whose first name is John .

Query sql = pm.newQuery (Query.SQL, 
"SELECT *    FROM PERSON WHERE FIRSTNAME = JOHN  ); 
sql.setClass (Person.class);
Collection people = (Collection) query.execute ();