Session Querying

The Session class and its subclasses provide query methods that enable you to run queries against the object model, rather than the relational model. You can invoke query methods using any of the following:

Simple Query API
Query Objects
Predefined Queries

This section introduces query methods.

For more in-depth information, see "Session Queries".

Simple Query API

The Session class offers the following methods to access the database:

The readObject() method uses a primary key to search for a single object in the database or the session cache. Specify the class of the queried object.

For example:
```
session.readObject(MyDomainObject.class);
```
This example returns the first instance of MyDomainObject found in the table that contains the MyDomainObject class. If the query does not find an object that matches the criteria, it returns null. For more complex readObject() queries, augment the query with an OracleAS TopLink Expression.

For more information, see "Using Expressions in Session Queries".
The readAllObjects() method retrieves a Vector of objects from the database. Specify the class of the queried object.

For example:
```
session.readAllObjects(MyDomainObject.class)
```
If the query does not find any objects that match the criteria, it returns an empty vector. For more complex readAllObjects() queries, augment the query with an OracleAS TopLink Expression.

For more information, see "Using Expressions in Session Queries".

The readAllObjects() method does not order the objects but, instead, returns objects in the order in which they are found.

Using Expressions in Session Queries

To form more complex queries, include expressions in session query methods. Expression support makes up two public classes:

The Expression class enables you to build either simple or complex logic into the expression. You can also combine multiple expressions in a query method.
The ExpressionBuilder class is the factory that constructs new expressions.

To combine expressions with query methods, use the Expression Builder to create an expression and set the expressions as the selection criterion for the query.

Example 4-31 The readObject() Method Using an Expression

Employee employee = (Employee) session.readObject(Employee.class, new ExpressionBuilder().get("lastName").equal("Smith"));

Example 4-32 The readAllObjects() Method Using an Expression

Vector employees = session.readAllObjects(Employee.class,new ExpressionBuilder.get("salary").greaterThan(10000));

For more information about the OracleAS TopLink Expression Builder, see "Expressions".

Custom SQL Queries

You can execute custom SQL queries and stored procedure calls from within an OracleAS TopLink application. This feature is useful when you call stored procedures on the database and to access raw data. Use custom SQL strings and stored procedure calls in either of the following ways:

Use the executeSelectingCall() and executeNonSelectingCall() session methods to execute SQL queries directly on the database.

For example:
```
Vector rows = session.executeSelectingCall(new SQLCall("SELECT USER, SYSDATE FROM DUAL"));
```

Call the executeQuery() method on the DatabaseSession. The following code example uses SQL to read all employee IDs:

DirectReadQuery query = new DirectReadQuery();
query.setSQLString("SELECT EMP_ID FROM EMPLOYEE");
Vector ids = (Vector) session.executeQuery(query);

Session Methods and the Unit of Work

If you call a session method to execute native SQL or invoke a stored procedure within a Unit of Work, then the Unit of Work is aware that you called a session method. However, it does not know about any changes the SQL or stored procedure makes to the database outside of the Unit of Work context, and so cannot roll back those changes if the commit call fails. Avoid using session methods inside a Unit of Work.

Query Objects

A query object is an OracleAS TopLink querying mechanism that offers full database querying access. Query objects support search criteria specified in several ways, including OracleAS TopLink expressions.

Use query objects to perform complex querying. An application creates query objects by instantiating the object and defining its querying criteria with either Expression objects or SQL strings.

You can:

Execute the query objects directly, by calling the executeQuery() method on the DatabaseSession.
Define new querying routines, and add the routines to the session. Because you name these queries when you add them to the session, you can call them by name.
Change the default querying behavior for read or write operations. An application can customize how the session queries operate by supplying query objects to the descriptor query manager.
Change the default querying behavior for complex relationship mappings such as selection queries.

For more information about creating and using query objects, see "Query Objects".

Predefined Queries

Predefined queries are queries you store in either the sessions.xml file or the OracleAS TopLink descriptor. Because they are part of the session or descriptor, OracleAS TopLink stores predefined queries in memory after you initially invoke them. Use predefined queries to maintain frequently-called queries.

For more information about predefined queries, see "Predefined Queries".