public interface

Type

implements Serializable
org.hibernate.type.Type
Known Indirect Subclasses

Class Overview

Defines a mapping between a Java type and one or more JDBC java.sql.Types types, as well as describing the in-memory semantics of the given java type (how do we check it for 'dirtiness', how do we copy values, etc).

Application developers needing custom types can implement this interface (either directly or via subclassing an existing impl) or by the (slightly more stable, though more limited) UserType interface.

Implementations of this interface must certainly be thread-safe. It is recommended that they be immutable as well, though that is difficult to achieve completely given the no-arg constructor requirement for custom types.

Summary

Public Methods
abstract Object assemble(Serializable cached, SessionImplementor session, Object owner)
Reconstruct the object from its cached "disassembled" state.
abstract void beforeAssemble(Serializable cached, SessionImplementor session)
Called before assembling a query result set from the query cache, to allow batch fetching of entities missing from the second-level cache.
abstract int compare(Object x, Object y, EntityMode entityMode)
Perform a Comparator style comparison between values
abstract Object deepCopy(Object value, EntityMode entityMode, SessionFactoryImplementor factory)
Return a deep copy of the persistent state, stopping at entities and at collections.
abstract Serializable disassemble(Object value, SessionImplementor session, Object owner)
Return a cacheable "disassembled" representation of the object.
abstract Object fromXMLNode(Node xml, Mapping factory)
Parse the XML representation of an instance.
abstract int getColumnSpan(Mapping mapping)
How many columns are used to persist this type.
abstract int getHashCode(Object x, EntityMode entityMode)
Get a hash code, consistent with persistence "equality".
abstract int getHashCode(Object x, EntityMode entityMode, SessionFactoryImplementor factory)
Get a hash code, consistent with persistence "equality".
abstract String getName()
Returns the abbreviated name of the type.
abstract Class getReturnedClass()
abstract Type getSemiResolvedType(SessionFactoryImplementor factory)
Get the type of a semi-resolved value.
abstract Object hydrate(ResultSet rs, String[] names, SessionImplementor session, Object owner)
Retrieve an instance of the mapped class, or the identifier of an entity or collection, from a JDBC resultset.
abstract boolean isAnyType()
Return true if the implementation is castable to AnyType.
abstract boolean isAssociationType()
Return true if the implementation is castable to AssociationType.
abstract boolean isCollectionType()
Return true if the implementation is castable to CollectionType.
abstract boolean isComponentType()
Return true if the implementation is castable to CompositeType.
abstract boolean isDirty(Object oldState, Object currentState, boolean[] checkable, SessionImplementor session)
Should the parent be considered dirty, given both the old and current value?
abstract boolean isDirty(Object old, Object current, SessionImplementor session)
Should the parent be considered dirty, given both the old and current value?
abstract boolean isEntityType()
Return true if the implementation is castable to EntityType.
abstract boolean isEqual(Object x, Object y, EntityMode entityMode)
Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent state).
abstract boolean isEqual(Object x, Object y, EntityMode entityMode, SessionFactoryImplementor factory)
Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent state).
abstract boolean isModified(Object dbState, Object currentState, boolean[] checkable, SessionImplementor session)
Has the value been modified compared to the current database state? The difference between this and the isDirty(Object, Object, boolean[], SessionImplementor) methods is that here we need to account for "partially" built values.
abstract boolean isMutable()
Are objects of this type mutable.
abstract boolean isSame(Object x, Object y, EntityMode entityMode)
Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent state) taking a shortcut for entity references.
abstract boolean isXMLElement()
abstract Object nullSafeGet(ResultSet rs, String name, SessionImplementor session, Object owner)
Retrieve an instance of the mapped class from a JDBC resultset.
abstract Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner)
Retrieve an instance of the mapped class from a JDBC resultset.
abstract void nullSafeSet(PreparedStatement st, Object value, int index, boolean[] settable, SessionImplementor session)
Write an instance of the mapped class to a prepared statement, ignoring some columns.
abstract void nullSafeSet(PreparedStatement st, Object value, int index, SessionImplementor session)
Write an instance of the mapped class to a prepared statement.
abstract Object replace(Object original, Object target, SessionImplementor session, Object owner, Map copyCache, ForeignKeyDirection foreignKeyDirection)
During merge, replace the existing (target) value in the entity we are merging to with a new (original) value from the detached entity we are merging.
abstract Object replace(Object original, Object target, SessionImplementor session, Object owner, Map copyCache)
During merge, replace the existing (target) value in the entity we are merging to with a new (original) value from the detached entity we are merging.
abstract Object resolve(Object value, SessionImplementor session, Object owner)
Map identifiers to entities or collections.
abstract Object semiResolve(Object value, SessionImplementor session, Object owner)
Given a hydrated, but unresolved value, return a value that may be used to reconstruct property-ref associations.
abstract void setToXMLNode(Node node, Object value, SessionFactoryImplementor factory)
A representation of the value to be embedded in an XML element.
abstract int[] sqlTypes(Mapping mapping)
Return the JDBC types codes (per java.sql.Types) for the columns mapped by this type.
abstract boolean[] toColumnNullness(Object value, Mapping mapping)
Given an instance of the type, return an array of boolean, indicating which mapped columns would be null.
abstract String toLoggableString(Object value, SessionFactoryImplementor factory)
A representation of the value to be embedded in a log file.

Public Methods

public abstract Object assemble (Serializable cached, SessionImplementor session, Object owner)

Reconstruct the object from its cached "disassembled" state.

Parameters
cached the disassembled state from the cache
session the session
owner the parent entity object
Returns
  • the the object

public abstract void beforeAssemble (Serializable cached, SessionImplementor session)

Called before assembling a query result set from the query cache, to allow batch fetching of entities missing from the second-level cache.

public abstract int compare (Object x, Object y, EntityMode entityMode)

Perform a Comparator style comparison between values

Parameters
x The first value
y The second value
entityMode The entity mode of the values.
Returns

public abstract Object deepCopy (Object value, EntityMode entityMode, SessionFactoryImplementor factory)

Return a deep copy of the persistent state, stopping at entities and at collections.

Parameters
value generally a collection element or entity field
Returns
  • Object a copy

public abstract Serializable disassemble (Object value, SessionImplementor session, Object owner)

Return a cacheable "disassembled" representation of the object.

Parameters
value the value to cache
session the session
owner optional parent entity object (needed for collections)
Returns
  • the disassembled, deep cloned state

public abstract Object fromXMLNode (Node xml, Mapping factory)

Parse the XML representation of an instance.

Returns
  • an instance of the type

public abstract int getColumnSpan (Mapping mapping)

How many columns are used to persist this type. Always the same as sqlTypes(mapping).length

Parameters
mapping The mapping object :/
Returns
  • The number of columns
Throws
MappingException Generally indicates an issue accessing the passed mapping object.

public abstract int getHashCode (Object x, EntityMode entityMode)

Get a hash code, consistent with persistence "equality". Again for most types the normal usage is to delegate to the value's #hashCode.

Parameters
x The value for which to retrieve a hash code
entityMode The entity mode of the value.
Returns
  • The hash code
Throws
HibernateException A problem occurred calculating the hash code

public abstract int getHashCode (Object x, EntityMode entityMode, SessionFactoryImplementor factory)

Get a hash code, consistent with persistence "equality". Again for most types the normal usage is to delegate to the value's #hashCode.

Parameters
x The value for which to retrieve a hash code
entityMode The entity mode of the value.
factory The session factory
Returns
  • The hash code
Throws
HibernateException A problem occurred calculating the hash code

public abstract String getName ()

Returns the abbreviated name of the type.

Returns
  • String the Hibernate type name

public abstract Class getReturnedClass ()

The class returned by nullSafeGet(ResultSet, String, SessionImplementor, Object) methods. This is used to establish the class of an array of this type.

Returns
  • The java type class handled by this type.

public abstract Type getSemiResolvedType (SessionFactoryImplementor factory)

Get the type of a semi-resolved value.

public abstract Object hydrate (ResultSet rs, String[] names, SessionImplementor session, Object owner)

Retrieve an instance of the mapped class, or the identifier of an entity or collection, from a JDBC resultset. This is useful for 2-phase property initialization - the second phase is a call to resolveIdentifier().

Parameters
names the column names
session the session
owner the parent entity
Returns
  • Object an identifier or actual value
Throws
HibernateException
SQLException
HibernateException

public abstract boolean isAnyType ()

Return true if the implementation is castable to AnyType. Essentially a polymorphic version of (type instanceof AnyType.class).

An AnyType is additionally an AssociationType; so if this method returns true, isAssociationType() should also return true.

Returns
  • True if this type is also an AnyType implementor; false otherwise.

public abstract boolean isAssociationType ()

Return true if the implementation is castable to AssociationType. This does not necessarily imply that the type actually represents an association. Essentially a polymorphic version of (type instanceof AssociationType.class)

Returns
  • True if this type is also an AssociationType implementor; false otherwise.

public abstract boolean isCollectionType ()

Return true if the implementation is castable to CollectionType. Essentially a polymorphic version of (type instanceof CollectionType.class)

A CollectionType is additionally an AssociationType; so if this method returns true, isAssociationType() should also return true.

Returns
  • True if this type is also an CollectionType implementor; false otherwise.

public abstract boolean isComponentType ()

Return true if the implementation is castable to CompositeType. Essentially a polymorphic version of (type instanceof CompositeType.class). A component type may own collections or associations and hence must provide certain extra functionality.

Returns
  • True if this type is also an CompositeType implementor; false otherwise.

public abstract boolean isDirty (Object oldState, Object currentState, boolean[] checkable, SessionImplementor session)

Should the parent be considered dirty, given both the old and current value?

Parameters
oldState the old value
currentState the current value
checkable An array of booleans indicating which columns making up the value are actually checkable
session The session from which the request originated.
Returns
  • true if the field is dirty
Throws
HibernateException A problem occurred performing the checking

public abstract boolean isDirty (Object old, Object current, SessionImplementor session)

Should the parent be considered dirty, given both the old and current value?

Parameters
old the old value
current the current value
session The session from which the request originated.
Returns
  • true if the field is dirty
Throws
HibernateException A problem occurred performing the checking

public abstract boolean isEntityType ()

Return true if the implementation is castable to EntityType. Essentially a polymorphic version of (type instanceof EntityType.class).

An EntityType is additionally an AssociationType; so if this method returns true, isAssociationType() should also return true.

Returns
  • True if this type is also an EntityType implementor; false otherwise.

public abstract boolean isEqual (Object x, Object y, EntityMode entityMode)

Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent state).

This should always equate to some form of comparison of the value's internal state. As an example, for something like a date the comparison should be based on its internal "time" state based on the specific portion it is meant to represent (timestamp, date, time).

Parameters
x The first value
y The second value
entityMode The entity mode of the values.
Returns
  • True if there are considered equal (see discussion above).
Throws
HibernateException A problem occurred performing the comparison

public abstract boolean isEqual (Object x, Object y, EntityMode entityMode, SessionFactoryImplementor factory)

Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent state).

This should always equate to some form of comparison of the value's internal state. As an example, for something like a date the comparison should be based on its internal "time" state based on the specific portion it is meant to represent (timestamp, date, time).

Parameters
x The first value
y The second value
entityMode The entity mode of the values.
factory The session factory
Returns
  • True if there are considered equal (see discussion above).
Throws
HibernateException A problem occurred performing the comparison

public abstract boolean isModified (Object dbState, Object currentState, boolean[] checkable, SessionImplementor session)

Has the value been modified compared to the current database state? The difference between this and the isDirty(Object, Object, boolean[], SessionImplementor) methods is that here we need to account for "partially" built values. This is really only an issue with association types. For most type implementations it is enough to simply delegate to isDirty(Object, Object, boolean[], SessionImplementor) here/

Parameters
dbState the database state, in a "hydrated" form, with identifiers unresolved
currentState the current state of the object
checkable which columns are actually updatable
session The session from which the request originated.
Returns
  • true if the field has been modified
Throws
HibernateException A problem occurred performing the checking

public abstract boolean isMutable ()

Are objects of this type mutable. (With respect to the referencing object ... entities and collections are considered immutable because they manage their own internal state.)

Returns
  • boolean

public abstract boolean isSame (Object x, Object y, EntityMode entityMode)

Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent state) taking a shortcut for entity references.

For most types this should equate to #equals check on the values. For associations the implication is a bit different. For most types it is conceivable to simply delegate to isEqual(Object, Object, EntityMode)

Parameters
x The first value
y The second value
entityMode The entity mode of the values.
Returns
  • True if there are considered the same (see discussion above).
Throws
HibernateException A problem occurred performing the comparison

public abstract boolean isXMLElement ()

public abstract Object nullSafeGet (ResultSet rs, String name, SessionImplementor session, Object owner)

Retrieve an instance of the mapped class from a JDBC resultset. Implementations should handle possibility of null values. This method might be called if the type is known to be a single-column type.

Parameters
name the column name
owner the parent entity
Returns
  • Object
Throws
HibernateException
SQLException
HibernateException

public abstract Object nullSafeGet (ResultSet rs, String[] names, SessionImplementor session, Object owner)

Retrieve an instance of the mapped class from a JDBC resultset. Implementors should handle possibility of null values.

Parameters
names the column names
owner the parent entity
Returns
  • Object
Throws
HibernateException
SQLException
HibernateException

public abstract void nullSafeSet (PreparedStatement st, Object value, int index, boolean[] settable, SessionImplementor session)

Write an instance of the mapped class to a prepared statement, ignoring some columns. Implementors should handle possibility of null values. A multi-column type should be written to parameters starting from index.

Parameters
value the object to write
index statement parameter index
settable an array indicating which columns to ignore
Throws
HibernateException
SQLException
HibernateException

public abstract void nullSafeSet (PreparedStatement st, Object value, int index, SessionImplementor session)

Write an instance of the mapped class to a prepared statement. Implementors should handle possibility of null values. A multi-column type should be written to parameters starting from index.

Parameters
value the object to write
index statement parameter index
Throws
HibernateException
SQLException
HibernateException

public abstract Object replace (Object original, Object target, SessionImplementor session, Object owner, Map copyCache, ForeignKeyDirection foreignKeyDirection)

During merge, replace the existing (target) value in the entity we are merging to with a new (original) value from the detached entity we are merging. For immutable objects, or null values, it is safe to simply return the first parameter. For mutable objects, it is safe to return a copy of the first parameter. For objects with component values, it might make sense to recursively replace component values.

Parameters
original the value from the detached entity being merged
target the value in the managed entity
Returns
  • the value to be merged

public abstract Object replace (Object original, Object target, SessionImplementor session, Object owner, Map copyCache)

During merge, replace the existing (target) value in the entity we are merging to with a new (original) value from the detached entity we are merging. For immutable objects, or null values, it is safe to simply return the first parameter. For mutable objects, it is safe to return a copy of the first parameter. For objects with component values, it might make sense to recursively replace component values.

Parameters
original the value from the detached entity being merged
target the value in the managed entity
Returns
  • the value to be merged

public abstract Object resolve (Object value, SessionImplementor session, Object owner)

Map identifiers to entities or collections. This is the second phase of 2-phase property initialization.

Parameters
value an identifier or value returned by hydrate()
session the session
owner the parent entity
Returns
  • the given value, or the value associated with the identifier

public abstract Object semiResolve (Object value, SessionImplementor session, Object owner)

Given a hydrated, but unresolved value, return a value that may be used to reconstruct property-ref associations.

public abstract void setToXMLNode (Node node, Object value, SessionFactoryImplementor factory)

A representation of the value to be embedded in an XML element.

Returns
  • String

public abstract int[] sqlTypes (Mapping mapping)

Return the JDBC types codes (per java.sql.Types) for the columns mapped by this type.

Parameters
mapping The mapping object :/
Returns
  • The JDBC type codes.
Throws
MappingException Generally indicates an issue accessing the passed mapping object.

public abstract boolean[] toColumnNullness (Object value, Mapping mapping)

Given an instance of the type, return an array of boolean, indicating which mapped columns would be null.

Parameters
value an instance of the type

public abstract String toLoggableString (Object value, SessionFactoryImplementor factory)

A representation of the value to be embedded in a log file.

Returns
  • String