org.hypergraphdb.cache
Class WeakRefAtomCache

java.lang.Object
  org.hypergraphdb.cache.WeakRefAtomCache

All Implemented Interfaces:

HGAtomCache

public class WeakRefAtomCache
extends java.lang.Object
implements HGAtomCache

This cache implementation interacts with the Java garbage collector, by using the java.lang.ref facilities, in order to implement its eviction policy. The eviction policy is the following: an atom is removed from the cache if and only if either (1) its runtime Java instance is garbage collected or (2) it is explicitly removed from the HyperGraph DB. Freezing an atom will keep it in the cache even when it's garbage collected, but not if it's removed from DB altogether.

The WeakRefAtomCache is a bit misleading: weak reference are in fact not used at all. Soft references are used when caching incidence sets and phantom references are used for atoms (@see org.hypergraphdb.handle.PhantomHandle).

Author:

Borislav Iordanov

Field Summary

static long

DEFAULT_PHANTOM_QUEUE_POLL_INTERVAL

Constructor Summary

WeakRefAtomCache()

Method Summary

HGLiveHandle	atomRead(HGPersistentHandle pHandle, java.lang.Object atom, byte flags) Inform the cache that an atom has just been read from persistent storage.
HGManagedLiveHandle	atomRead(HGPersistentHandle pHandle, java.lang.Object atom, byte flags, long retrievalCount, long lastAccessTime) Inform the cache that an atom with system-level attributes has been loaded.
void	atomRefresh(HGLiveHandle handle, java.lang.Object atom) Refresh a previously evicted atom.
void	close() Close the cache.
void	freeze(HGLiveHandle handle) Freezing an atom in the cache would prevent it from ever being removed.
HGLiveHandle	get(HGPersistentHandle pHandle) Retrieve an atom from the cache by its persistent handle.
HGLiveHandle	get(java.lang.Object atom) Retrieve the HGLiveHandle of a run-time atom instance.
HGCache<HGPersistentHandle,IncidenceSet>	getIncidenceCache() Return the incidence set cache.
boolean	isFrozen(HGLiveHandle handle) Find out whether a given atom is frozen in the cache.
void	remove(HGLiveHandle handle) Force a removal a given atom from the cache.
void	setHyperGraph(HyperGraph hg) Set the HyperGraph within which this cache is operating.
void	setIncidenceCache(HGCache<HGPersistentHandle,IncidenceSet> cache)
void	unfreeze(HGLiveHandle handle) Unfreezing a previously frozen atom makes it available for eviction.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_PHANTOM_QUEUE_POLL_INTERVAL

public static final long DEFAULT_PHANTOM_QUEUE_POLL_INTERVAL

See Also:

Constant Field Values

Constructor Detail

WeakRefAtomCache

public WeakRefAtomCache()

Method Detail

setIncidenceCache

public void setIncidenceCache(HGCache<HGPersistentHandle,IncidenceSet> cache)

getIncidenceCache

public HGCache<HGPersistentHandle,IncidenceSet> getIncidenceCache()

Description copied from interface: HGAtomCache

Return the incidence set cache. The incidence set cache is maintained separately from the main atom cache. Incidence sets don't hold actual atoms, but only their handles. Also, they are ordered and can be queried for membership efficiently.

Specified by:

getIncidenceCache in interface HGAtomCache

setHyperGraph

public void setHyperGraph(HyperGraph hg)

Description copied from interface: HGAtomCache

Set the HyperGraph within which this cache is operating. A given cache implementation may or may not need a reference to the HyperGraph instance, depending on the level of sophistication of the cache. For example, some cache policies may want to persist certain usage statistics in the HGStore, others may want to attach particular importance to certain atom types etc.

Specified by:

setHyperGraph in interface HGAtomCache

Parameters:

hg - The HyperGraph instance.

atomRead

public HGLiveHandle atomRead(HGPersistentHandle pHandle,
                             java.lang.Object atom,
                             byte flags)

Description copied from interface: HGAtomCache

Inform the cache that an atom has just been read from persistent storage. The cache is free to decide whether that atom should be actually cached or not, but in any case it must construct and return HGLiveHandle for the atom.

If the atom corresponding to specified persistent handle is already in the cache, it should be replaced with the new passed in value.

Specified by:

atomRead in interface HGAtomCache

Parameters:

pHandle - The persistent handle of the atom.

atom - The run-time instance of the atom.

flags - Atom management related flags that must be stored as part of its live handle.

Returns:

A valid HGLiveHandle to the atom.

atomRead

public HGManagedLiveHandle atomRead(HGPersistentHandle pHandle,
                                    java.lang.Object atom,
                                    byte flags,
                                    long retrievalCount,
                                    long lastAccessTime)

Description copied from interface: HGAtomCache

Inform the cache that an atom with system-level attributes has been loaded. This has the same function as the simpler version of atomRead, but the cache must construct an instance of HGExtLiveHandle for purposes of non-default atom management.

Specified by:

atomRead in interface HGAtomCache

Parameters:

pHandle - The persistent handle of the atom.

atom - The run-time instance of the atom.

flags - The system flags for this atom.

retrievalCount - The recorded overall retrieval count for this atom.

lastAccessTime - A timestamps (in milliseconds) representing the last time this atom was accessed.

Returns:

A HGManagedLiveHandle encapsulating the atom instance, persistence handle and system-level attributes.

atomRefresh

public void atomRefresh(HGLiveHandle handle,
                        java.lang.Object atom)

Description copied from interface: HGAtomCache

Refresh a previously evicted atom. This method is invoked when HyperGraph needs to inform the cache about a change of the value of an atom. The cache must assign the new reference to the cached live handle and, as the case may be, reinsert the atom into its caching structures.

Specified by:

atomRefresh in interface HGAtomCache

Parameters:

handle - The HGLiveHandle handle of the atom to be refreshed.

atom - The atom value. HyperGraph will obtain this value either from the cache, in case the atom has already been refetched from storage after the eviction event, or it will retrieve and create a new run-time instance.

close

public void close()

Description copied from interface: HGAtomCache

Close the cache. This will clear the cache, completely and perform any cleaning operations such as unloading of atoms and the like.

Once the cache is closed, it cannot be used again.

This method is normally invoked by HyperGraph only. The method is not guarantueed to be thread-safe. It can rely on the fact that no other threads are accessing the cache while it is executing.

Specified by:

close in interface HGAtomCache

get

public HGLiveHandle get(HGPersistentHandle pHandle)

Description copied from interface: HGAtomCache

Retrieve an atom from the cache by its persistent handle.

Specified by:

get in interface HGAtomCache

Parameters:

pHandle - The HGPersistentHandle of the desired atom.

Returns:

The HGLiveHandle of the atom or null if the atom is not in the cache.

get

public HGLiveHandle get(java.lang.Object atom)

Description copied from interface: HGAtomCache

Retrieve the HGLiveHandle of a run-time atom instance.

Specified by:

get in interface HGAtomCache

Parameters:

atom - The atom object.

Returns:

The HGLiveHandle of that atom or null if the atom is not in the cache.

remove

public void remove(HGLiveHandle handle)

Description copied from interface: HGAtomCache

Force a removal a given atom from the cache. This method is generally invoked when the atom is actually deleted from the graph.

If the incidence set of this atom was loaded in the cache, it should be removed as well.

Specified by:

remove in interface HGAtomCache

Parameters:

handle - The HGLiveHandle of the atom to be removed. If the atom is currently not in the cache, nothing should be done.

isFrozen

public boolean isFrozen(HGLiveHandle handle)

Description copied from interface: HGAtomCache

Find out whether a given atom is frozen in the cache.

Specified by:

isFrozen in interface HGAtomCache

Parameters:

handle - The live handle of the atom.

Returns:

true if the atom is frozen (i.e. would never be evicted from the cache) and false otherwise.

freeze

public void freeze(HGLiveHandle handle)

Description copied from interface: HGAtomCache

Freezing an atom in the cache would prevent it from ever being removed.

Specified by:

freeze in interface HGAtomCache

Parameters:

handle - The HGLiveHandle of the atom to be frozen. The atom must already be in the cache.

unfreeze

public void unfreeze(HGLiveHandle handle)

Description copied from interface: HGAtomCache

Unfreezing a previously frozen atom makes it available for eviction. It is ok to unfreeze an atom that has never been frozen.

Specified by:

unfreeze in interface HGAtomCache

Parameters:

handle - The HGLiveHandle of the atom to be unfrozen. The atom must be in the cache.