org.hypergraphdb
Class HGTypeSystem

java.lang.Object
  org.hypergraphdb.HGTypeSystem

public class HGTypeSystem
extends java.lang.Object

The HGTypeSystem manages atom type information for a given hypergraph database. Every hypergraph database can have its own user-definable type system.

Aliases

An alias can be defined for a commonly used type. An alias is simply a name that is associated with a type. The type instance can then be retrieved by using the alias. A type may have more than one alias. Use the addAlias, removeAlias, getType(String) and getHandle methods for working with aliases.

Author:

Borislav Iordanov

Field Summary

static HGPersistentHandle	LINK_PERSISTENT_HANDLE
static HGPersistentHandle	NULLTYPE_PERSISTENT_HANDLE
static HGPersistentHandle	PLAINLINK_PERSISTENT_HANDLE
static HGPersistentHandle	SUBSUMES_PERSISTENT_HANDLE
static HGAtomType	top
static HGPersistentHandle	TOP_PERSISTENT_HANDLE

Constructor Summary

HGTypeSystem(HyperGraph hg)
Construct the HGtypeSystem associated with a hypergraph.

Method Summary

void	addAlias(HGHandle typeHandle, java.lang.String alias) Add a new alias for a given type.
HGHandle	addPredefinedType(HGPersistentHandle handle, HGAtomType type, java.lang.Class<?> clazz) Specify an application specific predefined type, possibly overriding a default HyperGraph basic type.
void	defineTypeAtom(HGPersistentHandle handle, java.lang.Class<?> clazz) Create a HyperGraph type for the specified Java class and store the type under the passed in handle.
java.util.Set<java.lang.String>	findAliases(HGHandle typeHandle) Retrieve all the aliases of a given type.
HGAtomType	getAtomType(java.lang.Class<?> clazz) Return the HGAtomType corresponding to the passed in Java class.
HGAtomType	getAtomType(HGHandle handle) Return the type instance of a given atom.
HGAtomType	getAtomType(java.lang.Object object) Return the default HyperGraph type of the given atom object.
java.lang.Class<?>	getClassForType(HGHandle typeHandle) Return the Java class that corresponds to the given HyperGraphDB type handle.
HyperGraph	getHyperGraph() Return the HyperGraph on which this type system operates.
JavaTypeFactory	getJavaTypeFactory() Return the JavaTypeFactory which is responsible for mapping Java class to HyperGraph types.
HGAtomType	getTop()
HGAtomType	getType(HGHandle handle) Return the HGAtomType by its HGHandle.
HGAtomType	getType(java.lang.String alias) Return the HGAtomType corresponding to the given alias.
HGHandle	getTypeHandle(java.lang.Class<?> clazz) Return the HGHandle of the HyperGraph type representing a given Java class.
HGHandle	getTypeHandle(HGHandle atomHandle)
HGHandle	getTypeHandle(java.lang.Object x) Return the HyperGraph type handle of the given Java object.
HGHandle	getTypeHandle(java.lang.String alias) Return the handle of the type corresponding to the given alias.
HGHandle	getTypeHandleIfDefined(java.lang.Class<?> clazz) Return the HyperGraphDB type handle corresponding to the given Java class if a type for this class was previously defined.
boolean	hasType(java.lang.Class<?> clazz) Return true if there is a HyperGraph type corresponding to the given class and false otherwise.
void	removeAlias(java.lang.String alias) Remove a type alias.
void	storePrimitiveTypes(java.lang.String resource) Use this method to load a set of primitive types in bulk, from a text descriptor resource (loaded using this class's class loader).

Methods inherited from class java.lang.Object

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

Field Detail

TOP_PERSISTENT_HANDLE

public static final HGPersistentHandle TOP_PERSISTENT_HANDLE

LINK_PERSISTENT_HANDLE

public static final HGPersistentHandle LINK_PERSISTENT_HANDLE

PLAINLINK_PERSISTENT_HANDLE

public static final HGPersistentHandle PLAINLINK_PERSISTENT_HANDLE

SUBSUMES_PERSISTENT_HANDLE

public static final HGPersistentHandle SUBSUMES_PERSISTENT_HANDLE

NULLTYPE_PERSISTENT_HANDLE

public static final HGPersistentHandle NULLTYPE_PERSISTENT_HANDLE

top

public static final HGAtomType top

Constructor Detail

HGTypeSystem

public HGTypeSystem(HyperGraph hg)

Construct the HGtypeSystem associated with a hypergraph.

Parameters:

hg - The HyperGraph which the type system is bound.

Method Detail

storePrimitiveTypes

public void storePrimitiveTypes(java.lang.String resource)

Use this method to load a set of primitive types in bulk, from a text descriptor resource (loaded using this class's class loader).

The resource is expected to be in the following format: 1 type per line where each line consists of two or more columns separated by the space character. The first columns should be a canonical string representation of a UUID. The second column should be the classname of the class implementing the type. The (optional) subsequent columns should list the names of the classes that this type "covers". The following is an example where the first line simply adds a predefined type without any corresponding covered Java classes, and the second shows a type that covers only one class:

 db733325-19d5-11db-8b55-23bc8177d6ec org.hypergraphdb.type.NullType
 2ec10476-d964-11db-a08c-eb6f4c8f155a org.hypergraphdb.type.AtomRefType org.hypergraphdb.atom.HGAtomRef
 

Parameters:

resource -

defineTypeAtom

public void defineTypeAtom(HGPersistentHandle handle,
                           java.lang.Class<?> clazz)

Create a HyperGraph type for the specified Java class and store the type under the passed in handle.

Parameters:

handle -

clazz -

getHyperGraph

public HyperGraph getHyperGraph()

Return the HyperGraph on which this type system operates.

getJavaTypeFactory

public JavaTypeFactory getJavaTypeFactory()

Return the JavaTypeFactory which is responsible for mapping Java class to HyperGraph types.

getTop

public HGAtomType getTop()

addPredefinedType

public HGHandle addPredefinedType(HGPersistentHandle handle,
                                  HGAtomType type,
                                  java.lang.Class<?> clazz)

Specify an application specific predefined type, possibly overriding a default HyperGraph basic type. This method allows you to add base level types when the primitive types and type constructors provided with HyperGraph are not sufficient. For instance, one may replace the handling of simple data types such as strings and booleans, or the management of certain structured data such as a particular Java class etc.

Any HGAtomType that does not have a proper representation in the HyperGraph storage, should be added at application startup time through this method. While generally it will, such a top-level type does not need to correspond to a Java type. If there's no corresponding Java type, the clazz parameter in a call to this method should be null.

Note that a HyperGraph type may map to more than one corresponding Java class. Thus, multiple calls with the same type parameter, but different clazz parameters can be made to create a many-to-one relationship between Java type and HyperGraph types.

There is one special in the mapping of HyperGraph types to Java types: the handling of Java primitive arrays. From HyperGraph's storage perspective, all arrays are generally recorded in the same way regardless of the type of their elements (each element is stored through its own type). Therefore, a single HyperGraph array type would be able to handle all Java primitive arrays. Of course, it is possible to have specific implementations for a particular T[] Java types (for instance, an optimized boolean[]). But there is a special generic handling of all Java built-in arrays that is specified as the HyperGraph type of the Object[] class. That is, to specify the HGAtomType that should be used for Java primitive array storage, use the class of Object[] as the third parameter of this method. For example:

typeSystem.addPredefinedType(persistentHandle, type, Class.forName("[Ljava.lang.Object;"));

Parameters:

handle - The persistent handle of this type.

type - The run-time instance of the type.

clazz - The Java class to which this type corresponds. All atoms that are instances of this Java class will be handled through this type. This parameter may be null if the type should not be mapped to a Java class.

Returns:

A run-time handle for the newly added type.

getClassForType

public java.lang.Class<?> getClassForType(HGHandle typeHandle)

Return the Java class that corresponds to the given HyperGraphDB type handle. The result is the class of the run-time instances constructed with the type identified by typeHandle.

Parameters:

typeHandle - The HGHandle identifying the type whose runtime Java class is required.

Returns:

The Java class corresponding to typeHandle or null if there's no such correspondence.

getType

public HGAtomType getType(HGHandle handle)

Return the HGAtomType by its HGHandle.

Parameters:

handle - The handle of the atom type itself. Note that to retrieve the type of an atom, you must use the getAtomType(Object) method.

getType

public HGAtomType getType(java.lang.String alias)

Return the HGAtomType corresponding to the given alias.

Parameters:

alias - The alias.

Returns:

The type instance or null if this alias has not been defined.

getAtomType

public HGAtomType getAtomType(java.lang.Class<?> clazz)

Return the HGAtomType corresponding to the passed in Java class. This is equivalent to (HGAtomType)HyperGraph.get(getTypeHandle(clazz)).

getAtomType

public HGAtomType getAtomType(java.lang.Object object)

Return the default HyperGraph type of the given atom object. Note the default here means that the type returned is the one that would be automatically assigned to instances of the concrete type of object. That is, calling this method is equivalent to calling getAtomType(object.getClass()). If object is the run-time instance of an actual HyperGraph atom that was explicitely assigned a type, the latter may be different than the default type.

getAtomType

public HGAtomType getAtomType(HGHandle handle)

Return the type instance of a given atom.

Parameters:

handle - The atom whose type is desired.

Returns:

The type of the atom.

hasType

public boolean hasType(java.lang.Class<?> clazz)

Return true if there is a HyperGraph type corresponding to the given class and false otherwise.

getTypeHandleIfDefined

public HGHandle getTypeHandleIfDefined(java.lang.Class<?> clazz)

Return the HyperGraphDB type handle corresponding to the given Java class if a type for this class was previously defined. Return null otherwise.

getTypeHandle

public HGHandle getTypeHandle(java.lang.Class<?> clazz)

Return the HGHandle of the HyperGraph type representing a given Java class. If no type has been associated yet with that particular Class, a new one will be created using the currently active JavaTypeFactory.

Parameters:

clazz - The Class instance of the Java class. Cannot be null

Returns:

The HGHandle for that class. If the Java class hasn't been previously mapped to a HyperGraph atom type, a new HyperGraph type will be created and the new handle will be returned.

getTypeHandle

public HGHandle getTypeHandle(java.lang.String alias)

Return the handle of the type corresponding to the given alias.

Parameters:

alias - The alias.

Returns:

The type handle or null if this alias has not been defined.

getTypeHandle

public HGHandle getTypeHandle(HGHandle atomHandle)

getTypeHandle

public HGHandle getTypeHandle(java.lang.Object x)

Return the HyperGraph type handle of the given Java object.

This method will first try to find the HyperGraph HGHandle of the object and retrieve the type based on that handle. If not, it will retrieve the default HyperGraph type of the concrete Java class of the object (i.e. of x.getClass()).

Parameters:

x - The object whose HyperGraph type is desired. Cannot be null.

Returns:

The HGHandle of the HyperGraph type for that object.

addAlias

public void addAlias(HGHandle typeHandle,
                     java.lang.String alias)

Add a new alias for a given type.

Parameters:

typeHandle - The HGPersistentHandle of the type. Note that the method doesn't check whether this is in fact a type handle.

alias - A non-null alias name. If this name is already used to alias another type, an exception is thrown.

findAliases

public java.util.Set<java.lang.String> findAliases(HGHandle typeHandle)

Retrieve all the aliases of a given type.

Parameters:

typeHandle - The handle of the type whose aliases are desired.

Returns:

A regular HGSearchResult containing the aliases. Make sure to close the result set as all other result sets in HyperGraphDB.

removeAlias

public void removeAlias(java.lang.String alias)

Remove a type alias. If the alias hasn't been previously defined, nothing is done.

Parameters:

alias - The alias to remove. Cannot by null.

Throws:

java.lang.NullPointerException - if alias is null.