org.hypergraphdb.atom

Class HGAtomRef

java.lang.Object

org.hypergraphdb.atom.HGAtomRef

public class HGAtomRef
extends Object

An instance HGAtomRef represents a reference to a HyperGraph atom. Atom references can be used as atom values or as values of projections of composite types.

An HGAtomRef is more than a HGHandle because it has a special relationship with its referent and may play a role in the latter's lifetime. While a HGHandle can be thought of as a plain pointer, a HGAtomRef is more like a smart pointer. When a HGAtomRef is removed from HyperGraph, the underlying referent might be affected depending on the mode of the reference.

The mode of an atom reference defines how it affects the lifetime of the atom it refers to. There are several possibilities and an application must choose the most suitable one:

1. The referent is an atom that is mainly accessed through its HGAtomRefs and generally has no purpose of being outside of that context.
2. The referent has no particular relationship to the referee, but one needs to explicitly represent a reference to an atom for the purposes automatic dereferencing, as opposed to just storing a handle which is a pure reference value.
3. The reference is an atom that may carry valuable information that is accessible through queries and other means, and it is possible to re-establish atom references to it even after their removal.

The above three cases are represented by the three possible modes of an atom reference: HARD, SYMBOLIC and FLOATING respectively. The terms HARD and SYMBOLIC were chosen because of their familiarity from Unix and derivative file systems since atom references with those modes behave like the corresponding file links in those systems. The term FLOATING is specific to HyperGraph and it has the effect of transforming a referred to atom to a temporary, managed atom that gets removed if not used.

Both a HARD and a FLOATING reference will prevent an atom from being removed from a HyperGraph database. That is, a call to HyperGraph.remove(atomHandle) will have no effect and return false whenever there's a HARD or a FLOATING reference to that atomHandle. On the other hand, SYMBOLIC references impose no such constraint. As a result, a symbolic reference may point to a non-existing atom which generally translates to null.

When a mixture of both floating and hard references point to an atom, floating references take precedence in the management of the atom's lifetime. That is, when all hard references are deleted, but a floating reference remains, the atom is not going to be deleted. Also, when both all hard reference and all floating references are deleted, the atom is transformed into a MANAGED atom instead of being removed.

Author:

Borislav Iordanov

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HGAtomRef.Mode

Constructor Summary

Constructors

Constructor and Description
HGAtomRef(HGHandle referent, HGAtomRef.Mode mode) Construct a new HGAtomRef to the atom pointed by reference and with the specified mode.

Method Summary

Methods

Modifier and Type	Method and Description
HGAtomRef.Mode	getMode() Return the atom reference mode.
HGHandle	getReferent() Return the referent atom.
boolean	isFloating() Return true if this is a floating reference and false otherwise.
boolean	isHard() Return true if this is a hard reference and false otherwise.
boolean	isSymbolic() Return true if this is a symbolic reference and false otherwise.

Methods inherited from class java.lang.Object

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

Constructor Detail

HGAtomRef

public HGAtomRef(HGHandle referent,
         HGAtomRef.Mode mode)

Construct a new HGAtomRef to the atom pointed by reference and with the specified mode.

Parameters:

referent - The HGHandle of the refered to atom.

mode - The atom reference mode. this class.

Method Detail

getMode

public HGAtomRef.Mode getMode()

Return the atom reference mode.

isHard

public boolean isHard()

Return true if this is a hard reference and false otherwise.

isSymbolic

public boolean isSymbolic()

Return true if this is a symbolic reference and false otherwise.

isFloating

public boolean isFloating()

Return true if this is a floating reference and false otherwise.

getReferent

public HGHandle getReferent()

Return the referent atom.