BoundedLibraryObjectCache (ecmsdk-api 3.4.0 API)

java.lang.Object
- oracle.ifs.common.Cache
- - oracle.ifs.common.BoundedCache
  - - oracle.ifs.common.LibraryObjectCache
    - - oracle.ifs.server.BoundedLibraryObjectCache

```
public final class BoundedLibraryObjectCache
extends LibraryObjectCache
```
A BoundedLibraryObjectCache is a cache that holds both S_LibraryObjects and LibraryObjects on behalf of a single iFS session. It is lossely bounded to hold a limited number of items. The upper bound is maintained by an efficient but non-exact algorithm that removes LRU entries.
Cached LibraryObjects provide an addition feature in iFS: they represent the set of objects on which the session has implicit registration for iFS events. Because of this, the objects that are candidates for removal from the cache (due to not being recently used) must be "slowly" removed from the cache. This is accomplished by demoting a cache entry from being a "hard reference" to a "soft reference", and making use of the java.lang.ref.SoftReference class to determine when it is safe to completely remove the cache entry from the cache.
Note: this class requires JRE 1.2.2 or higher.

Version:

1.0

Author:

Dave Long

(Unpublished)

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`m_AccessSequence` The access sequence.
`protected int`	`m_Capacity` Target max cache capacity; also used as initial Capacity in HashMap constructor.
`protected int`	`m_DemoteCount` The number of cache entry demotions.
`protected int`	`m_EmergencyCapacityTrigger` capacity at which an "emergency" purge is performed.
`protected boolean`	`m_EmergencyPurgeRequested` Emergency cache purge requested.
`protected int`	`m_HardReferenceCount` The current hard-reference cache count.
`protected int`	`m_HitCount` The number of cache hits.
`protected HashMap`	`m_Items` The cache items.
`protected int`	`m_LockCount` The number of locked cache puts.
`protected int`	`m_MissCount` The number of cache misses.
`protected int`	`m_NormalCapacityTrigger` capacity at which a "normal" purge is posted.
`protected boolean`	`m_NormalPurgeRequested` Normal cache purge requested.
`protected int`	`m_PromoteCount` The number of cache entry promotions.
`protected int`	`m_PurgeCount` The number of cache removes.
`protected int`	`m_PurgeCycleCount` Total number of purge cycles performed
`protected long`	`m_PurgeCycleTime` Total elapsed time (in ms) of the purge cycles performed.
`protected boolean`	`m_PurgeInProgress` Cache purge in progress.
`protected int`	`m_PurgeTarget` Number of items desired in the cache after a purge operation.
`protected int`	`m_PutCount` The number of cache puts.
`protected ReferenceQueue`	`m_ReferenceQueue` The SoftReference queue
`protected int`	`m_RemoveCount` The number of cache removes.
`protected int`	`m_SequenceAtPreviousPurge` Cache purge in progress.
`protected S_LibrarySession`	`m_Session` The server-side session using this cache
`protected int`	`m_UrgentCapacityTrigger` capacity at which an "urgent" purge is posted.
`protected boolean`	`m_UrgentPurgeRequested` Urgent cache purge requested.
`protected static int`	`MAX_SEQUENCE` The maximum access sequence
`protected static IfsLogger`	`s_Logger` This logger instance specific to this class.
`protected static int`	`SEQUENCE_NORMALIZATION_FACTOR` The normalization factor to be used in case the access sequence wraps past MAX_SEQUENCE.

Fields inherited from class oracle.ifs.common.Cache
m_Configuration

Constructor Summary

Constructors
Constructor and Description
`BoundedLibraryObjectCache(BoundedCacheConfiguration configuration, S_LibrarySession session)` Construct a BoundedLibraryObjectCache

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`dispose()` Disposes this cache.
`protected void`	`entryDemoted()`
`protected void`	`entryPromoted()`
`Object`	`find(Object id)` Gets an item from this cache.
`LibraryObject`	`findLibraryObject(Object itemKey, LibrarySession session)` Gets an item from this cache.
`S_LibraryObject`	`findSLibraryObject(Object itemKey)` Gets an item from this cache.
`CachePerformance`	`getCachePerformance()` Gets the performance information for this cache.
`Enumeration`	`getElements()` Gets an Enumeration of the S_LibraryObjects in this cache.
`protected HashMap`	`getItemsHashMap()` Return cache item map, or null if it has been disposed
`protected HashMap`	`getItemsHashMap(boolean required)` Return cache item map, or throw if we are disposed
`Enumeration`	`getLibraryObjectEnumeration()` Gets an Enumeration of the LibraryObjects in this cache.
`protected int`	`getNextSequence()` Return next access sequence
`Enumeration`	`getSLibraryObjectEnumeration()` Gets an Enumeration of the S_LibraryObjects in this cache.
`boolean`	`isTraced(int channel, int level)` Gets whether tracing is enabled for the specified channel and level.
`void`	`lock(Object itemKey, Object value)` Locks an item in this cache.
`void`	`markEntriesAsUntrusted()` Mark all PO entries as untrusted.
`void`	`markEntryAsUntrusted(Object itemKey)` Mark an entry as untrusted.
`void`	`markFreeCancelled(Long id)` Respond to a rolledback FREE event.
`void`	`markFreeInitiated(Long id)` Removes an item from this cache, and mark it pending until the current transaction is committed.
`void`	`performNormalPurgeIfNeeded()` Purge Cache if a request for "normal" purge is indicated
`void`	`performUrgentPurgeIfNeeded()` Purge Cache if a request for "urgent" purge is indicated
`void`	`purgeEntry(Long id)` Purges an item from this cache.
`void`	`put(Object itemKey, Object value)` Puts an item in this cache.
`void`	`putLibraryObject(Object itemKey, LibraryObject value)` Puts an item in this cache.
`void`	`remove(Object itemKey)` Removes an item from this cache, in reaction to a committed FREE event, or a rolledbcak CREATE event.
`void`	`removeLibraryObject(Object itemKey)` Removes an item from this cache.
`void`	`reset()` Resets this cache.
`void`	`resetCachePerformance()` Resets the performance information for this cache.
`void`	`setCacheConfiguration(CacheConfiguration configuration)` Alters the configuration of this cache.
`protected void`	`setItemsHashMap(int size)` Initializes the cache item map,
`void`	`trace(int channel, int level, String payload)` Issues a trace request to the trace logger.

Methods inherited from class oracle.ifs.common.Cache
getCacheConfiguration

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MAX_SEQUENCE
```
protected static int MAX_SEQUENCE
```
    The maximum access sequence
    
    (Unpublished)
  - SEQUENCE_NORMALIZATION_FACTOR
```
protected static int SEQUENCE_NORMALIZATION_FACTOR
```
    The normalization factor to be used in case the access sequence wraps past MAX_SEQUENCE.
    
    (Unpublished)
  - m_Session
```
protected S_LibrarySession m_Session
```
    The server-side session using this cache
    
    (Unpublished)
  - m_Items
```
protected HashMap m_Items
```
    The cache items.
    
    (Unpublished)
  - m_ReferenceQueue
```
protected ReferenceQueue m_ReferenceQueue
```
    The SoftReference queue
    
    (Unpublished)
  - m_Capacity
```
protected int m_Capacity
```
    Target max cache capacity; also used as initial Capacity in HashMap constructor.
    
    (Unpublished)
  - m_NormalCapacityTrigger
```
protected int m_NormalCapacityTrigger
```
    capacity at which a "normal" purge is posted.
    
    (Unpublished)
  - m_UrgentCapacityTrigger
```
protected int m_UrgentCapacityTrigger
```
    capacity at which an "urgent" purge is posted.
    
    (Unpublished)
  - m_EmergencyCapacityTrigger
```
protected int m_EmergencyCapacityTrigger
```
    capacity at which an "emergency" purge is performed.
    
    (Unpublished)
  - m_PurgeTarget
```
protected int m_PurgeTarget
```
    Number of items desired in the cache after a purge operation.
    
    (Unpublished)
  - m_AccessSequence
```
protected int m_AccessSequence
```
    The access sequence.
    
    (Unpublished)
  - m_HardReferenceCount
```
protected int m_HardReferenceCount
```
    The current hard-reference cache count.
    
    (Unpublished)
  - m_SequenceAtPreviousPurge
```
protected int m_SequenceAtPreviousPurge
```
    Cache purge in progress.
    
    (Unpublished)
  - m_PurgeCycleCount
```
protected int m_PurgeCycleCount
```
    Total number of purge cycles performed
    
    (Unpublished)
  - m_PurgeCycleTime
```
protected long m_PurgeCycleTime
```
    Total elapsed time (in ms) of the purge cycles performed. Used to calculate an average purge cycle time.
    
    (Unpublished)
  - m_PurgeInProgress
```
protected boolean m_PurgeInProgress
```
    Cache purge in progress.
    
    (Unpublished)
  - m_NormalPurgeRequested
```
protected boolean m_NormalPurgeRequested
```
    Normal cache purge requested.
    
    (Unpublished)
  - m_UrgentPurgeRequested
```
protected boolean m_UrgentPurgeRequested
```
    Urgent cache purge requested.
    
    (Unpublished)
  - m_EmergencyPurgeRequested
```
protected boolean m_EmergencyPurgeRequested
```
    Emergency cache purge requested.
    
    (Unpublished)
  - m_HitCount
```
protected int m_HitCount
```
    The number of cache hits.
    
    (Unpublished)
  - m_MissCount
```
protected int m_MissCount
```
    The number of cache misses.
    
    (Unpublished)
  - m_PutCount
```
protected int m_PutCount
```
    The number of cache puts.
    
    (Unpublished)
  - m_LockCount
```
protected int m_LockCount
```
    The number of locked cache puts.
    
    (Unpublished)
  - m_RemoveCount
```
protected int m_RemoveCount
```
    The number of cache removes.
    
    (Unpublished)
  - m_PurgeCount
```
protected int m_PurgeCount
```
    The number of cache removes.
    
    (Unpublished)
  - m_DemoteCount
```
protected int m_DemoteCount
```
    The number of cache entry demotions.
    
    (Unpublished)
  - m_PromoteCount
```
protected int m_PromoteCount
```
    The number of cache entry promotions.
    
    (Unpublished)
  - s_Logger
```
protected static IfsLogger s_Logger
```
    This logger instance specific to this class.
- Constructor Detail
  - BoundedLibraryObjectCache
```
public BoundedLibraryObjectCache(BoundedCacheConfiguration configuration,
                                 S_LibrarySession session)
```
    Construct a BoundedLibraryObjectCache
    
    Parameters:
    
    configuration - the configuration paramaters for the new cache
    
    (Unpublished)
- Method Detail
  - reset
```
public void reset()
```
    Resets this cache.
    This causes the cache to be emptied and its performance information to be reset. This is invoked as part of construction, providing initialization.
    
    Overrides:
    
    reset in class Cache
    
    (Unpublished)
  - setCacheConfiguration
```
public final void setCacheConfiguration(CacheConfiguration configuration)
                                 throws IfsException
```
    Alters the configuration of this cache.
    The following cache configuration parameters can be changed using this method:
    - Capacity
    - Normal capacity trigger
    - Urgent capacity trigger
    - Emergency capacity trigger
    - Purge target
    All other cache configuration parameters specified in the CacheConfiguration are ignored.
    Specified by:
    
    setCacheConfiguration in class Cache
    
    Parameters:
    
    configuration - the configuration parameters; must be a BoundedCacheConfiguration
    
    Throws:
    
    IfsException - (IFS-10810) if the operation fails
    
    (Unpublished)
  - find
```
public final Object find(Object id)
                  throws IfsException
```
    Gets an item from this cache.
    
    Specified by:
    
    find in class Cache
    
    Parameters:
    
    id - the item id
    
    Returns:
    
    the item, or null if the item is not in this cache
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - remove
```
public final void remove(Object itemKey)
                  throws IfsException
```
    Removes an item from this cache, in reaction to a committed FREE event, or a rolledbcak CREATE event.
    
    Specified by:
    
    remove in class Cache
    
    Parameters:
    
    itemKey - the item id
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - markFreeInitiated
```
public final void markFreeInitiated(Long id)
                             throws IfsException
```
    Removes an item from this cache, and mark it pending until the current transaction is committed.
    
    Specified by:
    
    markFreeInitiated in class LibraryObjectCache
    
    Parameters:
    
    id - the item ID
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - markFreeCancelled
```
public void markFreeCancelled(Long id)
                       throws IfsException
```
    Respond to a rolledback FREE event. If this entry is still in the cache, clear the "Free Pending" indicator
    
    Specified by:
    
    markFreeCancelled in class LibraryObjectCache
    
    Parameters:
    
    id - the item ID
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - put
```
public final void put(Object itemKey,
                      Object value)
               throws IfsException
```
    Puts an item in this cache.
    
    Specified by:
    
    put in class Cache
    
    Parameters:
    
    itemKey - the item id
    
    value - the item
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - lock
```
public final void lock(Object itemKey,
                       Object value)
                throws IfsException
```
    Locks an item in this cache.
    
    Specified by:
    
    lock in class BoundedCache
    
    Parameters:
    
    itemKey - the item id
    
    value - the item
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - findSLibraryObject
```
public final S_LibraryObject findSLibraryObject(Object itemKey)
                                         throws IfsException
```
    Gets an item from this cache.
    
    Parameters:
    
    itemKey - the item id
    
    Returns:
    
    the item, or null if the item is not in this cache
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - purgeEntry
```
public final void purgeEntry(Long id)
```
    Purges an item from this cache. This results in a similar condition as if remove() was invoked, with two significant differences:
    - The entry is already in a disposed state when this method is called; so there's that is to say that the state is the same as if dispose() were invoked explicitly; no need to explicitly dispose it.
    - The statistics count that is incremented is the Purge count, not the Remove count.
    This is called whenever a softreference to the S_LibraryObject is queued for GC, or when get() on the S_LibraryObject's SoftReference returns null (effectively meaning that the SoftReference has been queued)
    Parameters:
    
    id - the item id
    
    (Unpublished)
  - findLibraryObject
```
public final LibraryObject findLibraryObject(Object itemKey,
                                             LibrarySession session)
                                      throws IfsException
```
    Gets an item from this cache.
    
    Parameters:
    
    itemKey - the item id
    
    session - the bean-side session
    
    Returns:
    
    the item, or null if the item is not in this cache
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - removeLibraryObject
```
public final void removeLibraryObject(Object itemKey)
                               throws IfsException
```
    Removes an item from this cache.
    
    Parameters:
    
    itemKey - the item id
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - putLibraryObject
```
public final void putLibraryObject(Object itemKey,
                                   LibraryObject value)
                            throws IfsException
```
    Puts an item in this cache.
    
    Parameters:
    
    itemKey - the item id
    
    value - the item
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - markEntriesAsUntrusted
```
public void markEntriesAsUntrusted()
                            throws IfsException
```
    Mark all PO entries as untrusted. Called whenever session leaves admin mode, when a user is impersonated, or when an impersonation is cancelled.
    
    Specified by:
    
    markEntriesAsUntrusted in class LibraryObjectCache
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - markEntryAsUntrusted
```
public void markEntryAsUntrusted(Object itemKey)
                          throws IfsException
```
    Mark an entry as untrusted.
    Called by S_LibrarySession when a special event is posted.
    
    Specified by:
    
    markEntryAsUntrusted in class LibraryObjectCache
    
    Parameters:
    
    itemKey - the ID of the entry to not be trusted
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - entryPromoted
```
protected void entryPromoted()
```
  - entryDemoted
```
protected void entryDemoted()
```
  - performNormalPurgeIfNeeded
```
public final void performNormalPurgeIfNeeded()
```
    Purge Cache if a request for "normal" purge is indicated
    
    Specified by:
    
    performNormalPurgeIfNeeded in class BoundedCache
    
    (Unpublished)
  - performUrgentPurgeIfNeeded
```
public final void performUrgentPurgeIfNeeded()
```
    Purge Cache if a request for "urgent" purge is indicated
    
    Specified by:
    
    performUrgentPurgeIfNeeded in class BoundedCache
    
    (Unpublished)
  - getElements
```
public Enumeration getElements()
                        throws IfsException
```
    Gets an Enumeration of the S_LibraryObjects in this cache.
    
    Overrides:
    
    getElements in class Cache
    
    Returns:
    
    the enumeration of S_LibraryObjects
    
    Throws:
    
    IfsException - if operation fails
    
    (Unpublished)
  - getSLibraryObjectEnumeration
```
public Enumeration getSLibraryObjectEnumeration()
                                         throws IfsException
```
    Gets an Enumeration of the S_LibraryObjects in this cache.
    
    Returns:
    
    the enumeration of S_LibraryObjects
    
    Throws:
    
    IfsException - if operation fails
    
    (Unpublished)
  - getLibraryObjectEnumeration
```
public Enumeration getLibraryObjectEnumeration()
                                        throws IfsException
```
    Gets an Enumeration of the LibraryObjects in this cache.
    
    Returns:
    
    the enumeration of LibraryObjects
    
    Throws:
    
    IfsException - if operation fails
    
    (Unpublished)
  - getNextSequence
```
protected final int getNextSequence()
```
    Return next access sequence
    
    Returns:
    
    next access sequence
    
    (Unpublished)
  - getCachePerformance
```
public final CachePerformance getCachePerformance()
```
    Gets the performance information for this cache.
    
    Specified by:
    
    getCachePerformance in class Cache
    
    Returns:
    
    a cache performance object
    
    (Unpublished)
  - resetCachePerformance
```
public final void resetCachePerformance()
```
    Resets the performance information for this cache.
    
    Specified by:
    
    resetCachePerformance in class Cache
    
    (Unpublished)
  - dispose
```
public void dispose()
```
    Disposes this cache.
    After the cache is disposed, it is invalid to use this cache.
    
    Overrides:
    
    dispose in class Cache
    
    (Unpublished)
  - isTraced
```
public final boolean isTraced(int channel,
                              int level)
```
    Gets whether tracing is enabled for the specified channel and level. Intentionally doesn't throw an IfsException.
    
    Parameters:
    
    channel - the channel number
    
    level - the level
    
    Returns:
    
    whether tracing is enabled
    
    (Unpublished)
  - trace
```
public final void trace(int channel,
                        int level,
                        String payload)
```
    Issues a trace request to the trace logger.
    
    Parameters:
    
    channel - the channel number
    
    level - the level
    
    payload - a string containing any additional information to be placed in the trace log
    
    (Unpublished)
  - getItemsHashMap
```
protected HashMap getItemsHashMap()
```
    Return cache item map, or null if it has been disposed
    
    Returns:
    
    the cache item map
    
    (Unpublished)
  - getItemsHashMap
```
protected HashMap getItemsHashMap(boolean required)
                           throws IfsException
```
    Return cache item map, or throw if we are disposed
    
    Parameters:
    
    required - whether the returned map must not be null
    
    Returns:
    
    the cache item map
    
    Throws:
    
    IfsException - (IFS-21000) if required is true, and the map is null
    
    (Unpublished)
  - setItemsHashMap
```
protected void setItemsHashMap(int size)
```
    Initializes the cache item map,
    
    Parameters:
    
    size - the initial cache size

Class BoundedLibraryObjectCache

Field Summary

Fields inherited from class oracle.ifs.common.Cache

Constructor Summary

Method Summary

Methods inherited from class oracle.ifs.common.Cache

Methods inherited from class java.lang.Object

Field Detail

MAX_SEQUENCE

SEQUENCE_NORMALIZATION_FACTOR

m_Session

m_Items

m_ReferenceQueue

m_Capacity

m_NormalCapacityTrigger

m_UrgentCapacityTrigger

m_EmergencyCapacityTrigger

m_PurgeTarget

m_AccessSequence

m_HardReferenceCount

m_SequenceAtPreviousPurge

m_PurgeCycleCount

m_PurgeCycleTime

m_PurgeInProgress

m_NormalPurgeRequested

m_UrgentPurgeRequested

m_EmergencyPurgeRequested

m_HitCount

m_MissCount

m_PutCount

m_LockCount

m_RemoveCount

m_PurgeCount

m_DemoteCount

m_PromoteCount

s_Logger

Constructor Detail

BoundedLibraryObjectCache

Method Detail

reset

setCacheConfiguration

find

remove

markFreeInitiated

markFreeCancelled

put

lock

findSLibraryObject

purgeEntry

findLibraryObject

removeLibraryObject

putLibraryObject

markEntriesAsUntrusted

markEntryAsUntrusted

entryPromoted

entryDemoted

performNormalPurgeIfNeeded

performUrgentPurgeIfNeeded

getElements

getSLibraryObjectEnumeration

getLibraryObjectEnumeration

getNextSequence

getCachePerformance

resetCachePerformance

dispose

isTraced

trace

getItemsHashMap

getItemsHashMap

setItemsHashMap