org.hypergraphdb
Class HyperGraph

java.lang.Object
  org.hypergraphdb.HyperGraph

public class HyperGraph
extends java.lang.Object

This is the main class representing a HyperGraph database. A HyperGraph database resides in a dedicated folder and can be accessed by more than one process. Also, a single process may open several databases at once.

Because HyperGraphDB is primarily an embedded database, it does not rely on a client-server model and therefore there is no notion of a connection. The database is accessed by instantiating an instance of this class and then using its methods. An instance of this class is essentially a connection to the database and it must be always properly closed before application shutdown. To close the database, call the close method. When the application exits abruptly, without having a chance to close, it may fail to open subsequently without running a recovery process. A light recovery process is performed every time you open a database, but sometimes a full recovery may be needed in which case a separate command line utility must be run as documented in the reference guide.

This class encapsulates and offers access to all important HyperGraphDB top-level objects such as its associated HGTransactionManager, HGTypeSystem, HGEventManager and the low-level HGStore.

Each datum in a HyperGraph database is called an atom. Atoms are either arbitrary plain objects or instances of HGLink. Using this class, you may:

• Add new atoms with the add family of methods.
• Remove existing atoms with the remove method.
• Change the value of an atom while preserving its HyperGraph handle (i.e. its database id, if you will) with the replace family of methods.
• Add new atoms with existing handles with the define family of methods. This is useful, for example, when moving atoms from one HyperGraphDB to another.

An important aspect of HyperGraph atoms are their associated system flags. More information about what those are and how to use them can be found in the HGSystemFlags class.

For aggregate structures such as Java beans, it is often useful to create indices to speed up searching by certain properties. You can manipulate indices with the HGIndexerManager associated with a HyperGraph instance. Call getIndexManager to get the index manager.

Author:

Borislav Iordanov

Field Summary

static HGPersistentHandle[]	EMPTY_PERSISTENT_HANDLE_SET
static HGHandle[]	EMTPY_HANDLE_SET
static LazyRef<HGHandle[]>	EMTPY_HANDLE_SET_REF

Constructor Summary

HyperGraph()

HyperGraph(java.lang.String location)
Construct a run-time instance of a hypergraph database and open the database at the specified location.

Method Summary

HGHandle	add(java.lang.Object atom) Add a new atom to the database using the default, Java Beans based typing mechanism and default system flags.
HGHandle	add(java.lang.Object atom, HGHandle type) Add a new atom with a specified type and default system flags to the database.
HGHandle	add(java.lang.Object atom, HGHandle type, int flags) Add a new atom with a specified type and system flags to the database.
HGHandle	add(java.lang.Object atom, int flags) Add a new atom to the database using the default, Java Beans based typing mechanism and the set of specified system flags.
void	close() Gracefully close all resources associated with the run-time instance of HyperGraph.
void	define(HGPersistentHandle atomHandle, HGHandle typeHandle, HGHandle valueHandle, HGLink outgoingSet, java.lang.Object instance) Put an existing atom into this HyperGraph instance.
void	define(HGPersistentHandle atomHandle, java.lang.Object instance) Delegate to define(HGPersistentHandle, Object, HGHandle [], byte) with the flags parameter = 0.
void	define(HGPersistentHandle atomHandle, java.lang.Object instance, byte flags) Put an atom with a specific HGPersistentHandle into this HyperGraph instance.
<T> HGSearchResult<T>	find(HGQueryCondition condition) Run a HyperGraphDB lookup query based on the specified condition.
java.lang.Object	freeze(HGHandle handle) Freeze an atom into the HyperGraph cache.Frozen atoms are guarantueed to NOT be evicted from the cache.
<T> T	get(HGHandle handle) Retrieve a hypergraph atom by its handle.
HGConfiguration	getConfig() Return the set of configuration parameters for this HyperGraphDB instance.
HGEventManager	getEventManager() Return this HyperGraph's event manager instance.
HGHandle	getHandle(java.lang.Object atom) Return the handle of the specified atom.
IncidenceSet	getIncidenceSet(HGHandle handle) Return the IncidenceSet, that is the set ofall HGLinks pointing to, the atom referred by the passed in handle.
HGIndexManager	getIndexManager() Return the HGIndexManager that is associated with this HyperGraph instance.
java.lang.String	getLocation() Return the physical location of this HyperGraph database.
HGPersistentHandle	getPersistentHandle(HGHandle handle) Return the persistent handle of a given atom.
HGStore	getStore() Return the HGStore used by this hypergraph.
int	getSystemFlags(HGHandle handle)
HGTransactionManager	getTransactionManager() Return the HGTransactionManager associated with this HyperGraph.
HGHandle	getType(HGHandle handle) Retrieve the handle of the type of the atom refered to by handle.
HGTypeSystem	getTypeSystem() Return the HGTypeSystem instance managing run-time types for this hypergraph.
boolean	isFrozen(HGHandle handle) Return true if a given is currently frozen in the cache and false otherwise.
boolean	isIncidenceSetLoaded(HGHandle h) Return true if the incidence set of a given atom is currently loaded in main memory and false otherwise.
boolean	isLoaded(HGHandle handle) Return true if a given is currently loaded in main memory and false otherwise.
boolean	isOpen() Return true is the database is currently open and false otherwise.
void	open(java.lang.String location) Open the database at the specified location.
HGHandle	refreshHandle(HGHandle handle) Refresh an atom handle with a currently valid and efficient run-time value.
boolean	remove(HGHandle handle) Remove an atom from the HyperGraph database.
boolean	remove(HGHandle handle, boolean keepIncidentLinks) Remove the atom referred to by handle from the hypergraph store.
void	replace(HGHandle handle, java.lang.Object atom) Replace the value of an atom with a new value.
void	replace(HGHandle handle, java.lang.Object atom, HGHandle type) Replace the value of an atom with a new value.
void	runMaintenance() Execute all currently scheduled maintenance operations.
void	setConfig(HGConfiguration config) Specify configuration parameters for this HyperGraphDB instance.
void	setSystemFlags(HGHandle handle, int flags)
void	unfreeze(HGHandle handle) Unfreeze a previously frozen atom so that it becomes subject of eviction from the cache.
void	update(java.lang.Object atom) Update the value of an atom in HyperGraph.

Methods inherited from class java.lang.Object

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

Field Detail

EMTPY_HANDLE_SET

public static final HGHandle[] EMTPY_HANDLE_SET

EMTPY_HANDLE_SET_REF

public static final LazyRef<HGHandle[]> EMTPY_HANDLE_SET_REF

EMPTY_PERSISTENT_HANDLE_SET

public static final HGPersistentHandle[] EMPTY_PERSISTENT_HANDLE_SET

Constructor Detail

HyperGraph

public HyperGraph()

HyperGraph

public HyperGraph(java.lang.String location)

Construct a run-time instance of a hypergraph database and open the database at the specified location.

Parameters:

location - The full path of the directory where the database resides.

Method Detail

open

public void open(java.lang.String location)

Open the database at the specified location.

Parameters:

location - The full path of the directory where the database resides.

getLocation

public java.lang.String getLocation()

Return the physical location of this HyperGraph database. The location is set either at construction or by a call to the open(String location) method.

getConfig

public HGConfiguration getConfig()

Return the set of configuration parameters for this HyperGraphDB instance.

setConfig

public void setConfig(HGConfiguration config)

Specify configuration parameters for this HyperGraphDB instance. If the instance is already opened, most parameters will not take effect.

Parameters:

config - A HGConfiguration holding the parameters. Must not be null - it is ignored if it is.

runMaintenance

public void runMaintenance()

Execute all currently scheduled maintenance operations. Note that calling this method can potentially take a long time. Also, it is imperative that no other thread accesses this HyperGraphDB instance while the maintenance operations are being executed.

This method is invoked by default when a HyperGraphDB instance is open, unless the HGConfiguration specifies that maintenance operations must be canceled or skipped. The method is made public for convenience to applications that "know" what they are doing - the same effect can be achieved by closing and re-opening the HyperGraphDB instance, but with the side effect of loosing all cached information.

close

public void close()

Gracefully close all resources associated with the run-time instance of HyperGraph.

isOpen

public boolean isOpen()

Return true is the database is currently open and false otherwise.

getStore

public HGStore getStore()

Return the HGStore used by this hypergraph.

getTransactionManager

public HGTransactionManager getTransactionManager()

Return the HGTransactionManager associated with this HyperGraph.

The transaction manager allows you to encapsulate several operations as a single, atomic transaction.

getTypeSystem

public HGTypeSystem getTypeSystem()

Return the HGTypeSystem instance managing run-time types for this hypergraph.

getEventManager

public HGEventManager getEventManager()

Return this HyperGraph's event manager instance.

getPersistentHandle

public HGPersistentHandle getPersistentHandle(HGHandle handle)

Return the persistent handle of a given atom. Generally, when working with atom handles, one needn't worry wether they are in-memory or not. However, some low-level APIs dealing with permanent storage explicitely require a HGPersistentHandle and, in addition, applications may not to record the permanent handle of an atom somewhere else.

Parameters:

handle - The HGHandle of the atom.

Returns:

The HGPersistentHandle corresponding to the passed in HGHandle.

isLoaded

public boolean isLoaded(HGHandle handle)

Return true if a given is currently loaded in main memory and false otherwise.

Parameters:

handle - The handle of the atom.

isFrozen

public boolean isFrozen(HGHandle handle)

Return true if a given is currently frozen in the cache and false otherwise. Frozen atoms are guarantueed to NOT be evicted from the cache.

Parameters:

handle - The handle of the atom.

freeze

public java.lang.Object freeze(HGHandle handle)

Freeze an atom into the HyperGraph cache.Frozen atoms are guarantueed to NOT be evicted from the cache. If the atom is not already currently loaded, it will be loaded. If it is already frozen, nothing will be done - so, it's safe to call this method multiple times. Because the atom instance is returned, this method may be called instead of get to retrieve an atom instance based on its handle while making sure that it's never removed from the cache.

This method should be called with care since it is a possible source of memory leaks. The unfreeze method should be called at appropriate times when you no longer need an object to absolutely remain in main memory. Typically, freezing an atom is desirable in the following situations:

• You need to retrieve a HGHandle from a Java instance reference by a call to the getHandle. This is only guarantueed to work when the atom is in the cache.
• The atom is a very large object, expansive to re-construct from permanent storage and even though used relatively rarely, it's better is it remain in memory. The cache will normally evict atoms based on used, not on they memory footprint which would be too much overhead to estimate in Java.

Parameters:

handle - The handle of the atom.

Returns:

The instance of the atom that was frozen.

unfreeze

public void unfreeze(HGHandle handle)

Unfreeze a previously frozen atom so that it becomes subject of eviction from the cache. If the atom is not loaded or not currently frozen in the cache, nothing is done - so, it's safe to call this method multiple times.

Parameters:

handle -

isIncidenceSetLoaded

public boolean isIncidenceSetLoaded(HGHandle h)

Return true if the incidence set of a given atom is currently loaded in main memory and false otherwise.

Parameters:

h - The handle of the atom in whose incidence we are interested.

add

public HGHandle add(java.lang.Object atom)

Add a new atom to the database using the default, Java Beans based typing mechanism and default system flags.

Parameters:

atom - The Object instance to be stored as a hypergraph atom.

Returns:

A HGHandle to the newly created atom. The handle may be used as a reference to the atom within hypergraph and to construct link to that atom.

add

public HGHandle add(java.lang.Object atom,
                    int flags)

Add a new atom to the database using the default, Java Beans based typing mechanism and the set of specified system flags. The atom to be added will be treated as a Java bean with appropriate getter and setter methods used as property accessors. The type of the atom will be inferred using the Java instrospection mechanism.

Parameters:

atom - The Object instance to be stored as a hypergraph atom.

flags - A combination of system-level bit flags. Available flags that can be or-ed together are listed in the HGSystemFlags interface.

Returns:

A HGHandle to the newly created atom. The handle may be used as a reference to the atom within hypergraph and to construct link to that atom.

add

public HGHandle add(java.lang.Object atom,
                    HGHandle type)

Add a new atom with a specified type and default system flags to the database.

Parameters:

atom - The new atom to add.

type - The handle of the HyperGraphDB type of the atom. This type must have been previously registered with the type system.

add

public HGHandle add(java.lang.Object atom,
                    HGHandle type,
                    int flags)

Add a new atom with a specified type and system flags to the database.

Parameters:

atom - The new atom to add.

type - The handle of the HyperGraphDB type of the atom. This type must have been previously registered with the type system.

flags - A combination of system-level bit flags. Available flags that can be or-ed together are listed in the HGSystemFlags interface.

Returns:

The HyperGraph handle of the newly added atom.

refreshHandle

public HGHandle refreshHandle(HGHandle handle)

Refresh an atom handle with a currently valid and efficient run-time value. HyperGraph manages essentially two types of handles: run-time handles that are reminiscent to memory pointers and provide very fast access to loaded atoms and persistent handles that refer to long term storage. An atom can be accessed with both types of handles at all times regardless of whether it is currently in memory or "passified" into permanent storage. During long operations on a large graph, it is likely that atoms get moved in and out of main memory and their live status constantly fluctuates. This method allows you to bring a HGHandle in line with the current live status of an atom. It is desirable to bring a HGHandle when the atom will be accessed frequently. The following scenarios describe situation where it may be worth refreshing a handle:

• A link has been retrieved and the atoms in its target set will be frequently accessed. Generally, the atom handles comprising the target set will be persistent handles, unless those atoms are loaded at the time the link is retrieved. Therefore, one may want to refresh that target handles after their corresponding atoms have been loaded in memory.
• An atom was loaded, but it wasn't used for a long time and was therefore removed from the cache. In this case, its live handle would loose its "liveliness" and it would be a good idea to refresh it if the atom starts being used again.

Given a persistent handle as an argument, this method will return the corresponding live handle if and only if the atom currently loaded. Given an invalid live handle, the method will either return a new, valid one if the atom was re-loaded, or it will simply return its argument if the atom is currently in the cache.

Parameters:

handle - The handle of the atom.

Returns:

An updated handle according to the behavior described above.

get

public <T> T get(HGHandle handle)

Retrieve a hypergraph atom by its handle.

HyperGraph will immediately return an atom available in memory through a live handle, and it will fetch the atom from the store for a persistent handle.

Parameters:

handle - The handle of the atom.

Returns:

The hypergraph atom. HyperGraph will construct a run-time instance of the appropriate type, but it is up to the application logic to perform the right cast. The actual type of the atom may be obtained via a call to HyperGraph.getTypeSystem().getAtomType(Object).

getHandle

public HGHandle getHandle(java.lang.Object atom)

Return the handle of the specified atom.

Parameters:

atom - The atom whose handle is desired.

Returns:

The HGHandle of the passed in atom, or null if the atom is not in HyperGraph.

getType

public HGHandle getType(HGHandle handle)

Retrieve the handle of the type of the atom refered to by handle.

FIXME: Instances of the same run-time Java type are not guarantueed to have the same HyperGraph type. For instance, a Java String may be mapped either to a HyperGraph indexed and reference counted strings, or to long text blobs. Therefore, the correct way of getting the actual HG type of an atom is by reading of off storage. We don't cache type handles of atoms as of now and this might turn out to be a performance issue.

Parameters:

handle - The HGHandle of the atom whose type is desired.

Returns:

The HGHandle of the atom type.

Throws:

HGException - if the passed in handle is invalid or unknown to HyperGraph.

remove

public boolean remove(HGHandle handle)

Remove an atom from the HyperGraph database. This is equivalent to calling remove(handle, true) - see that version of remove for detailed explanation.

Parameters:

handle -

Returns:

true if the atom was successfully removed and false otherwise.

remove

public boolean remove(HGHandle handle,
                      boolean keepIncidentLinks)

Remove the atom referred to by handle from the hypergraph store.

Note: This operation will delete the atom and potentially recursively all links pointing to it together with links pointing to them etc., if the keepIncidentLinks parameter is false. Also, if the atom is a type, all its instances are removed recursively (however, it is not possible to remove a predefined type). Thus, theoretically the removal of an atom could empty the whole hypergraph database.

When dealing with a complex linked structure, it is never obvious when incident links should be removed along with a given atom. As a rule of thumb, if the links are interpreted as ordered, in general they should be removed. Otherwise, if they are unordered, the atom should simply be removed from their target set. Note, however, that this very much depends on the application semantics. In mixed cases, when some links pointing to the atom must be removed, but others must be preserved, one should delete the former "manually" and set the keepIncidentLinks to true.

Note: also that the keepIncidentLinks applies recursively. Thus, if you set it to false links pointing to the links pointing to...etc. the given atom will all be deleted.

Parameters:

handle - The handle of the atom to be removed. NOTE: if no atom exists with this handle (e.g. the atom was already removed), the method does nothing and throws no exception. If an attempt is made to remove an atom with a null handle, then a regular NullPointerException is thrown.

keepIncidentLinks - A flag indicating whether to remove the atom from the links pointing to it (if true) or whether to remove the links altogether (if false). The flag applies recursively to all removals triggered from this call.

Returns:

true if the atom was successfully removed and false otherwise.

update

public void update(java.lang.Object atom)

Update the value of an atom in HyperGraph. This is equivalent to a call to replace(getHandle(atom), atom). An exception is thrown if the handle of the passed in atom could not be found.

Parameters:

atom -

replace

public void replace(HGHandle handle,
                    java.lang.Object atom)

Replace the value of an atom with a new value. The atom will preserve its handle and all links pointing to it will remain valid. This method allows you to effectively change the type of an atom while preserving the hypergraph structure intact. The new value does not have to be of a different than the old value type, of course.

As when adding new atom of arbitrary Java types, the concrete type of the atom parameter will be inferred if necessary.

The structure of the graph will be modified only if the atom is replaced with a new value that has a different linking import (e.g. a node is replaced by a link or vice-versa, or a link with a different target set is being replaced).

NOTE: If a HGAtomType atom with a non-empty instance set is being replaced, the new value must also be an HGAtomType that is compatible with the old HGAtomType. Compatibility here means that the new type must be able to store all values of the old type. The replace method will effectively attempt to recursively morph all those values based on the the new HGAtomType.

Parameters:

handle - The handle of the atom to be replaced.

atom - An arbitrary Java Object representing the new atom. The type of the atom will be inferred using the Java instrospection mechanism.

replace

public void replace(HGHandle handle,
                    java.lang.Object atom,
                    HGHandle type)

Replace the value of an atom with a new value. The atom will preserve its handle and all links pointing to it will remain valid. This method allows you to effectively change the type of an atom while preserving the hypergraph structure intact. The new value does not have to be of a different than the old value type, of course.

The structure of the graph will be modified only if the atom is replaced with a new value that has a different linking import (e.g. a node is replaced by a link or vice-versa, or a link with a different target set is being replaced).

NOTE: If a HGAtomType atom with a non-empty instance set is being replaced, the new value must also be an HGAtomType that is compatible with the old HGAtomType. Compatibility here means that the new type must be able to store all values of the old type. The replace method will effectively attempt to recursively morph all those values based on the the new HGAtomType.

If an attempt is made to replace one of the predefined type atoms, the behavior is currently undefined.

Parameters:

handle - The handle of the atom to be replaced.

atom - An arbitrary Java Object representing the new atom.

type - The type of the new atom value.

define

public void define(HGPersistentHandle atomHandle,
                   HGHandle typeHandle,
                   HGHandle valueHandle,
                   HGLink outgoingSet,
                   java.lang.Object instance)

Put an existing atom into this HyperGraph instance. This is a rather low-level method that requires you to explicitely find the type and value handles for the atom and use an already existing, yet unknown to this HyperGraph instance, persistent handle.

One possible use of this is when an application relies on a HyperGraph for storage and it needs to populate it with some predefined set of atoms with a set of existing, prefabricated handles. Using handles in an application instead of some naming scheme and the corresponding name properties is the preferred way of working with HyperGraph.

Parameters:

atomHandle - A valid HGPersistentHandle of the atom being defined. If an atom already exists with this handle, it will be replaced. This parameter cannot be null.

typeHandle - The handle of this atom's type. The corresponding HGAtomType should be capable of retrieving the actual atom instance based on the passed in valueHandle. This parameter cannot be null.

valueHandle - The handle of the atom's value. This parameter cannot be null.

outgoingSet - If the atom is a link, this parameter specifies the set of atoms pointed to by the link. If this parameter is null or of size 0, then the atom is not a link.

instance - The runtime instance of the atom. The runtime instance is needed in order to update any indices related to the atom. If this parameter is null, an attempt to construct the instance from the valueHandle will be made.

define

public void define(HGPersistentHandle atomHandle,
                   java.lang.Object instance,
                   byte flags)

Put an atom with a specific HGPersistentHandle into this HyperGraph instance.

One possible of this is when an application relies on a HyperGraph for storage and it needs to populate it with some predefined set of atoms with a set of existing, prefabricated handles. Using handles in an application instead of some naming scheme and the corresponding name properties is the preferred way of working with HyperGraph.

Parameters:

atomHandle - A valid HGPersistentHandle of the atom being defined. If an atom already exists with this handle, it will be replaced. This parameter cannot be null.

instance - The handle of the atom's value. May be null in which case the default HyperGraph NullType is used.

define

public void define(HGPersistentHandle atomHandle,
                   java.lang.Object instance)

Delegate to define(HGPersistentHandle, Object, HGHandle [], byte) with the flags parameter = 0.

Parameters:

atomHandle - The handle of the atom to define.

instance - The atom's runtime instance.

getIncidenceSet

public IncidenceSet getIncidenceSet(HGHandle handle)

Return the IncidenceSet, that is the set ofall HGLinks pointing to, the atom referred by the passed in handle.

Parameters:

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

Returns:

The atom's IncidenceSet. The returned set may have 0 elements, but it will never be null.

getSystemFlags

public int getSystemFlags(HGHandle handle)

setSystemFlags

public void setSystemFlags(HGHandle handle,
                           int flags)

find

public <T> HGSearchResult<T> find(HGQueryCondition condition)

Run a HyperGraphDB lookup query based on the specified condition.

Parameters:

condition - The HGQueryCondition constraining the returned result set. It cannot be null.

getIndexManager

public HGIndexManager getIndexManager()

Return the HGIndexManager that is associated with this HyperGraph instance. The index manager may be used to create indices for specific atoms types. Such indices may result in quicker queries at the expense of slower atom insertions.