org.hypergraphdb

Class HGTypeSystem

java.lang.Object

org.hypergraphdb.HGTypeSystem

public class HGTypeSystem
extends Object

The HGTypeSystem manages atom type information for a given HyperGraph database. Each atom stored in the database has a type that carries some semantic information about the atom as well as implementing the low-level storage representation of the atom's value. Types can be dynamically added to and removed from the database - they themselves are atoms. Such atom types are distinguished by the fact that their runtime instances implement the HGAtomType interface. Every database can have its own user-definable type system bootstrapped with a set of predefined types. The type of all predefined types is called top. When the instances of a given type are themselves types (i.e. implement the HGAtomType interface, they are called type constructors. Such type constructors are used to manage dynamically added types, for example for application specific Java classes.

This class is also responsible for creating and managing mappings from Java classes to HyperGraphDB types. The runtime instance of each atom is of some Java class and there is one and only one HyperGraphDB type associated with that class. Predefined types and the mechanism by which Java class are mapped to HyperGraphDB type go hand in hand and they are both part of the global database configuration in the form of a HGTypeConfiguration instance.

You can obtain the type of a given atom or the type associated with a given Java class by calling one of the getAtomType methods. To obtain the handle of a type (instead of the actual HGAtomType instance), call one of the getTypeHandle methods.

Class loading

Since this class does a lot of introspection when mapping newly seen Java classes to HyperGraphDB types, it is worth noting how classes are looked up. The mechanism is rather simple: the ClassLoader set via the setClassLoader is tried if provided at all, otherwise the current thread class loader is tried, and finally this.getClass().getClassLoader() is tried.

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

Fields

Modifier and Type	Field and Description
static HGAtomType	top

Constructor Summary

Constructors

Constructor and Description
HGTypeSystem(HyperGraph graph) Construct the HGtypeSystem associated with a hypergraph.

Method Summary

Methods

Modifier and Type	Method and Description
void	addAlias(HGHandle typeHandle, String alias) Add a new alias for a given type.
HGHandle	addPredefinedType(HGPersistentHandle handle, HGAtomType type, Class<?> clazz) Deprecated. Use {@link #addPredefinedType(HGPersistentHandle, HGAtomType, URI) instead;
HGHandle	addPredefinedType(HGPersistentHandle handle, HGAtomType type, URI typeId) Specify an application specific predefined type, possibly overriding a default HyperGraph basic type.
void	assertSubtype(HGHandle superType, HGHandle subType) Declare that a given type is a sub-type of another type.
void	defineTypeAtom(HGHandle typeHandle, URI typeUri)
void	defineTypeAtom(HGPersistentHandle handle, Class<?> clazz) Deprecated. Please use defineTypeAtom(HGHandle, URI) instead.
Set<String>	findAliases(HGHandle typeHandle) Retrieve all the aliases of a given type.
<T extends HGAtomType> T	getAtomType(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(Object object) Return the default HyperGraph type of the given atom object.
Class<?>	getClassForType(HGHandle typeHandle) Return the Java class that corresponds to the given HyperGraphDB type handle.
String	getClassNameForType(HGHandle typeHandle) Return the Java classname that corresponds to the given HyperGraphDB type handle.
HGHandle	getHandleForIdentifier(URI typeId)
HyperGraph	getHyperGraph() Return the HyperGraph on which this type system operates.
Set<URI>	getIdentifiersForHandle(HGHandle typeHandle) Return the URI identifiers of the set of types realized by the given type atom.
JavaTypeMapper	getJavaTypeFactory() Deprecated.
HGHandle	getNullType() Return the type of the special Java value null.
HGTypeSchema<?>	getSchema()
HGHandle	getTop() Return the type of all predefined types.
HGAtomType	getType(HGHandle handle) Return the HGAtomType by its HGHandle.
HGAtomType	getType(String alias) Return the HGAtomType corresponding to the given alias.
HGHandle	getTypeHandle(Class<?> clazz) Return the HGHandle of the HyperGraph type representing a given Java class.
HGHandle	getTypeHandle(HGHandle atomHandle) Deprecated. Please call #HyperGraph.getType(HGHandle) instead. This method will be removed in future versions.
HGHandle	getTypeHandle(Object x) Return the HyperGraph type handle of the given Java object.
HGHandle	getTypeHandle(String alias) Return the handle of the type corresponding to the given alias.
HGHandle	getTypeHandle(URI typeIdentifier)
HGHandle	getTypeHandleIfDefined(Class<?> clazz) Return the handle of the type associated with the specified class.
HGHandle	getTypeHandleIfDefined(URI uri) Return the HyperGraphDB type handle corresponding to the given Java class if a type for this class was previously defined.
HGTypeStructuralInfo	getTypeMetaData(HGHandle typeHandle) Return any metadata associated with the given type or null.
boolean	hasType(Class<?> clazz) Return true if there is a HyperGraph type corresponding to the given class and false otherwise.
Class<?>	loadClass(String classname) Load a class with the given name the way the HGTypeSystem would try to load it.
void	removeAlias(String alias) Remove a type alias.
void	setTypeForClass(HGHandle typeHandle, Class<?> clazz) Specifically map a HyperGraphDB HGAtomType, already stored as an atom with handle typeHandle to the Java class clazz.
void	storePrimitiveTypes(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

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

Field Detail

top

public static final HGAtomType top

Constructor Detail

HGTypeSystem

public HGTypeSystem(HyperGraph graph)

Construct the HGtypeSystem associated with a hypergraph.

Parameters:

graph - The HyperGraph which the type system is bound.

Method Detail

storePrimitiveTypes

public void storePrimitiveTypes(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 class name 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 -

getSchema

public HGTypeSchema<?> getSchema()

defineTypeAtom

public void defineTypeAtom(HGHandle typeHandle,
                  URI typeUri)

defineTypeAtom

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

Deprecated. Please use defineTypeAtom(HGHandle, URI) instead.

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

Parameters:

handle -

clazz -

assertSubtype

public void assertSubtype(HGHandle superType,
                 HGHandle subType)

Declare that a given type is a sub-type of another type. It is not necessary to call this method for sub-typing relationships that are automatically inferred from a Java class hierarchy. However, custom types and type constructors can use this method for sub-type bookkeeping, which is important for querying and indexing. A sub-type is represented by a HGSubsumes link.

In addition, the HGIndexManager must be informed about a sub-typing relationships in order to maintain indices appropriately.

Parameters:

superType - The parent type.

subType - The child type.

getHyperGraph

public HyperGraph getHyperGraph()

Return the HyperGraph on which this type system operates.

getJavaTypeFactory

public JavaTypeMapper getJavaTypeFactory()

Deprecated.

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

getNullType

public HGHandle getNullType()

Return the type of the special Java value null.

getTop

public HGHandle getTop()

Return the type of all predefined types.

getTypeHandleIfDefined

public HGHandle getTypeHandleIfDefined(URI uri)

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

getHandleForIdentifier

public HGHandle getHandleForIdentifier(URI typeId)

getIdentifiersForHandle

public Set<URI> getIdentifiersForHandle(HGHandle typeHandle)

Return the URI identifiers of the set of types realized by the given type atom. With the default Java type system, this will give you all the Java classes that are handled by the specified HyperGraphDB type.

Most of the time, there will be one class only, but for some cases there may be more. Objects stored through their java.io.Serializable interface are such a case. For example to find what Java classes the type system is treating as serializable, you could write:

  HGTypeSystem ts = graph.getTypeSystem();
  Set serializableClasses = ts.getIdentifiersForHandle(ts.getTypeHandle(Serializable.class));
 

Parameters:

typeHandle -

Returns:

loadClass

public Class<?> loadClass(String classname)

Load a class with the given name the way the HGTypeSystem would try to load it. First try a user-defined class loader with this instance, then try the Thread content class loader, finally try this.getClass().getClassLoader() which is usually the system class loader.

Parameters:

classname -

Returns:

addPredefinedType

public HGHandle addPredefinedType(HGPersistentHandle handle,
                         HGAtomType type,
                         URI typeId)

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 case 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.

addPredefinedType

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

Deprecated. Use {@link #addPredefinedType(HGPersistentHandle, HGAtomType, URI) instead;

getClassForType

public 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.

setTypeForClass

public void setTypeForClass(HGHandle typeHandle,
                   Class<?> clazz)

Specifically map a HyperGraphDB HGAtomType, already stored as an atom with handle typeHandle to the Java class clazz. Any previous type association with clazz will be removed.

Parameters:

typeHandle - can't be null

clazz - can't be null

getClassNameForType

public String getClassNameForType(HGHandle typeHandle)

Return the Java classname that corresponds to the given HyperGraphDB type handle. The result is the name of the class 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 name 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(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 <T extends HGAtomType> T getAtomType(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(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(Class<?> clazz)

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

getTypeHandleIfDefined

public HGHandle getTypeHandleIfDefined(Class<?> clazz)

Return the handle of the type associated with the specified class. The name of the class is first converted to a type URI. See getHandleForIdentifier(URI).

getTypeHandle

public HGHandle getTypeHandle(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(URI typeIdentifier)

getTypeHandle

public HGHandle getTypeHandle(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)

Deprecated. Please call #HyperGraph.getType(HGHandle) instead. This method will be removed in future versions.

Return the (handle of the) type of the given atom.

Parameters:

atomHandle - The handle of the atom whose type is desired.

getTypeHandle

public HGHandle getTypeHandle(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,
            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 Set<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.

getTypeMetaData

public HGTypeStructuralInfo getTypeMetaData(HGHandle typeHandle)

Return any metadata associated with the given type or null.

removeAlias

public void removeAlias(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:

NullPointerException - if alias is null.