org.hypergraphdb
Interface HGLink

All Known Implementing Classes:

AtomProjection, HGBergeLink, HGPlainLink, HGRel, HGRelType, HGSubsumes, HGValueLink, LinkRecord, TempLink

public interface HGLink

The HGLink interface defines an unordered hypergraph link. A hypergraph link is an atom that holds other atoms in a relationship. The precise semantics and interpretation of the relationship are application specific and will generally depend on a particular link's type and properties. The only restriction imposed by HyperGraph is that a link be of arity greater than 0.

The collection of atoms which an instance of HGLink connects is immutable. However, if the link is an instance of a particular type, its associated properties are mutable.

Implementations of this interfaces must provide a the notifyTargetHandleUpdate to allow hypergraph to notify them when a target atom was loaded/unloaded from the database.

Author:

Borislav Iordanov

Method Summary

int	getArity() Return the number of targets of this link.
HGHandle	getTargetAt(int i) Return the ith target.
void	notifyTargetHandleUpdate(int i, HGHandle handle) Notify the HGLink that one of its target atoms should be referred to by a different HGHandle instance.
void	notifyTargetRemoved(int i) Notify the HGLink that one of its targets must be removed.

Method Detail

getArity

int getArity()

Return the number of targets of this link. This number may be >= 0.

getTargetAt

HGHandle getTargetAt(int i)

Return the ith target.

Parameters:

i - The index of the desired target. The range of this parameters must be [0...getArity() - 1].

notifyTargetHandleUpdate

void notifyTargetHandleUpdate(int i,
                              HGHandle handle)

Notify the HGLink that one of its target atoms should be referred to by a different HGHandle instance. Generally, implementation should update their reference to this target with the passed in live handle.

IMPORTANT NOTE: This method should never be called by application code. It is strictly reserved to the HyperGraph implementation which guarantees that the new handle will always refer to the same atom. The method should essentially perform a setTargetAt operation, but a more elaborate name was chosen to reflect the intended usage. Note also that the intent is not for an implementation to attempt a database update! The intent is to only update the runtime representation of the set of targets pointed to be this link.

Parameters:

i - The index of the target that was loaded.

handle - The new live handle of the target atom.

notifyTargetRemoved

void notifyTargetRemoved(int i)

Notify the HGLink that one of its targets must be removed. This method is invoked by the system when the target at position i refers to an atom that is being deleted from the database. Implementation are required to remove the target at that position from their implementation data structure. It remains the system's responsibility to reflect that change in permanent data storage.

An implementation may throw an IllegalArgumentException if the target cannot be removed from the link because it would somehow break the semantics of the application or lead in otherwise inconsistent state. Throwing such an exception would indicate a fatal error and a very likely bug in the application.

Parameters:

i - The 0-based position of the target to be removed from this link.

Throws:

java.lang.IllegalArgumentException - if the target cannot be removed from the link.