|
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 |
All session types provide an executeQuery method that takes any of the following types of DatabaseQuery:
Using DatabaseQuery method setCall, you can define your own Call to accommodate a variety of data source options such as SQL (including stored procedures and stored functions), EJB QL queries, and EIS interactions. For more information, see "Call Queries".
Using DatabaseQuery method setSelectionCriteria, you can specify your selection criteria using a TopLink Expression. For more information, see "TopLink Expressions".
For more information, see "Using DatabaseQuery Queries".
Using an ObjectLevelReadQuery, you can query your data source and return Object instances that match the specified selection criteria. This section describes the following:
For more information, see "Reading Objects Using a DatabaseQuery".
Using a ReadObjectQuery, you can query your data source and return the first object that matches the specified selection criteria.
Using a ReadAllQuery, you can query your data source and return a Collection of all the objects that match the specified selection criteria.
By default, an ObjectLevelReadQuery returns all attributes of the objects read, including all privately owned (child) objects.
If you require only certain attributes from selected objects, you can create a partial object query by using ObjectLevelReadQuery method addPartialAttributes. Using this method, you can improve query performance by making TopLink return objects with only specified attributes populated.
Applications frequently use partial object queries to compile a list for further selection. For example, a query to find the names and addresses of all employees over the age of 40 returns a list of data (the names and addresses) that partially represents objects (the employees). A common next step is to present this list so the user can select the required object or objects from the list. Later retrieval of a complete object is simplified because TopLink always includes the primary key attribute (even if you do not add it as a partial attribute.
Consider the following when you use partial object queries:
You cannot edit or cache partial objects.
Unspecified attributes will be left null.
You cannot have two partial attributes of the same type.
You cannot add a partial attribute which is of the same type as the class being queried.
If you require only summary information for certain attributes from selected objects, it is more efficient to use a ReportQuery (see "Report Query").
For more information, see "Reading Objects Using Partial Object Queries".
Join reading is a query optimization feature that allows a single query for a class to return the data to build the instances of that class and its related objects. Use this feature to improve query performance by reducing database access. By default, relationships are not join-read: each relationship is fetched separately when accessed if you are using indirection (see "Indirection"), or as a separate database query if you are not using indirection.
You can use join reading with ReadObjectQuery and ReadAllObjectQuery to join only one-to-one or one-to-many mapped relationships. Join reading is not currently supported for any other relationship mappings.
Join reading can specify multiple and nested relationships to be joined. Nested joins are expressed through using expressions (see "Expressions for Joining and Complex Relationships").
Outer joins can also be used with join reading through using the expression outer join API. If an outer join is not used, objects with missing one-to-one relationships or empty one-to-many relationships will be filtered from the result set.
You can use join reading between relationships to the same class, or to concrete or leaf inherited classes, but not to root or branch inherited classes that have multiple tables. For more information about inheritance, see "Understanding Descriptors and Inheritance".
You can use join reading with custom SQL or stored procedures, but the query must ensure that all of the required data to build all of the join-read objects is returned. If the result set includes the same tables or fields, they must be returned in the same table order as TopLink would have generated.
Join reading can result in returning duplicate data if a one-to-many or a shared one-to-one relationship is joined. Although TopLink correctly filters the duplicate results from the object result, the duplicate data still must be fetched from the database and can degrade performance, especially if multiple one-to-many relationships are joined. In general, batch reading can be used as a better alternative to join reading, as it does not require fetching duplicate data (see "Avoiding Join-Reading Duplicate Data").
For more information, see "Using Join Reading".
You can use a fetch group with a ReadObjectQuery or ReadAllQuery. When you execute the query, TopLink retrieves only the attributes in the fetch group. TopLink automatically executes a query to fetch all the attributes excluded from this subset when and if you call a getter method on any one of the excluded attributes.
For more information, see the following:
Using a DataLevelReadQuery, you can query your data source and return Object instances that match the specified selection criteria. This section describes the following:
For more information, see "Reading Data with a DatabaseQuery".
|
WARNING: Allowing an unverified SQL string to be passed into constructors of such objects as |
Use a DataReadQuery to execute a selecting SQL string that returns a Collection of the DatabaseRows representing the result set.
Use a DirectReadQuery to read a single column of data (that is, one field) that returns a Collection of the DatabaseRows representing the result set.
Use a ValueReadQuery to read a single data value (that is, one field). A single data value is returned, or null if no rows are returned.
Using an ObjectLevelModifyQuery, you can query your data source to create, update, and delete objects. This section describes the following:
For more information, see "Creating, Updating, and Deleting Objects with a DatabaseQuery".
|
Note: Oracle recommends that you create and update objects using a TopLinkUnitOfWork: doing so is the most efficient way to manage transactions, concurrency, and referential constraints. For more information, see "Understanding TopLink Transactions".
|
If you do not know whether or not an object is new, use a WriteObjectQuery: TopLink performs an existence check if necessary to determine whether to perform an insert or an update.
If you do know whether or not an object exists, you can avoid the existence check by using an UpdateObjectQuery (see "UpdateObjectQuery") or InsertObjectQuery (see "InsertObjectQuery").
If you know that the object you want to modify exists, use an UpdateObjectQuery to avoid having TopLink perform an existence check.
If you know an object is new, you can use an InsertObjectQuery to avoid having TopLink perform an existence check.
To delete a specific object, construct a DeleteObjectQuery with a single specific object as an argument.
The UpdateAllQuery allows you to take an expression and update a set of objects (at the object level) without loading the objects into memory. You can updated to either a specific or relative value. For example, you can set the value to 5 or to increase by 5 percent.
To delete multiple objects, construct a DeleteAllQuery and use DeleteAllQuery method setObjects to configure the collection of specific objects to delete. Use DeleteAllQuery method setReferenceClass to configure the reference class of the objects to delete. Each specified object and all its privately owned parts are deleted. In the case of a DeleteAllQuery, all deletions are performed within a single transaction.
When you execute a create or update object DatabaseQuery, it writes both the object and its privately owned parts to the database by default. To create a query that does not update privately owned parts, use the DatabaseQuery method dontCascadeParts. Use this method to do the following:
Increase performance when you know that only the object's direct attributes have changed.
Manually resolve referential integrity dependencies when you write large groups of new, independent objects.
|
Note: Because the unit of work resolves referential integrity internally, this method is not required if you use the unit of work to write to the data source. For more information, see "Understanding TopLink Transactions". |
Using a DataModifyQuery, you can query your data source to execute a nonselecting SQL statement. It is equivalent to Session method executeNonSelectingCall.
For more information, see "Updating Data With a DatabaseQuery".
If you want to summarize (or roll up) certain attributes of a set of objects, you can use a ReportQuery.
A ReportQuery returns summary data from a set of objects and their related objects. That is, it returns data about objects, rather than the objects themselves. However, it still lets you query and specify the data at the object level. To build a report query, you specify the search criteria, the data you require about the objects, and how that data should be summarized.
For example, you can create a report query to compute the average age of all employees in your company. The report query is not interested in the specific objects (the employees), but rather, summary information about them (their average age).
A ReportQuery lets you do the following:
Specify a subset of the object's attributes and its related object's attributes, which allows you to query for lightweight information.
Build complex object-level expressions for the selection criteria and ordering criteria.
Use data source aggregation functions (supported by your platform), such as SUM, MIN, MAX, AVG, and COUNT.
Use expressions to group data.
Request primary key attributes with each ReportQueryResult. This makes it easy to request the real object from a lightweight result.
|
Note: TopLink report queries do not support multiple references to the same attribute in a single result set. You can only choose attributes that are configured with a direct mapping (converters included) or a user-defined query key. |
A ReportQuery is the most efficient form of partial object query (see "Partial Object Queries") because it takes advantage of the reporting capabilities of your data source (if available). Oracle recommends that you use ReportQuery to do partial object queries.
The ReportQuery API returns a collection of ReportQueryResult objects, similar in structure and behavior to a DatabaseRow or a Map. For more information, see "Report Query Results".
For more information, see the following:
