Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.impl.services.cache.CacheEntry

Class representing an entry in the cache. It is used by ConcurrentCache. When a thread invokes any of the methods in this class, except lock(), it must first have called lock() to ensure exclusive access to the entry.

When no thread holds the lock on the entry, it must be in one of the following states:

Uninitialized: The entry object has just been constructed, but has not yet been initialized. In this state, isValid() returns false, whereas isKept() returns true in order to prevent removal of the entry until it has been initialized. When the entry is in this state, calls to lockWhenIdentityIsSet() will block until settingIdentityComplete() has been called.
Unkept: In this state, the entry object contains a reference to a Cacheable and the keep count is zero. isValid() returns true and isKept() returns false in this state. getCacheable() returns a non-null value.
Kept: Same as the unkept state, except that the keep count is positive and isKept() returns true.
Removed: The entry has been removed from the cache. In this state, isValid() and isKept() return false, and getCacheable() returns null. When an entry has entered the removed state, it cannot be transitioned back to any of the other states.

To prevent deadlocks, each thread should normally lock only one entry at a time. In some cases it is legitimate to hold the lock on two entries, for instance if an entry must be evicted to make room for a new entry. If this is the case, exactly one of the two entries must be in the uninitialized state, and the uninitialized entry must be locked before the lock on the other entry can be requested.

Modifier and Type	Field and Description
private Cacheable	cacheable The cached object.
private ReplacementPolicy.Callback	callback Callback object used to notify the replacement algorithm about events on the cached objects (like accesses and requests for removal).
private Condition	forRemove Condition variable used to notify a thread that it is allowed to remove the entry from the cache.
private int	keepCount How many threads are currently keeping this entry.
private final ReentrantLock	mutex Mutex which guards the internal state of the entry.
private Condition	settingIdentity Condition variable used to notify a thread that the setting of this entry's identity is complete.

Constructor Summary

Access	Constructor and Description
pack-priv	CacheEntry()

Method Summary

Modifier and Type	Method and Description
pack-priv void	free() Clear this entry and notify the replacement algorithm that the `Cacheable` can be reused.
pack-priv Cacheable	Returns: the cached object in this entry getCacheable() Return the cached object held by this entry.
pack-priv boolean	Returns: `true` if the object is kept isKept() Check whether or not this entry is kept.
pack-priv boolean	Returns: `true` if the entry holds a valid object isValid() Check whether this entry holds a valid object.
pack-priv void	keep(boolean if `true`, notify the entry's callback object that it has been accessed (normally because of calls to create, find or findCached); otherwise, don't notify the callback object accessed) Increase the keep count for this entry.
pack-priv void	lock() Block until the current thread is granted exclusive access to the entry.
pack-priv void	setCacheable(Cacheable a cacheable, or `null` if the entry is about to be removed c) Set the cached object held by this entry.
pack-priv void	setCallback(ReplacementPolicy.Callback the callback object cb) Set the callback object used to notify the replacement algorithm about actions performed on the cached object.
pack-priv void	settingIdentityComplete() Notify this entry that the initialization of its cacheable has been completed.
pack-priv void	unkeep() Decrement the keep count for this entry.
pack-priv void	unkeepForRemove() Unkeep the entry and wait until no other thread is keeping it.
pack-priv void	unlock() Give up exclusive access.
pack-priv void	waitUntilIdentityIsSet() Block until this entry's cacheable has been initialized (that is, until `settingIdentityComplete()` has been called on this object).

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

cacheable	back to summary
private Cacheable cacheable The cached object. If it is null, it means that the entry is invalid (either uninitialized or removed).

callback	back to summary
private ReplacementPolicy.Callback callback Callback object used to notify the replacement algorithm about events on the cached objects (like accesses and requests for removal).

forRemove	back to summary
private Condition forRemove Condition variable used to notify a thread that it is allowed to remove the entry from the cache. If it is null, there is no thread waiting for the entry to be unkept.

keepCount	back to summary
private int keepCount How many threads are currently keeping this entry.

mutex	back to summary
private final ReentrantLock mutex Mutex which guards the internal state of the entry.

settingIdentity back to summary

settingIdentity	back to summary
private Condition settingIdentity Condition variable used to notify a thread that the setting of this entry's identity is complete. This variable is non-null when the object is created, and will be set to null when the identity has been set. See Also `settingIdentityComplete()`

private Condition settingIdentity

Condition variable used to notify a thread that the setting of this entry's identity is complete. This variable is non-null when the object is created, and will be set to null when the identity has been set.

See Also: settingIdentityComplete()

Constructor Detail

CacheEntry	back to summary
pack-priv CacheEntry()

Method Detail

free	back to summary
pack-priv void free() Clear this entry and notify the replacement algorithm that the `Cacheable` can be reused.

getCacheable	back to summary
pack-priv Cacheable getCacheable() Return the cached object held by this entry. Returns:Cacheable the cached object in this entry

getCacheable

back to summary

pack-priv Cacheable getCacheable()

Return the cached object held by this entry.

Returns:Cacheable: the cached object in this entry

isKept back to summary

isKept	back to summary
pack-priv boolean isKept() Check whether or not this entry is kept. Returns:boolean `true` if the object is kept

pack-priv boolean isKept()

Check whether or not this entry is kept.

Returns:boolean: true if the object is kept

isValid back to summary

isValid	back to summary
pack-priv boolean isValid() Check whether this entry holds a valid object. That is, it must hold a non-null `Cacheable` and have completed setting its identity. Returns:boolean `true` if the entry holds a valid object

pack-priv boolean isValid()

Check whether this entry holds a valid object. That is, it must hold a non-null Cacheable and have completed setting its identity.

Returns:boolean: true if the entry holds a valid object

keep back to summary

keep	back to summary
pack-priv void keep(boolean accessed) Increase the keep count for this entry. An entry which is kept cannot be removed from the cache. Parameters accessed:boolean if `true`, notify the entry's callback object that it has been accessed (normally because of calls to create, find or findCached); otherwise, don't notify the callback object

pack-priv void keep(boolean accessed)

Increase the keep count for this entry. An entry which is kept cannot be removed from the cache.

Parameters

accessed:boolean: if true, notify the entry's callback object that it has been accessed (normally because of calls to create, find or findCached); otherwise, don't notify the callback object

lock	back to summary
pack-priv void lock() Block until the current thread is granted exclusive access to the entry.

setCacheable back to summary

setCacheable	back to summary
pack-priv void setCacheable(Cacheable c) Set the cached object held by this entry. Parameters c:Cacheable a cacheable, or `null` if the entry is about to be removed

pack-priv void setCacheable(Cacheable c)

Set the cached object held by this entry.

Parameters

c:Cacheable: a cacheable, or null if the entry is about to be removed

setCallback	back to summary
pack-priv void setCallback(ReplacementPolicy.Callback cb) Set the callback object used to notify the replacement algorithm about actions performed on the cached object. Parameters cb:ReplacementPolicy.Callback the callback object

setCallback

back to summary

pack-priv void setCallback(ReplacementPolicy.Callback cb)

Set the callback object used to notify the replacement algorithm about actions performed on the cached object.

Parameters

cb:ReplacementPolicy.Callback: the callback object

settingIdentityComplete	back to summary
pack-priv void settingIdentityComplete() Notify this entry that the initialization of its cacheable has been completed. This method should be called after `Cacheable.setIdentity()` or `Cacheable.createIdentity()` has been called.

unkeep	back to summary
pack-priv void unkeep() Decrement the keep count for this entry. An entry cannot be removed from the cache until its keep count is zero.

unkeepForRemove back to summary

unkeepForRemove	back to summary
pack-priv void unkeepForRemove() Unkeep the entry and wait until no other thread is keeping it. This method is used when a thread requests the removal of the entry. As defined by the contract of `CacheManager.remove()`, it is the responsibility of the caller to ensure that only a single thread executes this method on an object. See Also `org.apache.derby.iapi.services.cache.CacheManager#remove`

pack-priv void unkeepForRemove()

Unkeep the entry and wait until no other thread is keeping it. This method is used when a thread requests the removal of the entry. As defined by the contract of CacheManager.remove(), it is the responsibility of the caller to ensure that only a single thread executes this method on an object.

See Also: org.apache.derby.iapi.services.cache.CacheManager#remove

unlock	back to summary
pack-priv void unlock() Give up exclusive access.

waitUntilIdentityIsSet back to summary

waitUntilIdentityIsSet	back to summary
pack-priv void waitUntilIdentityIsSet() Block until this entry's cacheable has been initialized (that is, until `settingIdentityComplete()` has been called on this object). If the cacheable has been initialized before this method is called, it will return immediately. The entry must have been locked for exclusive access before this method is called. If the method needs to wait, it will release the lock and reobtain it when it wakes up again.

pack-priv void waitUntilIdentityIsSet()

Block until this entry's cacheable has been initialized (that is, until settingIdentityComplete() has been called on this object). If the cacheable has been initialized before this method is called, it will return immediately. The entry must have been locked for exclusive access before this method is called. If the method needs to wait, it will release the lock and reobtain it when it wakes up again.

pack-priv final Class CacheEntry

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail