Using Session Queries

This section provides examples of using the session query methods for the following:

• Reading Objects with a Session Query

• Creating, Updating, and Deleting Objects with a Session Query

Note: Oracle recommends that you perform all data source operations using a unit of work: doing so is the most efficient way to manage transactions, concurrency, and referential constraints. For more information, see "Understanding TopLink Transactions".

For more information, see "Session Queries".

Reading Objects with a Session Query

Using the session query API, you can perform the following read operations:

• Reading an Object with a Session Query

• Reading All Objects with a Session Query

• Refreshing an Object with a Session Query

Reading an Object with a Session Query

The readObject method retrieves a single object from the database. The application must specify the class of object to read. If no object matches the criteria, a null value is returned.

For example, the basic read operation is:

session.readObject(MyDomainObject.class);

This example returns the first instance of MyDomainObject found in the table used for MyDomainObject. TopLink provides the Expression class to specify querying parameters for a specific object.

When you search for a single, specific object using a primary key, the readObject method is more efficient than the readAllObjects method, because readObject can find an instance in the cache without accessing database. Because a readAllObjects method does not know how many objects match the criteria, it always searches the database to find matching objects, even if it finds matching objects in the cache.

Example 98-1 readObject Using an Expression

import oracle.toplink.sessions.*;
import oracle.toplink.expressions.*;

/* Use an expression to read in the employee whose last name is Smith. Create an expression using the Expression Builder and use it as the selection criterion of the search */
Employee employee = (Employee) session.readObject(Employee.class, new ExpressionBuilder().get("lastName").equal("Smith"));

Reading All Objects with a Session Query

The readAllObjects method retrieves a Vector of objects from the database and does not put the returned objects in order. If the query does not find any matching objects, it returns an empty Vector.

Specify the class for the query. You can also include an expression to define more complex search criteria, as illustrated in Example 98-2.

Example 98-2 readAllObjects Using an Expression

// Returns a Vector of employees whose employee salary is greater than 10000
Vector employees = session.readAllObjects(Employee.class,new ExpressionBuilder.get("salary").greaterThan(10000));

WARNING: Allowing an unverified SQL string to be passed into methods (for example: readAllObjects(Class class, String sql) and readObject(Class class, String sql) methods) makes your application vulnerable to SQL injection attacks.

Refreshing an Object with a Session Query

The refreshObject method causes TopLink to update the object in memory using data from the database. This operation refreshes any privately owned objects as well.

Note: A privately owned object is one that cannot exist without its parent, or source object.

Creating, Updating, and Deleting Objects with a Session Query

Using the session query API, you can perform the following create, update, and delete operations:

• Writing a Single Object to the Database with a Session Query

• Writing All Objects to the Database With a Session Query

• Adding New Objects to the Database with a Session Query

• Modifying Existing Objects in the Database with a Session Query

• Deleting Objects in the Database with a Session Query

Writing a Single Object to the Database with a Session Query

When you invoke the writeObject method, the method performs a does-exist check to determine whether or not an object exists. If the object exists, writeObject updates the object; if it does not exist, writeObject inserts a new object.

The writeObject method writes privately owned objects in the correct order to maintain referential integrity.

Call the writeObject method when you cannot verify that an object exists in the database.

Example 98-3 Writing a Single Object Using writeObject

// Create an instance of the employee and write it to the database
Employee susan = new Employee();
susan.setName("Susan");
...
// Initialize the susan object with all other instance variables
session.writeObject(susan); 

Writing All Objects to the Database With a Session Query

You can call the writeAllObjects() method to write multiple objects to the database. The writeAllObjects() method performs the same does-exist check as the writeObject() method and then performs the appropriate insert or update operations.

Example 98-4 Writing Several Objects Using writeAllObjects

// Read a Vector of all the current employees in the database.
Vector employees = (Vector) session.readAllObjects(Employee.class);
...// Modify any employee data as necessary
// Create a new employee and add it to the list of employees
Employee susan = new Employee();
...
// Initialize the new instance of employee
employees.add(susan);
/* Write all employees to the database. The new instance of susan not currently in the database will be inserted. All the other employees currently stored in the database will be updated */
session.writeAllObjects(employees);

Adding New Objects to the Database with a Session Query

The insertObject method creates a new object in the database, but does not perform the does-exist check before it attempts the insert operation. The insertObject method is more efficient than the writeObject method if you are certain that the object does not yet exist in the database. If the object does exist, the database throws an exception when you execute the insertObject method.

Modifying Existing Objects in the Database with a Session Query

The updateObject method updates existing objects in the database, but does not perform the does-exist check before it attempts the update operation. The updateObject is more efficient than the writeObject method if you are certain that the object does exist in the database. If the object does not exist, the database throws an exception when you execute the updateObject method.

Deleting Objects in the Database with a Session Query

To delete a TopLink object from the database, read the object from the database and then call the deleteObject method. This method deletes both the specified object and any privately owned data.