Query Objects and Write Operations

Although OracleAS TopLink applications most often perform database write operations through a Unit of Work, you can also write to the database with query objects. This section describes some of the more common strategies for using write queries, and includes discussions on:

• Write Query Overview

• Non-Cascading Write Queries

• Disabling the Identity Map Cache During a Write Query

• Using Query Objects to Customize the Default Database Operations

Write Query Overview

To execute a write query, use a WriteObjectQuery instance instead of using the writeObject() method of the session. Likewise, substitute DeleteObjectQuery, UpdateObjectQuery, and InsertObjectQuery objects for their respective Session methods.

Example 6-62 Using a WriteObjectQuery Object

WriteObjectQuery writeQuery = new WriteObjectQuery();
writeQuery.setObject(domainObject);
session.executeQuery(writeQuery);

Example 6-63 Using Other Write Query Objects with Similar Syntax

InsertObjectQuery insertQuery= new InsertObjectQuery();
insertQuery.setObject(domainObject);
session.executeQuery(insertQuery);

/* When you use UpdateObjectQuery without a Unit of Work, UpdateObjectQuery writes all direct attributes to the database */
UpdateObjectQuery updateQuery= new UpdateObjectQuery();
updateQuery.setObject(domainObject2);
session.executeQuery(updateQuery);

DeleteObjectQuery deleteQuery = new DeleteObjectQuery();
deleteQuery.setObject(domainObject2);
session.executeQuery(deleteQuery);

Non-Cascading Write Queries

When you execute a write query, it writes both the object and its privately owned parts to the database by default. To build write queries that do not update privately owned parts, include the dontCascadeParts() method in your query definition.

Use this method to:

• Increase performance when you know that only the direct attributes of the objects have changed.

• 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 database.

  
  

Example 6-64 Performing a Non-Cascading Write Query

// theEmployee is an existing employee read from the database.
Employee.setFirstName("Bob");
UpdateObjectQuery query = new UpdateObjectQuery();
query.setObject(Employee);
query.dontCascadeParts();
session.executeQuery(query);

Disabling the Identity Map Cache During a Write Query

When you write objects to the database, OracleAS TopLink copies them to the session cache by default. To disable this behavior within a query, call the dontMaintainCache() method within the query. This improves query performance when you insert objects into the database, but only must be used on objects that will not be required later by the application.

Example 6-65 Disabling the Identity Map Cache During a Write Query

This code reads all the objects from a flat file and writes new copies of the objects into a table.

// Reads objects from an employee file and writes them to the employee table.
void createEmployeeTable(String filename, Session session)
{
   Iterator iterator;
   Employee employee;
   // Read the employee data file.
   List employees = Employee.parseFromFile(filename);
   Iterator iterator = employees.iterator();
   while (iterator.hasNext()) {
      Employee employee = (Employee) iterator.next();
      InsertObjectQuery query = new InsertObjectQuery();
      query.setObject(employee);
      query.dontMaintainCache();
      session.executeQuery(query);
}

Caution: Disable the identity map only when object identity is unimportant in subsequent operations.

Using Query Objects to Customize the Default Database Operations

OracleAS TopLink provides default querying behavior for each of the read and write operations that is sufficient for most applications. In addition, applications can define their own custom queries where required:

• If the custom query is specific to a persistent class, register it with the descriptor of that class.

  For more information, see "Query Managers".

• If the custom query is global for the project rather than specific to a particular class, register it with the session. Execute registered queries by calling one of the executeQuery() methods of DatabaseSession or UnitOfWork.