http://hibernate.org: The core O/RM functionality as provided by Hibernate (Hibernate.org) 
/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2010, Red Hat Inc. or third-party contributors as
 * indicated by the @author tags or express copyright attribution
 * statements applied by the authors.  All third-party contributions are
 * distributed under license by Red Hat Inc.
 *
 * This copyrighted material is made available to anyone wishing to use, modify,
 * copy, or redistribute it subject to the terms and conditions of the GNU
 * Lesser General Public License, as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this distribution; if not, write to:
 * Free Software Foundation, Inc.
 * 51 Franklin Street, Fifth Floor
 * Boston, MA  02110-1301  USA
 */
package org.hibernate.type;

import java.io.Serializable;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Map;

import org.hibernate.HibernateException;
import org.hibernate.MappingException;
import org.hibernate.engine.spi.Mapping;
import org.hibernate.engine.spi.SessionFactoryImplementor;
import org.hibernate.engine.spi.SessionImplementor;
import org.hibernate.metamodel.relational.Size;

import org.dom4j.Node;


Defines a mapping between a Java type and one or more JDBC 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.

Author:Gavin King, Steve Ebersole
/**
 * Defines a mapping between a Java type and one or more JDBC {@linkplain 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).
 * <p/>
 * 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) {@link org.hibernate.usertype.UserType}
 * interface.
 * <p/>
 * 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.
 *
 * @author Gavin King
 * @author Steve Ebersole
 */
public interface Type extends Serializable {
	
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.
/**
	 * Return true if the implementation is castable to {@link AssociationType}. This does not necessarily imply that
	 * the type actually represents an association.  Essentially a polymorphic version of
	 * {@code (type instanceof AssociationType.class)}
	 *
	 * @return True if this type is also an {@link AssociationType} implementor; false otherwise.
	 */
	public boolean isAssociationType();

	
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.
/**
	 * Return true if the implementation is castable to {@link CollectionType}. Essentially a polymorphic version of
	 * {@code (type instanceof CollectionType.class)}
	 * <p/>
	 * A {@link CollectionType} is additionally an {@link AssociationType}; so if this method returns true,
	 * {@link #isAssociationType()} should also return true.
	 *
	 * @return True if this type is also an {@link CollectionType} implementor; false otherwise.
	 */
	public boolean isCollectionType();

	
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.
/**
	 * Return true if the implementation is castable to {@link EntityType}. Essentially a polymorphic
	 * version of {@code (type instanceof EntityType.class)}.
	 * <p/>
	 * An {@link EntityType} is additionally an {@link AssociationType}; so if this method returns true,
	 * {@link #isAssociationType()} should also return true.
	 *
	 * @return True if this type is also an {@link EntityType} implementor; false otherwise.
	 */
	public boolean isEntityType();

	
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.
/**
	 * Return true if the implementation is castable to {@link AnyType}. Essentially a polymorphic
	 * version of {@code (type instanceof AnyType.class)}.
	 * <p/>
	 * An {@link AnyType} is additionally an {@link AssociationType}; so if this method returns true,
	 * {@link #isAssociationType()} should also return true.
	 *
	 * @return True if this type is also an {@link AnyType} implementor; false otherwise.
	 */
	public boolean isAnyType();

	
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.
/**
	 * Return true if the implementation is castable to {@link CompositeType}. Essentially a polymorphic
	 * version of {@code (type instanceof CompositeType.class)}.  A component type may own collections or
	 * associations and hence must provide certain extra functionality.
	 *
	 * @return True if this type is also an {@link CompositeType} implementor; false otherwise.
	 */
	public boolean isComponentType();

	
How many columns are used to persist this type. Always the same as sqlTypes(mapping).length 
Params:
  • mapping – The mapping object :/
Throws:
  • MappingException – Generally indicates an issue accessing the passed mapping object.
Returns:The number of columns
/**
	 * How many columns are used to persist this type.  Always the same as {@code sqlTypes(mapping).length}
	 *
	 * @param mapping The mapping object :/
	 *
	 * @return The number of columns
	 *
	 * @throws MappingException Generally indicates an issue accessing the passed mapping object.
	 */
	public int getColumnSpan(Mapping mapping) throws MappingException;

	
Return the JDBC types codes (per Types) for the columns mapped by this type. 
 NOTE: The number of elements in this array matches the return from getColumnSpan. 
Params:
  • mapping – The mapping object :/
Throws:
  • MappingException – Generally indicates an issue accessing the passed mapping object.
Returns:The JDBC type codes.
/**
	 * Return the JDBC types codes (per {@link java.sql.Types}) for the columns mapped by this type.
	 * <p/>
	 * NOTE: The number of elements in this array matches the return from {@link #getColumnSpan}.
	 *
	 * @param mapping The mapping object :/
	 *
	 * @return The JDBC type codes.
	 *
	 * @throws MappingException Generally indicates an issue accessing the passed mapping object.
	 */
	public int[] sqlTypes(Mapping mapping) throws MappingException;

	
Return the column sizes dictated by this type. For example, the mapping for a char/Character would have a dictated length limit of 1; for a string-based UUID would have a size limit of 36; etc. 
 NOTE: The number of elements in this array matches the return from getColumnSpan. 
Params:
  • mapping – The mapping object :/
Throws:
  • MappingException – Generally indicates an issue accessing the passed mapping object.
@todoWould be much much better to have this aware of Dialect once the service/metamodel split is done
Returns:The dictated sizes.
/**
	 * Return the column sizes dictated by this type.  For example, the mapping for a {@code char}/{@link Character} would
	 * have a dictated length limit of 1; for a string-based {@link java.util.UUID} would have a size limit of 36; etc.
	 * <p/>
	 * NOTE: The number of elements in this array matches the return from {@link #getColumnSpan}.
	 *
	 * @param mapping The mapping object :/
	 * @todo Would be much much better to have this aware of Dialect once the service/metamodel split is done
	 *
	 * @return The dictated sizes.
	 *
	 * @throws MappingException Generally indicates an issue accessing the passed mapping object.
	 */
	public Size[] dictatedSizes(Mapping mapping) throws MappingException;

	
Defines the column sizes to use according to this type if the user did not explicitly say (and if no dictatedSizes were given). 
 NOTE: The number of elements in this array matches the return from getColumnSpan. 
Params:
  • mapping – The mapping object :/
Throws:
  • MappingException – Generally indicates an issue accessing the passed mapping object.
@todoWould be much much better to have this aware of Dialect once the service/metamodel split is done
Returns:The default sizes.
/**
	 * Defines the column sizes to use according to this type if the user did not explicitly say (and if no
	 * {@link #dictatedSizes} were given).
	 * <p/>
	 * NOTE: The number of elements in this array matches the return from {@link #getColumnSpan}.
	 *
	 * @param mapping The mapping object :/
	 * @todo Would be much much better to have this aware of Dialect once the service/metamodel split is done
	 *
	 * @return The default sizes.
	 *
	 * @throws MappingException Generally indicates an issue accessing the passed mapping object.
	 */
	public Size[] defaultSizes(Mapping mapping) throws MappingException;

	
The class returned by nullSafeGet methods. This is used to establish the class of an array of this type. 
Returns:The java type class handled by this type.
/**
	 * The class returned by {@link #nullSafeGet} methods. This is used to  establish the class of an array of
	 * this type.
	 *
	 * @return The java type class handled by this type.
	 */
	public Class getReturnedClass();

	
Deprecated:To be removed in 5.  Removed as part of removing the notion of DOM entity-mode.
See Jira issue: HHH-7771
/**
	 * @deprecated To be removed in 5.  Removed as part of removing the notion of DOM entity-mode.
	 * See Jira issue: <a href="https://hibernate.onjira.com/browse/HHH-7771">HHH-7771</a>
	 */
	@SuppressWarnings( {"UnusedDeclaration"})
	@Deprecated
	public boolean isXMLElement();

	
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 an equals check on the values. For associations the implication is a bit different. For most types it is conceivable to simply delegate to isEqual 
Params:
  • x – The first value
  • y – The second value
Throws:
Returns:True if there are considered the same (see discussion above).
/**
	 * Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent
	 * state) taking a shortcut for entity references.
	 * <p/>
	 * For most types this should equate to an {@link Object#equals equals} check on the values.  For associations
	 * the implication is a bit different.  For most types it is conceivable to simply delegate to {@link #isEqual}
	 *
	 * @param x The first value
	 * @param y The second value
	 *
	 * @return True if there are considered the same (see discussion above).
	 *
	 * @throws HibernateException A problem occurred performing the comparison
	 */
	public boolean isSame(Object x, Object y) throws HibernateException;

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

Params:
  • x – The first value
  • y – The second value
Throws:
Returns:True if there are considered equal (see discussion above).
/**
	 * Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent
	 * state).
	 * <p/>
	 * 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).
	 *
	 * @param x The first value
	 * @param y The second value
	 *
	 * @return True if there are considered equal (see discussion above).
	 *
	 * @throws HibernateException A problem occurred performing the comparison
	 */
	public boolean isEqual(Object x, Object y) throws HibernateException;

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

Params:
  • x – The first value
  • y – The second value
  • factory – The session factory
Throws:
Returns:True if there are considered equal (see discussion above).
/**
	 * Compare two instances of the class mapped by this type for persistence "equality" (equality of persistent
	 * state).
	 * <p/>
	 * 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).
	 *
	 * @param x The first value
	 * @param y The second value
	 * @param factory The session factory
	 *
	 * @return True if there are considered equal (see discussion above).
	 *
	 * @throws HibernateException A problem occurred performing the comparison
	 */
	public boolean isEqual(Object x, Object y, SessionFactoryImplementor factory) throws HibernateException;

	
Get a hash code, consistent with persistence "equality". Again for most types the normal usage is to delegate to the value's hashCode. 
Params:
  • x – The value for which to retrieve a hash code
Throws:
Returns:The hash code
/**
	 * Get a hash code, consistent with persistence "equality".  Again for most types the normal usage is to
	 * delegate to the value's {@link Object#hashCode hashCode}.
	 *
	 * @param x The value for which to retrieve a hash code
	 * @return The hash code
	 *
	 * @throws HibernateException A problem occurred calculating the hash code
	 */
	public int getHashCode(Object x) throws HibernateException;

	
Get a hash code, consistent with persistence "equality". Again for most types the normal usage is to delegate to the value's hashCode. 
Params:
  • x – The value for which to retrieve a hash code
  • factory – The session factory
Throws:
Returns:The hash code
/**
	 * Get a hash code, consistent with persistence "equality".  Again for most types the normal usage is to
	 * delegate to the value's {@link Object#hashCode hashCode}.
	 *
	 * @param x The value for which to retrieve a hash code
	 * @param factory The session factory
	 *
	 * @return The hash code
	 *
	 * @throws HibernateException A problem occurred calculating the hash code
	 */
	public int getHashCode(Object x, SessionFactoryImplementor factory) throws HibernateException;
	
	
Perform a Comparator style comparison between values 
Params:
  • x – The first value
  • y – The second value
Returns:The comparison result. See Comparator.compare for a discussion.
/**
	 * Perform a {@link java.util.Comparator} style comparison between values
	 *
	 * @param x The first value
	 * @param y The second value
	 *
	 * @return The comparison result.  See {@link java.util.Comparator#compare} for a discussion.
	 */
	public int compare(Object x, Object y);

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

Params:
  • old – the old value
  • current – the current value
  • session – The session from which the request originated.
Throws:
Returns:true if the field is dirty
/**
	 * Should the parent be considered dirty, given both the old and current value?
	 * 
	 * @param old the old value
	 * @param current the current value
	 * @param session The session from which the request originated.
	 *
	 * @return true if the field is dirty
	 *
	 * @throws HibernateException A problem occurred performing the checking
	 */
	public boolean isDirty(Object old, Object current, SessionImplementor session) throws HibernateException;

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

Params:
  • 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.
Throws:
Returns:true if the field is dirty
/**
	 * Should the parent be considered dirty, given both the old and current value?
	 *
	 * @param oldState the old value
	 * @param currentState the current value
	 * @param checkable An array of booleans indicating which columns making up the value are actually checkable
	 * @param session The session from which the request originated.
	 *
	 * @return true if the field is dirty
	 *
	 * @throws HibernateException A problem occurred performing the checking
	 */
	public boolean isDirty(Object oldState, Object currentState, boolean[] checkable, SessionImplementor session)
			throws HibernateException;

	
Has the value been modified compared to the current database state? The difference between this and the isDirty 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 here/ 
Params:
  • 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.
Throws:
Returns:true if the field has been modified
/**
	 * Has the value been modified compared to the current database state?  The difference between this
	 * and the {@link #isDirty} 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
	 * {@link #isDirty} here/
	 *
	 * @param dbState the database state, in a "hydrated" form, with identifiers unresolved
	 * @param currentState the current state of the object
	 * @param checkable which columns are actually updatable
	 * @param session The session from which the request originated.
	 *
	 * @return true if the field has been modified
	 *
	 * @throws HibernateException A problem occurred performing the checking
	 */
	public boolean isModified(Object dbState, Object currentState, boolean[] checkable, SessionImplementor session)
			throws HibernateException;

	
Extract a value of the mapped class from the JDBC result set. Implementors should handle possibility of null values. 
Params:
  • rs – The result set from which to extract value.
  • names – the column names making up this type value (use to read from result set)
  • session – The originating session
  • owner – the parent entity
Throws:
See Also:
Returns:The extracted value
/**
	 * Extract a value of the {@link #getReturnedClass() mapped class} from the JDBC result set. Implementors
	 * should handle possibility of null values.
	 *
	 * @param rs The result set from which to extract value.
	 * @param names the column names making up this type value (use to read from result set)
	 * @param session The originating session
	 * @param owner the parent entity
	 *
	 * @return The extracted value
	 *
	 * @throws HibernateException An error from Hibernate
	 * @throws SQLException An error from the JDBC driver
	 *
	 * @see Type#hydrate(ResultSet, String[], SessionImplementor, Object) alternative, 2-phase property initialization
	 */
	public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor session, Object owner)
	throws HibernateException, SQLException;

	
Extract a value of the mapped class from the JDBC result set. Implementors should handle possibility of null values. This form might be called if the type is known to be a single-column type. 
Params:
  • rs – The result set from which to extract value.
  • name – the column name making up this type value (use to read from result set)
  • session – The originating session
  • owner – the parent entity
Throws:
Returns:The extracted value
/**
	 * Extract a value of the {@link #getReturnedClass() mapped class} from the JDBC result set. Implementors
	 * should handle possibility of null values.  This form might be called if the type is known to be a
	 * single-column type.
	 *
	 * @param rs The result set from which to extract value.
	 * @param name the column name making up this type value (use to read from result set)
	 * @param session The originating session
	 * @param owner the parent entity
	 *
	 * @return The extracted value
	 *
	 * @throws HibernateException An error from Hibernate
	 * @throws SQLException An error from the JDBC driver
	 */
	public Object nullSafeGet(ResultSet rs, String name, SessionImplementor session, Object owner)
	throws HibernateException, SQLException;

	
Bind a value represented by an instance of the mapped class to the JDBC prepared statement, ignoring some columns as dictated by the 'settable' parameter. Implementors should handle the possibility of null values. A multi-column type should bind parameters starting from index.

Params:
  • st – The JDBC prepared statement to which to bind
  • value – the object to write
  • index – starting parameter bind index
  • settable – an array indicating which columns to bind/ignore
  • session – The originating session
Throws:
/**
	 * Bind a value represented by an instance of the {@link #getReturnedClass() mapped class} to the JDBC prepared
	 * statement, ignoring some columns as dictated by the 'settable' parameter.  Implementors should handle the
	 * possibility of null values.  A multi-column type should bind parameters starting from <tt>index</tt>.
	 *
	 * @param st The JDBC prepared statement to which to bind
	 * @param value the object to write
	 * @param index starting parameter bind index
	 * @param settable an array indicating which columns to bind/ignore
	 * @param session The originating session
	 *
	 * @throws HibernateException An error from Hibernate
	 * @throws SQLException An error from the JDBC driver
	 */
	public void nullSafeSet(PreparedStatement st, Object value, int index, boolean[] settable, SessionImplementor session)
	throws HibernateException, SQLException;

	
Bind a value represented by an instance of the mapped class to the JDBC prepared statement. Implementors should handle possibility of null values. A multi-column type should bind parameters starting from index.

Params:
  • st – The JDBC prepared statement to which to bind
  • value – the object to write
  • index – starting parameter bind index
  • session – The originating session
Throws:
/**
	 * Bind a value represented by an instance of the {@link #getReturnedClass() mapped class} to the JDBC prepared
	 * statement.  Implementors should handle possibility of null values.  A multi-column type should bind parameters
	 * starting from <tt>index</tt>.
	 *
	 * @param st The JDBC prepared statement to which to bind
	 * @param value the object to write
	 * @param index starting parameter bind index
	 * @param session The originating session
	 *
	 * @throws HibernateException An error from Hibernate
	 * @throws SQLException An error from the JDBC driver
	 */
	public void nullSafeSet(PreparedStatement st, Object value, int index, SessionImplementor session)
	throws HibernateException, SQLException;

	
Generate a representation of the value for logging purposes.

Params:
  • value – The value to be logged
  • factory – The session factory
Throws:
Returns:The loggable representation
/**
	 * Generate a representation of the value for logging purposes.
	 *
	 * @param value The value to be logged
	 * @param factory The session factory
	 *
	 * @return The loggable representation
	 *
	 * @throws HibernateException An error from Hibernate
	 */
	public String toLoggableString(Object value, SessionFactoryImplementor factory)
	throws HibernateException;

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

Params:
  • node – The XML node to which to write the value
  • value – The value to write
  • factory – The session factory
Throws:
Deprecated:To be removed in 5.  Removed as part of removing the notion of DOM entity-mode.
See Jira issue: HHH-7771
/**
	 * A representation of the value to be embedded in an XML element.
	 *
	 * @param node The XML node to which to write the value
	 * @param value The value to write
	 * @param factory The session factory
	 *
	 * @throws HibernateException An error from Hibernate
	 *
	 * @deprecated To be removed in 5.  Removed as part of removing the notion of DOM entity-mode.
	 * See Jira issue: <a href="https://hibernate.onjira.com/browse/HHH-7771">HHH-7771</a>
	 */
	@Deprecated
	public void setToXMLNode(Node node, Object value, SessionFactoryImplementor factory)
	throws HibernateException;

	
Parse the XML representation of an instance.

Params:
  • xml – The XML node from which to read the value
  • factory – The session factory
Throws:
Returns:an instance of the mapped class
Deprecated:To be removed in 5.  Removed as part of removing the notion of DOM entity-mode.
See Jira issue: HHH-7771
/**
	 * Parse the XML representation of an instance.
	 *
	 * @param xml The XML node from which to read the value
	 * @param factory The session factory
	 *
	 * @return an instance of the {@link #getReturnedClass() mapped class}
	 *
	 * @throws HibernateException An error from Hibernate
	 *
	 * @deprecated To be removed in 5.  Removed as part of removing the notion of DOM entity-mode.
	 * See Jira issue: <a href="https://hibernate.onjira.com/browse/HHH-7771">HHH-7771</a>
	 */
	@Deprecated
	public Object fromXMLNode(Node xml, Mapping factory) throws HibernateException;

	
Returns the abbreviated name of the type.

Returns:String the Hibernate type name
/**
	 * Returns the abbreviated name of the type.
	 *
	 * @return String the Hibernate type name
	 */
	public String getName();

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

Params:
  • value – The value to be copied
  • factory – The session factory
Throws:
Returns:The deep copy
/**
	 * Return a deep copy of the persistent state, stopping at entities and at collections.
	 *
	 * @param value The value to be copied
	 * @param factory The session factory
	 *
	 * @return The deep copy
	 *
	 * @throws HibernateException An error from Hibernate
	 */
	public Object deepCopy(Object value, SessionFactoryImplementor factory)
	throws HibernateException;

	
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
/**
	 * 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.)
	 *
	 * @return boolean
	 */
	public boolean isMutable();

	
Return a disassembled representation of the object.  This is the value Hibernate will use in second level
caching, so care should be taken to break values down to their simplest forms; for entities especially, this
means breaking them down into their constituent parts.

Params:
  • value – the value to cache
  • session – the originating session
  • owner – optional parent entity object (needed for collections)
Throws:
Returns:the disassembled, deep cloned state
/**
	 * Return a disassembled representation of the object.  This is the value Hibernate will use in second level
	 * caching, so care should be taken to break values down to their simplest forms; for entities especially, this
	 * means breaking them down into their constituent parts.
	 *
	 * @param value the value to cache
	 * @param session the originating session
	 * @param owner optional parent entity object (needed for collections)
	 *
	 * @return the disassembled, deep cloned state
	 *
	 * @throws HibernateException An error from Hibernate
	 */
	public Serializable disassemble(Object value, SessionImplementor session, Object owner) throws HibernateException;

	
Reconstruct the object from its disassembled state. This method is the reciprocal of disassemble 
Params:
  • cached – the disassembled state from the cache
  • session – the originating session
  • owner – the parent entity object
Throws:
Returns:the (re)assembled object
/**
	 * Reconstruct the object from its disassembled state.  This method is the reciprocal of {@link #disassemble}
	 *
	 * @param cached the disassembled state from the cache
	 * @param session the originating session
	 * @param owner the parent entity object
	 *
	 * @return the (re)assembled object
	 *
	 * @throws HibernateException An error from Hibernate
	 */
	public Object assemble(Serializable cached, SessionImplementor session, Object owner)
	throws HibernateException;
	
	
Called before assembling a query result set from the query cache, to allow batch fetching
of entities missing from the second-level cache.

Params:
  • cached – The key
  • session – The originating session
/**
	 * Called before assembling a query result set from the query cache, to allow batch fetching
	 * of entities missing from the second-level cache.
	 *
	 * @param cached The key
	 * @param session The originating session
	 */
	public void beforeAssemble(Serializable cached, SessionImplementor session);

	
Extract a value from the JDBC result set. This is useful for 2-phase property initialization - the second phase is a call to resolve This hydrated value will be either:
    
    
  • in the case of an entity or collection type, the key
    • 
    
  • otherwise, the value itself
    • 



Params:
  • rs – The JDBC result set
  • names – the column names making up this type value (use to read from result set)
  • session – The originating session
  • owner – the parent entity
Throws:
See Also:
Returns:An entity or collection key, or an actual value.
/**
	 * Extract a value from the JDBC result set.  This is useful for 2-phase property initialization - the second
	 * phase is a call to {@link #resolve}
	 * This hydrated value will be either:<ul>
	 *     <li>in the case of an entity or collection type, the key</li>
	 *     <li>otherwise, the value itself</li>
	 * </ul>
	 * 
	 * @param rs The JDBC result set
	 * @param names the column names making up this type value (use to read from result set)
	 * @param session The originating session
	 * @param owner the parent entity
	 *
	 * @return An entity or collection key, or an actual value.
	 *
	 * @throws HibernateException An error from Hibernate
	 * @throws SQLException An error from the JDBC driver
	 *
	 * @see #resolve
	 */
	public Object hydrate(ResultSet rs, String[] names, SessionImplementor session, Object owner)
	throws HibernateException, SQLException;

	
The second phase of 2-phase loading.  Only really pertinent for entities and collections.  Here we resolve the
identifier to an entity or collection instance

Params:
  • value – an identifier or value returned by hydrate()
  • owner – the parent entity
  • session – the session
Throws:
See Also:
Returns:the given value, or the value associated with the identifier
/**
	 * The second phase of 2-phase loading.  Only really pertinent for entities and collections.  Here we resolve the
	 * identifier to an entity or collection instance
	 * 
	 * @param value an identifier or value returned by <tt>hydrate()</tt>
	 * @param owner the parent entity
	 * @param session the session
	 * 
	 * @return the given value, or the value associated with the identifier
	 *
	 * @throws HibernateException An error from Hibernate
	 *
	 * @see #hydrate
	 */
	public Object resolve(Object value, SessionImplementor session, Object owner)
	throws HibernateException;
	
	
Given a hydrated, but unresolved value, return a value that may be used to reconstruct property-ref
associations.

Params:
  • value – The unresolved, hydrated value
  • session – THe originating session
  • owner – The value owner
Throws:
Returns:The semi-resolved value
/**
	 * Given a hydrated, but unresolved value, return a value that may be used to reconstruct property-ref
	 * associations.
	 *
	 * @param value The unresolved, hydrated value
	 * @param session THe originating session
	 * @param owner The value owner
	 *
	 * @return The semi-resolved value
	 *
	 * @throws HibernateException An error from Hibernate
	 */
	public Object semiResolve(Object value, SessionImplementor session, Object owner)
	throws HibernateException;
	
	
As part of 2-phase loading, when we perform resolving what is the resolved type for this type?  Generally
speaking the type and its semi-resolved type will be the same.  The main deviation from this is in the
case of an entity where the type would be the entity type and semi-resolved type would be its identifier type

Params:
  • factory – The session factory
Returns:The semi-resolved type
/**
	 * As part of 2-phase loading, when we perform resolving what is the resolved type for this type?  Generally
	 * speaking the type and its semi-resolved type will be the same.  The main deviation from this is in the
	 * case of an entity where the type would be the entity type and semi-resolved type would be its identifier type
	 *
	 * @param factory The session factory
	 *
	 * @return The semi-resolved type
	 */
	public Type getSemiResolvedType(SessionFactoryImplementor factory);

	
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.

Params:
  • original – the value from the detached entity being merged
  • target – the value in the managed entity
  • session – The originating session
  • owner – The owner of the value
  • copyCache – The cache of already copied/replaced values
Throws:
Returns:the value to be merged
/**
	 * 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.
	 *
	 * @param original the value from the detached entity being merged
	 * @param target the value in the managed entity
	 * @param session The originating session
	 * @param owner The owner of the value
	 * @param copyCache The cache of already copied/replaced values
	 *
	 * @return the value to be merged
	 *
	 * @throws HibernateException An error from Hibernate
	 */
	public Object replace(
			Object original, 
			Object target, 
			SessionImplementor session, 
			Object owner, 
			Map copyCache) throws HibernateException;
	
	
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.

Params:
  • original – the value from the detached entity being merged
  • target – the value in the managed entity
  • session – The originating session
  • owner – The owner of the value
  • copyCache – The cache of already copied/replaced values
  • foreignKeyDirection – For associations, which direction does the foreign key point?
Throws:
Returns:the value to be merged
/**
	 * 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.
	 *
	 * @param original the value from the detached entity being merged
	 * @param target the value in the managed entity
	 * @param session The originating session
	 * @param owner The owner of the value
	 * @param copyCache The cache of already copied/replaced values
	 * @param foreignKeyDirection For associations, which direction does the foreign key point?
	 *
	 * @return the value to be merged
	 *
	 * @throws HibernateException An error from Hibernate
	 */
	public Object replace(
			Object original, 
			Object target, 
			SessionImplementor session, 
			Object owner, 
			Map copyCache, 
			ForeignKeyDirection foreignKeyDirection) throws HibernateException;
	
	
Given an instance of the type, return an array of boolean, indicating
which mapped columns would be null.

Params:
  • value – an instance of the type
  • mapping – The mapping abstraction
Returns:array indicating column nullness for a value instance
/**
	 * Given an instance of the type, return an array of boolean, indicating
	 * which mapped columns would be null.
	 * 
	 * @param value an instance of the type
	 * @param mapping The mapping abstraction
	 *
	 * @return array indicating column nullness for a value instance
	 */
	public boolean[] toColumnNullness(Object value, Mapping mapping);
	
}