org.hypergraphdb
Interface HGAtomCache

All Known Implementing Classes:

DefaultAtomCache, WeakRefAtomCache

public interface HGAtomCache

The HGAtomCache interface abstracts the HyperGraph caching activities in order for different caching policies and implementations to be configured and plugged. A successful caching policy will largely depend on a particular application. For instance, some applications may maintain most HyperGraph atoms within their own data structures whilst others would entirely rely on HyperGraph and continuously query for atoms on a need by need basis.

The cache is reminiscent to a memory manager. Both HyperGraph and its HGTypeSystem rely on the cache to manage live vs. persistent information.

This interface is made public in order to allow for custom plugging of atom caching policies. It is never to be used directly be applications.

The HGAtomCache is responsible for the following:

• Manage run-time instances of atoms.
• Create live handle for newly loaded atoms.
• Generate an HGAtomEvictedEvent for every atom that is removed from the cache.
• Cache and manages incidence sets on a per-atom basis.
• Provide mappings between atoms' live handles and their persistence handles.

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.
HGHandle[]	getIncidenceSet(HGPersistentHandle handle) Return the incidence set of a given atom or null if the set is not in the cache.
void	incidenceSetRead(HGPersistentHandle handle, HGHandle[] incidenceSet) Inform the cache that the incidence set of a given atom has been retrieved from permanent storage.
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	removeIncidenceSet(HGPersistentHandle handle) Remove the incidence set of an atom from the cache.
void	setHyperGraph(HyperGraph hg) Set the HyperGraph within which this cache is operating.
void	unfreeze(HGLiveHandle handle) Unfreezing a previously frozen atom makes it available for eviction.

Method Detail

setHyperGraph

void setHyperGraph(HyperGraph hg)

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.

Parameters:

hg - The HyperGraph instance.

atomRead

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

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.

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

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. 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.

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

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

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.

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.

get

HGLiveHandle get(HGPersistentHandle pHandle)

Retrieve an atom from the cache by its persistent handle.

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

HGLiveHandle get(java.lang.Object atom)

Retrieve the HGLiveHandle of a run-time atom instance.

Parameters:

atom - The atom object.

Returns:

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

remove

void remove(HGLiveHandle handle)

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.

Parameters:

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

freeze

void freeze(HGLiveHandle handle)

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

Parameters:

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

unfreeze

void unfreeze(HGLiveHandle handle)

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

Parameters:

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

isFrozen

boolean isFrozen(HGLiveHandle handle)

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

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.

close

void close()

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.

incidenceSetRead

void incidenceSetRead(HGPersistentHandle handle,
                      HGHandle[] incidenceSet)

Inform the cache that the incidence set of a given atom has been retrieved from permanent storage.

The cache may decide to cache the incidence set or not. HyperGraph will usually query the cache for the incidence set of an atom before reading from storage.

IMPLEMENTATION NOTE: the current/default storage mechanism for HyperGraphDB being BerkeleyDB, there is relatively little need to cache a lot of incidence sets. Usually BerkeleyDB has its own cache and since construction of a HGHandle from byte[] is quite fast (compared to atom instance construction) one can rely mostly on the underlying Berkeley DB's cache for incidence set. [note on the note: this is pure speculation, never measured any of this. ;)].

Parameters:

handle - The HGPersistentHandle of the atom whose incidence set has been retrieved.

incidenceSet - The incidence set of the atom.

getIncidenceSet

HGHandle[] getIncidenceSet(HGPersistentHandle handle)

Return the incidence set of a given atom or null if the set is not in the cache.

Parameters:

handle - The persistent handle of the atom whose incidence set is desired.

Returns:

A HGHandle array holding the handle of all links pointing to the given atom.

removeIncidenceSet

void removeIncidenceSet(HGPersistentHandle handle)

Remove the incidence set of an atom from the cache.

Parameters:

handle - The HGPersistentHandle of the atom whose incidence set is to be removed.