IntroHGHandles

One refers to object on a memory heap with memory addresses. In a relational database, one uses primary keys. On the internet, it's URIs. With HyperGraphDB, one uses HyperGraphDB handles - instances of HGHandle. When you add an atom with the HyperGraph.add method, you get back a HGHandle. When you query for atoms, you get back a set of handles. HyperGraphDB links also point to atoms by using handles. In other words, handles are to HyperGraphDB what object references are to Java or pointers to C/C++.

If you have a HGHandle, you can get the actual atom by calling HyperGraph.get. For example:

HGHandle handle = // some means to obtain a handle to an atom
Book book = (Book)graph.get(handle);

In general, when working with objects that reside in HyperGraphDB, it is preferable to use handles and retrieve the actual object on a need-by-need basis. This recommendation is based on:

1. The way caching of objects works in HyperGraphDB. The system will cache all currently loaded atoms and maintain a map b/w HGHandles and Java object references. When a Java object is garbage collected, the cache clears its maps from it after a while. But the handle remains valid and the object will be automatically re-loaded upon the next HyperGraph.get(handle) request.
2. The fact that links in the graph are based on handles, not plain Java references. The HyperGraph.get method is pretty fast (most of the time it doesn't even involve a hash lookup), so it's ok to use HGHandle as your way of referring to objects stored in HyperGraphDB instead of plain Java references.

You will notice that HGHandle is actually just a marker interface. There are several implementation of it that may change in the future, so you shouldn't be relying on any concrete implementation. The only time you may be interested in a variety of a HyperGraphDB handle is if you want to persist the handle somewhere else. In those cases, you can get a persistent version of it by calling HyperGraph.getPersistentHandle(handle). Persistent handles are represented by the HGPersistentHandle interface. They can be converted to byte buffers and then read back with HGHandleFactory.makeHandle.

From Objects to Handles

If you have a Java object reference that is also a HyperGraphDB atom, you can obtain its handle through the HyperGraph.getHandle(object) method. Thus despite the advice given above, you're not required to refer to hypergraph atoms only through their handles. It would be cumbersome to have to obtain the object with calls to HyperGraph.get every time you need it.

However, you must be careful that the object whose handle you're trying to obtain is actually in the HyperGraphDB cache. It will be there either if it was loaded from HyperGraphDB through a previous get or if it was just recently added by a call to add.

In general, you would use the Java object reference whenever you have to work with the actual data value and/or you want to isolate an application layer from the HyperGraphDB API. And you would use the HGHandle interface when you are mindful of memory consumption and/or you are working mainly with the graph structure of your data, rather than individual atoms.

<< Prev - Storing Data Next - Atom Types >>