|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
 Previous |
 Next |
|
Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
|
Previous |
Next |
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:
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.
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".
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.
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.
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 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".
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").
Using TopLink, you can express a query using any of the following query languages:
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 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".
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 theLOCATE 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".
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".
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 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".
