Configuring Cache Refreshing

By default, TopLink caches objects read from a data source (see "Understanding the Cache"). Subsequent queries for these objects will access the cache and thus improve performance by reducing data source access and avoiding the cost of rebuilding object's and their relationships. Even if a query, such as a read-all query, accesses the data source, if the objects corresponding to the records returned are in the cache, TopLink will use the cache objects.

This can lead to stale data in the application. Although using an appropriate locking policy (see "Configuring Locking Policy") is the only way to ensure that stale or conflicting data does not get committed to the data source, sometimes certain data in the application changes so frequently that it is desirable to always refresh the data, instead of only refreshing the data when a conflict is detected.

You can specify how the TopLink runtime handles cache refreshing for all queries on a descriptor's reference class.

Table 28-4 summarizes which descriptors support query cache refresh configuration.

Table 28-10 Descriptor Support for Query Cache Refresh

Descriptor	Using TopLink Workbench	Using Java
Relational Descriptors^Foot 1
Object-Relational Descriptors
EIS Descriptor^Foot 2
XML Descriptors

^Footnote 1Relational class descriptors only (see "Relational Class Descriptors").

^Footnote 2EIS root descriptors only (see "EIS Root Descriptors").

Configuring descriptor-level cache refresh may affect performance. As an alternative, consider configuring the following:

cache refresh on a query-by-query basis (see "Refreshing the Cache")
cache expiration (see "Configuring Cache Expiration at the Descriptor Level")
isolated caching (see "Cache Isolation")

For more information, see "Cache Optimization"

Using TopLink Workbench

To configure how TopLink refreshes the cache for queries to this descriptor, use this procedure:

Select a descriptor in the Navigator. Its properties appear in the Editor.
Click the Queries tab. The Queries tab appears.
Click the Settings tab. The Settings tab appears.

Figure 28-21 Descriptor Queries Settings Tab, Cache Refreshing Options

Description of "Figure 28-21 Descriptor Queries Settings Tab, Cache Refreshing Options"

Field	Description
Always Refresh	Refreshes the cache on all queries. Avoids stale data by ensuring that any query that accesses the data source will refresh the resulting objects in the cache. This has no effect on queries that get a cache hit and never access the data source, such as read-object primary key queries or in-memory queries. Configuring descriptor level cache refresh may affect performance. As an alternative, consider configuring: cache refresh on a query-by-query basis (see "Refreshing the Cache") cache expiration (see "Configuring Cache Expiration at the Descriptor Level") isolated caching (see "Cache Isolation")
Only Refresh If Newer Version	Refreshes the cache only if the object in the database is newer than the object in the cache (as determined by the Optimistic Locking field). See "Configuring Locking Policy" for more information. Improves performance by avoiding unnecessary refreshing of an object if its version matches the data source version. This option does not cause refreshing on its own: you must use it in combination with Always Refresh, query refreshing (see "Refreshing the Cache"), or cache expiration (see "Configuring Cache Expiration at the Descriptor Level").
Disable Cache Hits	When selected, TopLink bypasses the cache and goes to the database for read object queries based on primary key. Using this option in conjunction with Always Refresh ensures that TopLink always goes to the database. This option ensures that all queries including read-object primary key queries will always access the data source. This option does not cause refreshing on its own: you must use it in combination with Always Refresh. This option can cause a serious performance issue: avoid whenever possible.

Field

Description

Always Refresh

Refreshes the cache on all queries.

Avoids stale data by ensuring that any query that accesses the data source will refresh the resulting objects in the cache. This has no effect on queries that get a cache hit and never access the data source, such as read-object primary key queries or in-memory queries.

Configuring descriptor level cache refresh may affect performance. As an alternative, consider configuring:

cache refresh on a query-by-query basis (see "Refreshing the Cache")
cache expiration (see "Configuring Cache Expiration at the Descriptor Level")
isolated caching (see "Cache Isolation")

Only Refresh If Newer Version

Refreshes the cache only if the object in the database is newer than the object in the cache (as determined by the Optimistic Locking field). See "Configuring Locking Policy" for more information.

Improves performance by avoiding unnecessary refreshing of an object if its version matches the data source version. This option does not cause refreshing on its own: you must use it in combination with Always Refresh, query refreshing (see "Refreshing the Cache"), or cache expiration (see "Configuring Cache Expiration at the Descriptor Level").

Disable Cache Hits

When selected, TopLink bypasses the cache and goes to the database for read object queries based on primary key. Using this option in conjunction with Always Refresh ensures that TopLink always goes to the database.

This option ensures that all queries including read-object primary key queries will always access the data source. This option does not cause refreshing on its own: you must use it in combination with Always Refresh.

This option can cause a serious performance issue: avoid whenever possible.

Caution:

Use the Always Refresh and Disable Cache Hits properties with caution as they may lead to poor performance. As an alternative, consider configuring cache refresh on a query-by-query basis (see "Refreshing the Cache") or configuring cache expiration (see "Configuring Cache Expiration at the Descriptor Level"). For more information about cache performance, see "Cache Optimization".

Using Java

Configure cache refresh options using the following ClassDescriptor methods:

setShouldAlwaysRefreshCache
setShouldAlwaysRefreshCacheOnRemote
setShouldDisableCacheHits
setShouldDisableCacheHitsOnRemote
setShouldOnlyRefreshCacheIfNewerVersion

Use these methods in a descriptor amendment method (see "Configuring Amendment Methods") as Example 28-2 illustrates.

Example 28-2 Configuring Remote Refreshing

public void addToDescriptor(ClassDescriptor descriptor) {
    descriptor.setShouldRefreshCacheOnRemote(true);
    descriptor.setShouldDisableCacheHitsOnRemote(true);
}