org.hypergraphdb
Class HGStore

java.lang.Object
  org.hypergraphdb.HGStore

public class HGStore
extends java.lang.Object

An instance of HGStore is associated with each HyperGraph to manage to low-level interaction with the underlying database mechanism.

Normally, the hypergraph store is not accessed directly by applications. However, hypergraph type implementors will rely on the HGStore to manage the way raw data is stored and indexed based on a particular type.

Note that a HGStore does not maintain any data cache, nor does it interact in any special way with the semantic layer of hypergraph and the way data and types are laid out in the store.

Author:

Borislav Iordanov

Constructor Summary

HGStore(java.lang.String database, HGConfiguration config)
Construct a HGStore bound to a specific database location.

Method Summary

void	close()
boolean	containsLink(HGPersistentHandle handle)
<KeyType,ValueType> HGBidirectionalIndex<KeyType,ValueType>	createBidirectionalIndex(java.lang.String name, ByteArrayConverter<KeyType> keyConverter, ByteArrayConverter<ValueType> valueConverter, java.util.Comparator comparator) Creates a new HGBidirectionalIndex.
<KeyType,ValueType> HGIndex<KeyType,ValueType>	createIndex(java.lang.String name, ByteArrayConverter<KeyType> keyConverter, ByteArrayConverter<ValueType> valueConverter, java.util.Comparator<?> comparator) Create a new index with the specified name.
<KeyType,ValueType> HGBidirectionalIndex<KeyType,ValueType>	getBidirectionalIndex(java.lang.String name, ByteArrayConverter<KeyType> keyConverter, ByteArrayConverter<ValueType> valueConverter, java.util.Comparator comparator) Retrieve an existing HGBidirectionalIndex by its name.
byte[]	getData(HGPersistentHandle handle) Retrieve the raw data buffer stored at handle.
java.lang.String	getDatabaseLocation() Return the physical, filesystem location of the HyperGraph store.
HGSearchResult<HGPersistentHandle>	getIncidenceResultSet(HGPersistentHandle handle) Return a HGSearchResult of atom handles in a given atom's incidence set.
HGPersistentHandle[]	getIncidenceSet(HGPersistentHandle handle)
long	getIncidenceSetCardinality(HGPersistentHandle handle) Return the number of atoms in the incidence set of a given atoms.
<KeyType,ValueType> HGIndex<KeyType,ValueType>	getIndex(java.lang.String name, ByteArrayConverter<KeyType> keyConverter, ByteArrayConverter<ValueType> valueConverter, java.util.Comparator comparator) Retrieve an HGIndex by its name.
HGPersistentHandle[]	getLink(HGPersistentHandle handle) Retrieve an existing link by its handle.
byte[]	getLinkData(HGPersistentHandle handle) Retrieves an existing link in raw byte form.
HGTransactionFactory	getTransactionFactory() Create and return a transaction factory for this HGStore.
HGTransactionManager	getTransactionManager() Return this store's HGTransactionManager.
HGPersistentHandle[]	readHandles(byte[] data, int offset) Read a persistent handle array of size n out of a raw data buffer.
HGPersistentHandle[]	readHandles(byte[] data, int offset, int length) Read a persistent handle array of size n out of a raw data buffer.
HGPersistentHandle[]	readNHandles(byte[] data, int offset, int n) Read a persistent handle array of size n out of a raw data buffer.
void	removeData(HGPersistentHandle handle) Remove a raw data value associated with a HGPersistentHandle key.
void	removeIndex(java.lang.String name) Remove an index from the database.
void	removeLink(HGPersistentHandle handle) Remove a link value associated with a HGPersistentHandle key.
HGPersistentHandle	store(byte[] data) Write raw binary data to the store.
HGPersistentHandle	store(HGPersistentHandle[] link) Create a new link in the hypergraph store.
void	store(HGPersistentHandle handle, byte[] data) Write raw binary data to the store using a pre-created, unique persistent handle.
HGPersistentHandle	store(HGPersistentHandle handle, HGPersistentHandle[] link) Create a new link in the hypergraph store with an existing handle.

Methods inherited from class java.lang.Object

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

Constructor Detail

HGStore

public HGStore(java.lang.String database,
               HGConfiguration config)

Construct a HGStore bound to a specific database location.

Parameters:

database -

Method Detail

getTransactionFactory

public HGTransactionFactory getTransactionFactory()

Create and return a transaction factory for this HGStore.

getTransactionManager

public HGTransactionManager getTransactionManager()

Return this store's HGTransactionManager.

getDatabaseLocation

public java.lang.String getDatabaseLocation()

Return the physical, filesystem location of the HyperGraph store.

store

public HGPersistentHandle store(HGPersistentHandle[] link)

Create a new link in the hypergraph store. A new HGPersistentHandle is created to refer to the link.

Parameters:

link - A non-null, but possibly empty array of persistent atom handles that constitute the link to be created.

Returns:

The newly created HGPersistentHandle.

store

public HGPersistentHandle store(HGPersistentHandle handle,
                                HGPersistentHandle[] link)

Create a new link in the hypergraph store with an existing handle. It is up to the caller of this method to ensure that the passed in handle is unique.

Parameters:

handle - A unique HGPersistentHandle that will refer to the link within the hypergraph store.

link - A non-null, but possibly empty array of persistent atom handles that constitute the link to be created.

The - handle parameter.

store

public HGPersistentHandle store(byte[] data)

Write raw binary data to the store. A new persistent handle is created to refer to the data.

Parameters:

A - non-null, but possibly empty byte[] holding the data to write.

Returns:

The newly created HGPersistentHandle that refers to the recorded data.

store

public void store(HGPersistentHandle handle,
                  byte[] data)

Write raw binary data to the store using a pre-created, unique persistent handle.

Parameters:

handle - A unique HGPersistentHandle to be recorded as the data key.

A - non-null, but possibly empty byte[] holding the data to write.

removeLink

public void removeLink(HGPersistentHandle handle)

Remove a link value associated with a HGPersistentHandle key.

removeData

public void removeData(HGPersistentHandle handle)

Remove a raw data value associated with a HGPersistentHandle key.

getLink

public HGPersistentHandle[] getLink(HGPersistentHandle handle)

Retrieve an existing link by its handle.

Parameters:

handle - The persistent handle of the link. A NullPointerException is thrown if this parameter is null.

Returns:

An array of handles forming the link or null if there is no link with that HGPersistentHandle in the database. Note that if the passed in handle points, the behavior is undefined - the method might throw an exception or return an array of invalid links.

getLinkData

public byte[] getLinkData(HGPersistentHandle handle)

Retrieves an existing link in raw byte form. The returned byte array contains the 16 byte UUID of the handles constituting the link.

Parameters:

handle -

Returns:

readNHandles

public HGPersistentHandle[] readNHandles(byte[] data,
                                         int offset,
                                         int n)

Read a persistent handle array of size n out of a raw data buffer. The buffer must contain at least n persistent handles starting at offset.

Parameters:

data - The data buffer.

offset - The 0 based offset from which the read starts.

n - The number of handles to read.

Returns:

A new HGPersistentHandle[] with the retrieved handles.

readHandles

public HGPersistentHandle[] readHandles(byte[] data,
                                        int offset,
                                        int length)

Read a persistent handle array of size n out of a raw data buffer.

Parameters:

data - The data buffer.

offset - The 0 based offset from which the read starts.

length - The number of bytes to read.

Returns:

A new HGPersistentHandle[] with the retrieved handles.

readHandles

public HGPersistentHandle[] readHandles(byte[] data,
                                        int offset)

Read a persistent handle array of size n out of a raw data buffer. All bytes including and following offset are read.

Parameters:

data - The data buffer.

offset - The 0 based offset from which the read starts.

Returns:

A new HGPersistentHandle[] with the retrieved handles.

containsLink

public boolean containsLink(HGPersistentHandle handle)

getData

public byte[] getData(HGPersistentHandle handle)

Retrieve the raw data buffer stored at handle.

Parameters:

handle - The HGPersistentHandle of the data. Cannot be null.

Returns:

The data pointed to by handle or null if it could not be found.

getIncidenceSet

public HGPersistentHandle[] getIncidenceSet(HGPersistentHandle handle)

getIncidenceResultSet

public HGSearchResult<HGPersistentHandle> getIncidenceResultSet(HGPersistentHandle handle)

Return a HGSearchResult of atom handles in a given atom's incidence set.

Parameters:

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

Returns:

The HGSearchResult iterating over the incidence set.

getIncidenceSetCardinality

public long getIncidenceSetCardinality(HGPersistentHandle handle)

Return the number of atoms in the incidence set of a given atoms. That is, return the number of links pointing to the atom.

createIndex

public <KeyType,ValueType> HGIndex<KeyType,ValueType> createIndex(java.lang.String name,
                                                                  ByteArrayConverter<KeyType> keyConverter,
                                                                  ByteArrayConverter<ValueType> valueConverter,
                                                                  java.util.Comparator<?> comparator)

Create a new index with the specified name. If an index with this name already exists, the method will return null.

Once the index is created, it can be used without further setup. Note that the HGStore does not provide any automatic population of manually created indices. It does, however, manage entries once they are added to an index so that integrity is maintained after a removal operation.

Parameters:

name - The name of the newly created index.

comparatorClass - The comparator class used to compare the keys of this index. This parameter may be null if the default, lexicographical byte ordering comparator is to be used.

Returns:

A ready to use HGIndex or null if an index with the specified name already exists.

createBidirectionalIndex

public <KeyType,ValueType> HGBidirectionalIndex<KeyType,ValueType> createBidirectionalIndex(java.lang.String name,
                                                                                            ByteArrayConverter<KeyType> keyConverter,
                                                                                            ByteArrayConverter<ValueType> valueConverter,
                                                                                            java.util.Comparator comparator)

Creates a new HGBidirectionalIndex. This method has the exact same behavior as the createIndex method, except that a bidirectional implementation is constructed.

getIndex

public <KeyType,ValueType> HGIndex<KeyType,ValueType> getIndex(java.lang.String name,
                                                               ByteArrayConverter<KeyType> keyConverter,
                                                               ByteArrayConverter<ValueType> valueConverter,
                                                               java.util.Comparator comparator)

Retrieve an HGIndex by its name. An index will not be automatically created if it does not exists. To create an index, use the createIndex method.

Parameters:

name - The name of the desired index.

Returns:

The HGIndex with the given name or null if no such index exists.

getBidirectionalIndex

public <KeyType,ValueType> HGBidirectionalIndex<KeyType,ValueType> getBidirectionalIndex(java.lang.String name,
                                                                                         ByteArrayConverter<KeyType> keyConverter,
                                                                                         ByteArrayConverter<ValueType> valueConverter,
                                                                                         java.util.Comparator comparator)

Retrieve an existing HGBidirectionalIndex by its name.

Throws:

java.lang.ClassCastException - is the index with the specified name is not bidirectional.

removeIndex

public void removeIndex(java.lang.String name)

Remove an index from the database. Note that all entries in this index will be lost.

close

public void close()