Session Queries

Sessions provide query methods that lets you perform the object operations listed in Table 96-3.

Table 96-3 Session Object Query Summary

Session Type	Create	Read	Update	Delete
`UnitOfWork`	NA	`readObject` `readAllObjects`	NA	`deleteObject` `deleteAllObjects`
`Server`	`insertObject`	`readObject` `readAllObjects`	`updateObject` `writeObject` `writeAllObjects`	`deleteObject` `deleteAllObjects`
`ClientSession`	NA	`readObject` `readAllObjects`	NA	NA
`DatabaseSession`	`insertObject`	`readObject` `readAllObjects`	`updateObject` `writeObject` `writeAllObjects`	`deleteObject` `deleteAllObjects`

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

These methods implicitly construct and execute a DatabaseQuery based on any of the following input parameters and return Object or Object collection:

Reference Class (the Class of objects that the query accesses)
Reference Class and Call
Reference Class and Expression
Example object with primary key set

These methods are a convenient way to perform the most common data source operations on objects.

WARNING:

Allowing an unverified SQL string to be passed into these methods makes your application vulnerable to SQL injection attacks.

To access all configurable options to further refine and optimize a query, consider using a corresponding DatabaseQuery directly. For more information, see "Database Queries".

For more information, see "Using Session Queries".

Read-Object Session Queries

Read-object queries return the first instance of an Object that matches the specified selection criteria, and read-all object queries return all such instances.

You can also pass in a domain Object with its primary key set and TopLink will construct and execute a read-object query to select that object. This is one form of query by example. For more information on query by example, see "Query by Example".

For more information, see "Reading Objects with a Session Query".

Create, Update, and Delete Object Session Queries

Oracle recommends that you create and update objects 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".

However, you can also create and update objects using a session query. These session queries are a convenient way to modify objects directly on the database when you manage simple, nonbusiness object data that has no relationships (for example, user preferences).

If you know an object is new, you can use an insertObject method to avoid having TopLink perform an existence check. If you do not know if an object is new, use the updateObject, writeObject, or writeAllObject methods: TopLink performs an existence check if necessary.

When you execute a write session query, it writes both the object and its privately owned parts to the database. To manage this behavior, use a corresponding DatabaseQuery (see "Object-Level Modify Queries and Privately Owned Parts").

Using the Session method deleteObject, you can delete a specific object. Using the Session method deleteAllObjects, you can delete a collection of objects. Each specified object and all its privately owned parts are deleted. In the case of deleteAllObjects, all deletions are performed within a single transaction.

For more information, see "Creating, Updating, and Deleting Objects with a Session Query".