Oracle TopLink Cache Invalidation |
How-To Document
January 2006
After reading this How-To document, you will be able to:
Understand the purpose of TopLink cache invalidation.
Configure your TopLink application to use cache invalidation.
Label objects as invalid in the TopLink cache.
The following conventions are used in this document:
<ORACLE_HOME> – the directory in which you installed TopLink.
TopLink maintains identity maps of objects to ensure identity is maintained throughout a TopLink application and to provide some caching functionality. In previous versions of TopLink, elements in the identity maps were considered to have accurate data until they were specifically refreshed from the database. With the new cache invalidation feature, items can be set as invalid in the cache. Invalid objects in the cache will require a refresh from the database before their data is made available to the application.
Objects can become invalid in the following ways:
They can be set to expire at a specific time every day.
They can be set to expire a preset amount of time after they are read.
They can be set as invalid through API.
Cache invalidation can be used in one of the following ways:
Set a cache invalidation policy on a descriptor (see "Setting Objects to Expire").
Call API to invalidate objects (see "Invalidating Objects with API").
The following examples illustrate the two ways to use TopLink cache invalidation:
Objects are set to expire through their descriptors. A cache invalidation policy can be set on each descriptor. The following cache invalidation policies are available:
NoExpiryCacheInvalidationPolicy (default) – Objects are only treated as invalid when API is called to invalidate them.
TimeToLiveCacheInvalidationPolicy – Objects expire a specified number of milliseconds after they are read.
DailyCacheInvalidationPolicy – Objects expire at a given time each day.
No code is required to use NoExpiryCacheInvalidationPolicy.
To use a TimeToLiveCacheInvalidationPolicy, specify the following code in a descriptor amendment method:
// Objects will expire 100000 milliseconds after they are read. TimeToLiveCacheInvalidationPolicy expiryPolicy = new TimeToLiveCacheInvalidationPolicy(100000); descriptor.setCacheInvalidationPolicy(expiryPolicy);
To use a DailyCacheInvalidationPolicy, specify the following code in a descriptor amendment method:
// Objects will expire at 12 noon every day DailyCacheInvalidationPolicy expiryPolicy = new DailyCacheInvalidationPolicy(12, 0, 0, 0); descriptor.setCacheInvalidationPolicy(expiryPolicy);
API is available to invalidate objects in the cache. This API can be accessed through the Session's identity map manager. API is available to do the following:
Invalidate an individual object.
Invalidate a collection of objects.
Invalidate a class.
The API is all very similar. Here is an example of how to call the API to invalidate an object.
ObjectA aObject = (ObjectA)getSession().readObject(ObjectA.class); ...getSession().getIdentityMapAccessor().invalidateObject(aObject);
In general, the behavior of invalidated objects can be summarized as:
Invalidated objects are still held in the TopLink cache.
Invalidated objects will still be used to maintain identity.
When a read query is run that accesses an invalidated object, it will be treated as though it requires a refresh from the database. This means it will not be returned from queries which only check the cache and it will be refreshed from the database for other queries.
Expiry times are calculated based on the time an object was read. These read times are refreshed when an object is read from the database and several other times when TopLink is able to confirm the data contained in an object is up to date.
The main classes for this feature are in the oracle.toplink.descriptors.invalidation package.
The other important classes for this feature are oracle.toplink.sessions.IdentityMapAccessor and oracle.toplink.publicinterface.Descriptor.
Oracle TopLink, 10g Release 3 (10.1.3)
The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.
If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software—Restricted Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.
Oracle, JD Edwards and PeopleSoft are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.
Alpha and Beta Draft documentation are considered to be in prerelease status. This documentation is intended for demonstration and preliminary use only. We expect that you may encounter some errors, ranging from typographical errors to data inaccuracies. This documentation is subject to change without notice, and it may not be specific to the hardware on which you are using the software. Please be advised that prerelease documentation in not warranted in any manner, for any purpose, and we will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.