org.apache.derby.impl.services.cache
Class CachedItem

java.lang.Object
  extended by org.apache.derby.impl.services.cache.CachedItem

final class CachedItem
extends java.lang.Object

A generic class to represent the cache related infomation of a cached object (Cacheable).

        The relationship between isValid and settingIdentity can be explain by the
        following life cycle of a cached item.

        Stage              1    2       3
        ----------------------
        isValid         F       T       T       
        settingIdentity X       T       F

        In Stage 1, the CachedItem is created but it is invalid and has an entry
        that is just a holder object with no identity.

        In Stage 2, the identity has been set and the item is being created or
        being faulted into the cache.

        In Stage 3, the item found in the CachedItem entry
        

Remove is set if this item is being removed out of existance, not just being evicted from the cache. When the last referece to it release it from the cache, it will be removed.
RecentlyUsed is set whenever this item is accessed (via a keep() call). It is reset by the clockHand as it sweeps around the cache looking for victims to evict.

MT - must be MT-safe and work with cache manager. Every method that access (set or get) instance variables is synchronized on the cached item object. The following method waits so it should not be called by the cache manager inside a sync block: clean(), waitFor(), create(), remove(). (RESOLVE: need to move these from the cache manager to here)

See Also:
org.apache.derby.impl.services.cache, Cacheable

Field Summary
private  Cacheable entry
          The Cacheable object being represented.
private  int keepCount
          The current keep count on the entry.
private  boolean recentlyUsed_
           
private  boolean removeOk_
           
private  boolean removeRequested_
           
private  boolean settingIdentity_
           
private  boolean valid_
           
 
Constructor Summary
CachedItem()
          Create a CachedItem in the not valid state.
 
Method Summary
 void clean(boolean forRemove)
          Clean the cached object MT -
The wait will not release the lock on the cache manager, so the cache manager should not waitfor clean inside a sync block or the whole cache will freeze
 Cacheable getEntry()
          Get the cached object.
 boolean isKept()
          Is the cached object kept?
 boolean isValid()
          Does the cached object have a valid identity.
 void keepAfterSearch()
          Keep the cached object after a search.
 void keepForClean()
           
 void keepForCreate()
           
 void notifyRemover()
           
 boolean recentlyUsed()
          Has the cached object been referenced (kept) since the last sweep of the clock hand?
 void remove(boolean removeNow)
           
 void setRemoveState()
          Set the state of the to-be removed flag.
 void settingIdentityComplete()
           
 void setUsed(boolean flag)
          The clock hand has swept past this entry.
 void setValidState(boolean flag)
          Set the valid state of the cached object.
 Cacheable takeOnIdentity(CacheManager cm, CacheableFactory holderFactory, java.lang.Object key, boolean forCreate, java.lang.Object createParameter)
          Make entry (the Cacheable) take on a new identity.
 boolean unkeep()
          Unkeep the cached object.
 void unkeepForCreate()
           
 Cacheable use()
          Allow use of the cacheable entry.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

valid_

private boolean valid_

removeRequested_

private boolean removeRequested_

settingIdentity_

private boolean settingIdentity_

removeOk_

private boolean removeOk_

recentlyUsed_

private boolean recentlyUsed_

keepCount

private int keepCount
The current keep count on the entry.
MT - single thread required : synchronization provided by cache manager.


entry

private Cacheable entry
The Cacheable object being represented.
Mutable - content dynamic

Constructor Detail

CachedItem

public CachedItem()
Create a CachedItem in the not valid state.

Method Detail

keepAfterSearch

public void keepAfterSearch()
Keep the cached object after a search.


keepForCreate

public void keepForCreate()

unkeepForCreate

public void unkeepForCreate()

keepForClean

public void keepForClean()

unkeep

public boolean unkeep()
Unkeep the cached object.

MT - not synchronized, only modified single threaded by the cache manager

Returns:
if the object is still kept after this call.

isKept

public final boolean isKept()
Is the cached object kept?

MT - not synchronized, only accessed single threaded by the cache manager


clean

public void clean(boolean forRemove)
           throws StandardException
Clean the cached object

MT -
The wait will not release the lock on the cache manager, so the cache manager should not waitfor clean inside a sync block or the whole cache will freeze

Parameters:
forRemove - if true, get rid of the backend persistent store object
Throws:
StandardException - error thrown while writing cacheable object to disk

setRemoveState

public void setRemoveState()
Set the state of the to-be removed flag.


isValid

public final boolean isValid()
Does the cached object have a valid identity.


setValidState

public void setValidState(boolean flag)
Set the valid state of the cached object.


getEntry

public Cacheable getEntry()
Get the cached object.


takeOnIdentity

public Cacheable takeOnIdentity(CacheManager cm,
                                CacheableFactory holderFactory,
                                java.lang.Object key,
                                boolean forCreate,
                                java.lang.Object createParameter)
                         throws StandardException
Make entry (the Cacheable) take on a new identity.

Throws:
StandardException

settingIdentityComplete

public void settingIdentityComplete()

use

public Cacheable use()
              throws StandardException
Allow use of the cacheable entry.

Throws:
StandardException

remove

public void remove(boolean removeNow)
            throws StandardException
Throws:
StandardException

notifyRemover

public void notifyRemover()

setUsed

public void setUsed(boolean flag)
The clock hand has swept past this entry.


recentlyUsed

public boolean recentlyUsed()
Has the cached object been referenced (kept) since the last sweep of the clock hand?


Built on Thu 2012-03-29 21:53:33+0000, from revision ???

Apache Derby V10.6 Internals - Copyright © 2004,2007 The Apache Software Foundation. All Rights Reserved.