Skip Headers

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

Previous | Next |

# Using Queries and the Cache

This section describes how to use caching options in TopLink queries, including the following:

- Caching Results in a ReadQuery

- Configuring Cache Expiration at the Query Level

## Caching Results in a ReadQuery

By default, each time you execute a `ReadQuery`, TopLink applies the current query configuration to the read operation. In doing so, TopLink will access the session cache, the data source, or both.

Some queries are known to return the same result set (for example, the number of units sold last year by the current sales person). After the first query execution, there is no need to actually execute the query if it is invoked again.

For these types of queries, you can use any TopLink `ReadQuery` and configure it to store its query results in an internal query cache.

After its first execution for a set of query parameters, the query will return its cached result set each time it is invoked with the same query parameters. This improves query performance for frequently executed queries. By default a query will cache the results sets for the last 100 queries of specific parameters. You can configure this query cache as part of the `QueryResultsCachePolicy`.

Enable this feature using `ReadQuery` method `cacheQueryResults` or by calling the `ReadQuery` method `setQueryResultsCachePolicy` with an instance of `QueryResultsCachePolicy`, and disable it using `ReadQuery` method `doNotCacheQueryResults`.

Before using this feature, consider the restrictions in "Internal Query Cache Restrictions". For more information, see "Caching Query Results".

You can apply a cache invalidation policy to the query's internal cache (see "Configuring Cache Expiration at the Query Level"). For more information, see "Cache Invalidation".

Example 99-24 shows how to configure a `ReadQuery` to cache its results.

Example 99-24 Configuring a ReadQuery to Cache Its Query Results

    ReadObjectQuery query = new ReadObjectQuery();
    query.setReferenceClass(Employee.class);

    // Instruct the ReadQuery to cache its query results
    query.cacheQueryResults();

    // The first time you invoke it, the ReadQuery reads from the database, session
    // cache, or both and stores the result set in its internal query cache
    Employee employeeFirst = (Employee) session.executeQuery(query);

Example 99-25 shows how to configure the `ReadQuery` to stop caching its results. The next time the query is executed, TopLink does not use the query cache. Instead, the query accesses the data source.

Example 99-25 Configuring a ReadQuery to Stop Caching Its Query Results

    // Disable query caching
    query.doNotCacheQueryResults();

    // The ReadQuery does not use the query cahce and instead accesses the database
    Employee employee = (Employee) session.executeQuery(query);

Alternativley, you can clear the query's internal cache using `ReadQuery` method `clearQueryResults` passing in your session. This clears the currently cached results and ensures that the next query execution reads from the database.

## Configuring Cache Expiration at the Query Level

You can configure a `ReadQuery` with a `CacheInvalidationPolicy`.

If you configure a query to cache results in its own internal cache (see "Caching Results in a ReadQuery"), the cache invalidation policy allows the cached query result set to expire, based on a time-to-live or daily-expiry. This invalidation time is calculated from the time of the query execution that cached the query result set for the specific set of query parameters.

Example 99-26 shows how to configure a `ReadQuery` so that a `TimeToLiveCacheInvalidationPolicy` is applied to all the objects returned by the query and cached in the query's internal cache.

Example 99-26 Configuring a CacheInvalidationPolicy on a ReadQuery for the Query's Internal Cache

    // The TimeToLiveCacheInvalidationPolicy applies to all objects returned by the query and
    // cached in the query's internal cache
    readQuery.setQueryResultsCachePolicy(
        new QueryResultsCachePolicy(new TimeToLiveCacheInvalidationPolicy(1000))
    );

For more information, see "Cache Invalidation".