HGAtomCache (HyperGraphDB Core 1.3-SNAPSHOT API)

All Known Implementing Classes:

DefaultAtomCache, PhantomRefAtomCache, 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

Methods
Modifier and Type	Method and Description
`HGLiveHandle`	`atomAdded(HGPersistentHandle pHandle, Object atom, HGAtomAttrib attrib)` Inform the cache that a new atom has just been added to the database.
`HGLiveHandle`	`atomRead(HGPersistentHandle pHandle, Object atom, HGAtomAttrib attrib)` Inform the cache that an atom has just been read from persistent storage.
`HGLiveHandle`	`atomRefresh(HGLiveHandle handle, Object atom, boolean replace)` Replace the runtime instance of an atom with a new value.
`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(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(HGHandle 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)` Set the implementation of the incidence sets cache to use.
`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.
  - atomAdded
```
HGLiveHandle atomAdded(HGPersistentHandle pHandle,
                     Object atom,
                     HGAtomAttrib attrib)
```
    Inform the cache that a new atom has just been added to the database. 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.
    
    Parameters:
    pHandle - The persistent handle of the atom.
    atom - The run-time instance of the atom.
    attrib - Atom management related attributes that must be stored as part of its live handle.
    
    Returns:
    A valid HGLiveHandle to the atom.
  - atomRead
```
HGLiveHandle atomRead(HGPersistentHandle pHandle,
                    Object atom,
                    HGAtomAttrib attrib)
```
    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.
    attrib - Atom management related attributes that must be stored as part of its live handle.
    
    Returns:
    A valid HGLiveHandle to the atom.
  - atomRefresh
```
HGLiveHandle atomRefresh(HGLiveHandle handle,
                       Object atom,
                       boolean replace)
```
    Replace the runtime instance of an atom with a new value. 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.
    
    Note that there are two important cases of "refreshing" an atom in the cache - the atom being reloaded from permanent storage or when there is an actual value change. In the former case, a transaction abort does not need to roll back changes in the caching structures while in the latter it does! The two cases are distinguished by the third parameter of this method. ??? Note that the cache should perform a replace if handle.getRef() != null && handle.getRef() != atom because this signals that a new value must be stored. If the atom's value hasn't changed (i.e. if handle.getRef() == atom) then nothing is done.
    
    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 re-fetched from storage after the eviction event, or it will retrieve and create a new run-time instance.
    replace - true if this is a new atom value (old must be restored if the transaction aborts) and false if this is simply a reload from permanent storage where the effects of that reload may (or may not, depending on the implementation) be reversed in case of a transaction abort.
    
    Returns:
    Possibly a new live handle instance or the handle parameter depending on the implementation. If a new instance is return, the reference of the old instance is cleared.
  - 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(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(HGHandle 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 guaranteed to be thread-safe. It can rely on the fact that no other threads are accessing the cache while it is executing.
  - getIncidenceCache
```
HGCache<HGPersistentHandle,IncidenceSet> getIncidenceCache()
```
    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.
  - setIncidenceCache
```
void setIncidenceCache(HGCache<HGPersistentHandle,IncidenceSet> cache)
```
    Set the implementation of the incidence sets cache to use.
    
    Parameters:
    cache -

Interface HGAtomCache

Method Summary

Method Detail

setHyperGraph

atomAdded

atomRead

atomRefresh

get

get

remove

freeze

unfreeze

isFrozen

close

getIncidenceCache

setIncidenceCache