Skip Headers

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

Previous | Next |

# 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.