JDO 2.0 Quick Reference

Back to the Speedo documentation

javax.jdo.Query Interface

javax.jdo.Query Interface

JDOQL Methods

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:

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.

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

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