The purpose of the IDataCacheProvider is to provide caching functionality to the application which allows it to reduce the workload of the GC by re-use of objects, and to decouple the amount of data which can be loaded into the application from the actual size of the java heap. The primary target of the implementation is to provide this functionality for arrays of primitive values (byte, short, int, long, float, double). Specialized access methods exist to handle primitive types, while a set of generic methods allows concrete implementations of the cache to provide such functionality for arbitrary classes.
The cache functionality is accessed through the DataCacheProviderFactory which returns a singleton of an implementation registered via the "com.agfa.pacs.core.shared.DataCacheProvider" extension point.
IDataCacheProvider provides three different types of functionality accessible through corresponding sets of methods:
 
for(i=0;i!=1000;i++)
{
	byte mem[]=allocBytes(i);
	// do something
    free(mem);
   }
					    
for(i=0;i!=1000;i++)
{
    byte mem[]=allocateBytes(1000);
   // do something
   free(mem);
}
					
private byte[] createContent()
{
    byte myArray[]=DataCacheProviderFactory.getCache().allocBytes(size);
    //... fill myArray here
    return myArray;
}
//do once:
String id=DataCacheProviderFactory.getCache().createID();
//
// do everytime myArray's content is used:
// ...
byte myArray[]=DataCacheProviderFactory.getCache().getContentBytes(id);
if (myArray==null) // first time or cleared due to out of mem
{
    myArray=createContent();
}
// ... use myArray
DataCacheProviderFactory.getCache().putContentBytes(myArray, id);    // pass to cache again.
					addPersistentXXX(), referencePersistentXXX(), releaseReference(), releaseModifiedReference() provide access to persistent cache functionality. Depending on the configuration data may be written to a persistent storage (disk) and persist between application sessions. addPersistentXXX(Object, id) puts an object (or more specifically it's content) under cache control.
Successive calls to referencePersistentXXX(id) return references to the object currently containing the content associated with the given ID (may be the same object put into cache using addPersistentXXX() or a different one if the data was forced to disk in between).
Depending on the implementation, the cache may keep a reference count to objects referenced by the application, thus requiring to call a final releaseReference(id) for each referencePersistentXXX(). releaseModifiedReference(id) marks an object as dirty and forces update of data on disk (if disk used). Using the persistent cache functionality:
byte myArray[]=DataCacheFectory.getCache().allocateByteArray(size);
//... fill myArray with some content
id=DataCacheProviderFactory.getCache().createID();
DataCacheProviderFactory.getCache().addPersistentBytes(myArray, id);
//... now the content of myArray may be transferred to disk asynchronously
//... use myArray
byte myArray[]=DataCacheProviderFactory.getCache().referencePersistentBytes(id);
//... use myArray, other threads/methods may also access it.
//... use release to release reference (use the releaseModified version if myData has been modified).
DataCacheProviderFactory.getCache().releaseReference(id);
//... delete from permanent cache if not used any more
DataCacheProviderFactory.getCache().remove(id);
					Each item put under control of the cache can be associated with a specific priority (0..MAX_ITEM_PRIORITY) which influences the probability of this item being re-used by the cache as part of it's pool functionality. Priority 0 will result in an early re-use, MAX_ITEM_PRIORITY leads to a longer life-time. Items with the same prioirty should be re-used following a LRU scheme.
Each personalized or persistent data item within the cache is identified using a unique CacheID. The CacheID should be created using the createID() method for session persistent or personalized objects or createID(group, item, persistenceType) for objects which are intended to persist across application starts. The group/item pair has to allow identification of a specific item throughout multiple runs of the application. This is vital so the object can be reaccessed by this name/group during the next run of an application. The three persistence types are:
To support the Java heap management and the internal memory management of the cache an additional mechanism is provided through the MemoryAlertHandler to allow arbitrary parts of the application to participate in handling memory shortages. The MemoryAlertHandler allows to register IMemoryAlertListeners which are notified if memory is running low and heap space has to be freed to allow the cache to perform a requested allocation operation. A listener registered with addMemoryAlertListener is notified if an allocation fails or is expected to fail due to low heap memory. It should try to free internally used memory to allow the allocation to be completed. A listener registered with addPersistentMemoryAlertListener is notified whenever disk space is running low, and persistent data has to be removed from disk. In case no disk is used for caching and all persistent data remains in the heap, the persistentMemoryAlert listeners are also notified if the heap funs low and memoryAlertListeners were not able to free sufficient memory.