Show TOC Start of Content Area

Procedure documentation Constructing and Executing Queries  Locate the document in its SAP Library structure

Use

A query is used to select certain instances from the candidate class based on specific search criteria. To use a query, you must specify the required elements – the candidate class, a set of instances of this class represented by an extent or a collection, and a query filter. In addition, you can use parameters, variables, import declarations and ordering specifications.

Procedure

Constructing a New Query

To construct a new query, the application must invoke the newQuery() method of the javax.jdo.PersistenceManager interface:

Example

Query queryEmployees = pm.newQuery(employeeExtent);

 

You can create a Query object without a filter using the following methods:

·        newQuery(Class class);

·        newQuery(Extent extent);

·        newQuery(Class class, Collection collection);

The interface provides the same methods with an additional filter argument specified as String

·        newQuery(Class class, String filter);

·        newQuery(Extent extent, String filter);

·        newQuery(Class class, Collection collection, String filter);

In addition, you can construct an empty query and set its properties directly using the newQuery()method without parameters. The newQuery(Object query) method enables you to construct a new query from another one. You can also set the query language that you want to use with the newQuery(String language, Object query) method. The default query language used in the rest of the methods is JDOQL.

Specifying a Filter

A filter is a Boolean expression that is evaluated for each instance in the candidate set. If the filter evaluates to true, the instance is added to the result.

The filter expression cannot change the JDO instances. However, it may contain the following functions:

·        String.startsWith(String);

·        String.endsWith(String);

·        Collection.contains(Object);

·        Collection.isEmpty();

The filter can also contain certain operators supported by the JDOQL. For more information about these operators, see JDOQL Operators.

You can set the filter either using the setFilter() method of the javax.jdo.Query interface, or as a parameter of the PesistenceManager.newQuery() method:

Example

String filter = "firstName == \"John\" ";

Query queryEmployees = pm.newQuery(employeeExtent, filter);

In this example, the query selects all employees whose first name is John.

Using Parameters

Optionally, you can use parameters to specify the filtering criteria at runtime. The parameters are declared using the Query.declareParameters() method. Their values are set when the Query.execute() method is invoked with the relevant values passed as parameters:

Example

{

String filter = "firstName == firstParameter && lastName == secondParameter ";

 

Query queryEmployees = pm.newQuery(employeeExtent, filter);

queryEmployees.declareParameters("String firstParameter, String secondParameter");

 

String firstValue = "John";

String secondValue = "Miller";

Collection result = (Collection)queryEmployees.execute(firstValue, secondValue);

/* processing the result */

queryEmployees.close(result);

}

 

Using Variables for Navigation

Variables are another optional element of a query. They enable you to navigate through a collection – that is, to select objects that are related according to one or more criteria. Variables are declared using the Query.declareVariables() method. You must declare a variable for each collection through which you want to navigate. The variable is passed as a parameter to the contains() method to reference the element that is currently processed during the navigation. The contains() method returns true if the referenced collection is non-null and contains at least one element of the declared type. If the type of the variable is unknown within the scope of the Query, you can use the Query.declareImports() method to add an import statement for the variable type.

Example

{

String filter = "employees.contains(emp) && emp.salary > 1000";

Query departmentQuery = pm.newQuery(departmentExtent, filter);

queryEmployees.declareVariables("Employee emp");

Collection result = (Collection)departmentQuery.execute();

}

The example returns a collection containing all employees whose salary is greater than 1000.

Ordering the Result

You can order the result of a query using the Query.setOrder() method and the keywords ascending or descending:

Example

String order = "employee.lastname descending, employee.firstname ascending";

employeeQuery.setOrder(order);

In this query the employees in the result are ordered in descending order by last name, and the employees with same last names are ordered in ascending order by first name.

Compiling and Executing the Query

After the query has been constructed, you may optionally invoke the Query.compile() method. In this invocation, the elements of the query are verified and any errors are reported. Using compilation is recommended when the query is executed repeatedly.

The query may be executed using one of the following Query.execute() methods:

·        execute() – the query is executed without parameters

·        execute(Object) – the query is executed with one parameter

·        execute(Object, Object) – the query is executed with two parameters

·        execute(Object, Object, Object) – the query is executed with three parameters

·        executeWithArray(Object[]) – the query is executed with an array of parameters

·        executeWithMap(Map) – the query is executed with a map of parameters. The map should contain key - value pairs, which correspond to parameter name - value pairs.

When the processing of the result is over, the application must take care to close the result to free resources. Therefore, it must invoke either Query.close(Object queryResult) or Query.closeAll().

 

 

 

End of Content Area