Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# Query Concepts

In general, querying a data source means performing an action on or interacting with the contents of the data source. To do this, you must be able to perform the following:

- Define an action in a syntax native to the data source being queried

- Apply the action in a controlled fashion

- Manage the results returned by the action (if any)

Specific to TopLink, you must also consider how the query affects the TopLink cache. For more information, see "Queries and the Cache".

This section introduces query concepts unique to TopLink, including the following:

- Call

- DatabaseQuery

- Data-Level and Object-Level Queries

- Summary Queries

- Descriptor Query Manager

- TopLink Expressions

- Query Keys

- Query Languages

## Call

In TopLink, the `Call` object encapsulates an operation or action on a data source. TopLink provides a variety of `Call` types such as structured query language (SQL), Enterprise Java Beans Query Language (EJB QL), Extensible Markup Language (XML), and enterprise information system (EIS).

You can execute a `Call` directly or in the context of a `DatabaseQuery`.

## DatabaseQuery

A `DatabaseQuery` object is an abstraction that associates additional customization and optimization options with the action encapsulated by a `Call`. By separating these options from the `Call`, TopLink can provide sophisticated query capabilities across all `Call` types.

For more information, see "Database Queries".

## Data-Level and Object-Level Queries

In TopLink, queries can be defined for objects or data.

- Object-level queries (see "Object-Level Read Query" and "Object-Level Modify Query") are object-specific and return data as objects in your domain model. They are the preferred type of query for mapped data. By far, object-level `DatabaseQuery` queries are the most common query used in TopLink.

- Data-level queries (see "Data-Level Read Query" and "Data-Level Modify Query") are used to query database tables directly, and are an appropriate way to work with unmapped data, such as foreign keys and object version fields.

## Summary Queries

While data-level queries return raw data and object-level queries return objects in your domain model, summary queries return data about objects. TopLink provides partial object queries (see "Partial Object Queries") to return a set of objects with only specific attributes populated, and report queries (see "Report Query") to return summarized (or rolled-up) data for specific attributes of a set of objects.

## Descriptor Query Manager

In addition to storing named queries applicable to a particular class (see "Named Queries"), you can also use the `DescriptorQueryManager` to override the default action that TopLink defines for common data source operations. For more information, see "Descriptor Query Manager Queries".

## TopLink Expressions

TopLink expressions let you specify query search criteria based on your domain object model. When you execute the query, TopLink translates these search criteria into the appropriate query language for your platform.

TopLink provides two public classes to support expressions:

- The `Expression` class represents an expression that can be anything from a simple constant to a complex clause with boolean logic. You can manipulate, group, and integrate expressions.

- The `ExpressionBuilder` class is the factory for constructing new expressions.

You can specify a selection criterion as an `Expression` with `DatabaseQuery` method `setSelectionCriteria` (see "Database Queries"), and in a finder that takes an `Expression` (see "Expression Finders").

For more information about using TopLink expressions, see "Understanding TopLink Expressions".

## Query Keys

A query key is a schema-independent alias for a database field name. Using a query key, you can refer to a field using a schema-independent alias. In relational projects only, TopLink automatically creates query keys for all mapped attributes. The name of the query key is the name of the class attribute specified in your object model.

You can configure query keys in a class descriptor (see "Configuring Query Keys") or interface descriptor (see "Configuring Interface Query Keys").

You can use query keys in expressions (see "Query Keys and Expressions") and to query variable one-to-one mappings (see "Using Queries on Variable One-to-One Mappings").

## Query Languages

Using TopLink, you can express a query using any of the following query languages:

- SQL Queries

- EJB QL Queries

- XML Queries

- EIS Interactions

- Query by Example

In most cases, you can compose a query directly in a given query language or, preferably, you can construct a `DatabaseQuery` with an appropriate `Call` and specify selection criteria using a TopLink `Expression`. Although composing a query directly appears to be the simplest approach (and for simple operations or operations on unmapped data, it is), using the `DatabaseQuery` approach offers the compelling advantage of confining your query to your domain object model and avoiding dependence on data source schema implementation details. Oracle recommends that you compose your queries using `DatabaseQuery`, `Call`, and `Expression`.

### SQL Queries

SQL is the most common query language for applications that use a relational database data source.

You can execute custom SQL directly using `Session` methods `executeSelectingCall` and `executeNonSelectingCall`, or you can construct a `DatabaseQuery` with an appropriate `Call`.

TopLink provides a variety of SQL `Call` objects for use with stored procedures and, with Oracle databases, stored functions. For more information, see "SQL Calls".

### EJB QL Queries

Like SQL, EJB QL is a query language; but unlike SQL, it presents queries from an object model perspective, allowing you to declare queries using the attributes of each abstract entity bean in your object model. It also includes path expressions that enable navigation over the relationships defined between entity beans and dependent objects.

Using EJB QL offers the following advantages:

- You do not need to know the database structure (such as tables and fields).

- You can construct queries using the attributes of the entity beans instead of using database tables and fields.

- You can use relationships in a query to provide navigation from attribute to attribute.

- EJB QL queries are portable because they are database-independent.

- You can specify the reference class in the `SELECT` clause.

The disadvantage of EJB QL queries is that it is difficult to use when you construct complex queries.

TopLink supports the EJB QL specification with the following exceptions:

- Arithmetic functions

- `ESCAPE`

- `IS [NOT] EMPTY`

- `[NOT] MEMBER [OF]`

Note: TopLink supports the `LOCATE` string function and will generate the correct SQL with it. However, not all data sources support `LOCATE`. Before using the `LOCATE` string function, consult your data source documentation.

EJB QL is the standard query language defined in the EJB 2.0 specification. Consequently, TopLink lets you specify selection criteria using EJB QL in an EJB finder (see "EJB QL Finders").

Although EJB QL is usually associated with EJB, TopLink also lets you specify selection criteria using EJB QL in queries for regular Java objects as well. TopLink provides an EJB QL `Call` that you can execute directly or in the context of a `DatabaseQuery`. For more information, see "EJB QL Calls" and "DatabaseQuery".

### XML Queries

You can use TopLink XML to query XML data stored in an Oracle Database XMLType field. For more information, see "Direct to XMLType Mapping" and "XMLType Functions".

### EIS Interactions

When you execute a TopLink query using an EIS `Call` (see "Enterprise Information System (EIS) Interactions"), TopLink converts your selection criteria into an XML format appropriate for your J2C adapter.

If supported by your J2C adapter, you can use the XQuery language by executing an XQuery interaction (see "XQueryInteraction") either directly or in the context of a `DatabaseQuery`.

### Query by Example

Query by example is a simple and intuitive way to express a query. To specify a query by example, provide a sample instance of the persistent object to query, and set appropriate values on only the data members on which you wish to query.

You can use any valid constructor to create a sample instance or example object.

Query by example lets you query for an object based on any attribute that uses a direct mapping or a one-to-one relationship (including those with nesting).

Note: Query by example does not support any other relationship mapping types nor does it support EJB 2.0 beans.

Set only the attributes on which you base the query; set all other attributes to `null`. By default, TopLink ignores attributes in the sample instance that contain `null`, zero (0), empty strings, and `FALSE`. You can modify this list of values (and define other query by example options) by specifying a `QueryByExamplePolicy` (see "Defining a QueryByExamplePolicy").

Query by example uses the `AND` operator to tie the attribute comparisons together. By default, attribute values in the sample instance are compared against corresponding values of candidate objects using `EQUALS` operator. You can modify this behaviour using the `QueryByExamplePolicy`.

Both `ReadAllQuery` and `ReadObjectQuery` provide a `setExampleObject` method and `setQueryByExamplePolicy` method that you can use to specify selection criteria based on an example object instance.

For more information, see "Reading Objects Using Query By Example".