Working with Identity Maps

OracleAS TopLink uses identity maps to cache objects for performance and maintain object identity. The OracleAS TopLink Mapping Workbench provides the following identity map types on the Identity tab (see Figure 4–19):

Table 4-2 Identity Maps

Identity Map	Description
Full identity map	Provides full caching and guaranteed identity. Caches all objects and does not remove them. This method may be memory intensive when many objects are read. Do not use on batch type operations.
Soft cache weak identity map (default with JDK 1.2, available since JDK 1.2)	Similar to the weak identity map except that it maintains a most-frequently-used sub-cache. The size of the sub-cache is proportional to the size of the identity map as specified by descriptor's `setIdentityMapSize()` method. The sub-cache uses soft references to ensure that these objects are garbage-collected only if the system is low on memory.
Hard cache weak identity map (available since JDK 1.2)	Identical to the soft cache weak identity map except that it uses hard references in the sub-cache. Use this identity map if soft references do not behave properly on your platform.
Weak identity map (available since JDK 1.2)	Similar to the full identity map except that the map holds the objects using weak references. This method allows full garbage collection and provides full caching and guaranteed identity.
Cache identity map	Furnishes caching and identity, but does not guarantee identity. A cache identity map maintains a fixed number of objects specified by the application. Objects are removed from the cache on a least-recently-used basis. This method allows object identity for the most commonly used objects.
No identity map	Does not preserve object identity and does not cache objects.

Identity Map Size

The default identity map size is 100.

For the cache identity map policy, the size indicates the maximum number of objects stored in the identity map.
For the full identify map policy, the size determines the starting size of the map.
For the soft/hard cache weak identity map, the most recently used sub-cache is proportional to the size.

Design Guidelines

Use the following guidelines when employing an identity map:

If using a Java 2-compatible Virtual Machine (VM), objects with a long lifespan, and object identity are important, use a SoftCacheWeakIdentityMap or HardCacheWeakIdentityMap policy.
If using a Java 2-compatible VM, and object identity is important but caching is not, use a WeakIdentityMap policy.
If an object has a long lifespan or requires frequent access, or is important, use a FullIdentityMap policy.
If an object has a short lifespan or requires frequent access, and identity is not important, use a CacheIdentityMap policy.
If objects are discarded immediately after being read from the database, such as in a batch operation, use a NoIdentityMap policy.

Using Object Identity

Note:

The NoIdentityMap does not preserve object identity.

In a Java application, object identity is preserved if each object in memory is represented by one, and only one, object instance. Multiple retrievals of the same object return references to the same object instance — not multiple copies of the same object.

Maintaining object identity is extremely important when the application's object model contains circular references between objects. You must ensure that two are referencing each other directly, rather than copies of each other. Object identity is important when multiple parts of the application may be modifying the same object simultaneously.

Turn identity off when object identity is not important (for example, for read-only objects).

Caching Objects

Identity maps maintain client-side object caches, which increases application performance by minimizing the number of database reads.

When the cache fills up, OracleAS TopLink cleans up the cache based on the identity map policy.