Historical Queries

By default, a session represents a view of the most current version of objects and when you execute a query in that session, it returns the most current version of selected objects.

If your data source maintains past or historical versions of objects, you can configure TopLink to access this historical data (see "Historical Client Sessions").

Once you configure TopLink to take advantage of this historical data, you can access historical versions using the historical queries that Table 96-4 summarizes.

Note: Flashback queries do not support view selects. This means you cannot use a flashback query on objects with an inheritance policy for read-all-subclasses views. For more information, see "Understanding Descriptors and Inheritance".

Table 96-4 Historical Queries

Historical Query Type	Session	Cache	Must set maintainCache to false?	Query both current and historical versions?
Using an ObjectLevelReadQuery With an AsOfClause	RegularFoot 1	Global Read and write Contains current versions	Yes	No
Using an ObjectLevelReadQuery With Expression Operator asOf	RegularFootref 1	Global Read and write Contains current versions	Yes	Yes
Using an ObjectLevelReadQuery in a Historical Session	HistoricalFoot 2	Isolated Read-only Contains static snapshot as of specified time	No	No

^Footnote 1 A server or database session based on an OraclePlatform for an Oracle9i (or later) or based on a TopLink HistoryPolicy.

^Footnote 2 A session returned by a server or database session based on an OraclePlatform or TopLink HistoryPolicy using the acquireHistoricalSession method passing in an AsOfClause.

Using an ObjectLevelReadQuery With an AsOfClause

You can query historical versions of objects using an ObjectLevelReadQuery configured with an AsOfClause (set by ObjectLevelReadQuery method setAsOfClause) that specifies a point in time that applies to every Expression used in the query.

This type of historical query lets you query a static snapshot of object versions as of the specified time.

Note: To prevent corrupting the global shared cache with old versions of objects, you must set ObjectLevelReadQuery method maintainCache to false in this historical query. If you do not, TopLink will throw an exception when you execute the query.

For more information and examples of using an ObjectLevelReadQuery with an AsOfClause, see "Using Historical Queries".

Using an ObjectLevelReadQuery With Expression Operator asOf

You can query historical versions of objects using an ObjectLevelReadQuery (such as ReadObjectQuery or ReadAllQuery) containing one or more expressions that use Expression operator asOf to specify a point in time on an Expression-by-Expression basis.

This type of historical query lets you combine both current and historical versions of objects in the same query.

If you configure the ObjectLevelReadQuery with an AsOfClause, that point in time overrides the point in time specified in any Expression in the query (see "Using an ObjectLevelReadQuery With an AsOfClause").

Note: To prevent corrupting the global shared cache with old versions of objects, you must set ObjectLevelReadQuery method maintainCache to false in this historical query. If you do not, TopLink will throw an exception when you execute the query.

For more information and examples of using an ObjectLevelReadQuery with Expression operator asOf, see "Using Historical Queries".

Using an ObjectLevelReadQuery in a Historical Session

Given a session that maintains historical versions of objects (based on an appropriate OraclePlatform or TopLink HistoryPolicy), you can use Session method acquireHistoricalSession passing in an AsOfClause that specifies a point in time that applies to all queries and expressions.

This method returns a lightweight, read-only snapshot of object versions as of the specified time. The cache used in this type of session is isolated from the global shared cache. You do not need to set ObjectLevelReadQuery method maintainCache to false in this case.

For more information and examples of using an ObjectLevelReadQuery with a historical session, see "Using Historical Queries".