/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
 */
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.jdbc.Size;
import org.hibernate.engine.spi.Mapping;
import org.hibernate.engine.spi.SessionFactoryImplementor;
import org.hibernate.engine.spi.SharedSessionContractImplementor;

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.
	 */
	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 a 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 a {@link CollectionType} implementor; false otherwise.
	 */
	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.
	 */
	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.
	 */
	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 a 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 a {@link CompositeType} implementor; false otherwise.
	 */
	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.
	 */
	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.
	 */
	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.
@todo
Would 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.
	 */
	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.
@todo
Would 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.
	 */
	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.
	 */
	Class getReturnedClass();

	
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:
HibernateException – A problem occurred performing the comparison
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
	 */
	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:
HibernateException – A problem occurred performing the comparison
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
	 */
	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:
HibernateException – A problem occurred performing the comparison
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
	 */
	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:
HibernateException – A problem occurred calculating the hash code
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
	 */
	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:
HibernateException – A problem occurred calculating the hash code
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
	 */
	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.
	 */
	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:
HibernateException – A problem occurred performing the checking
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
	 */
	boolean isDirty(Object old, Object current, SharedSessionContractImplementor 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:
HibernateException – A problem occurred performing the checking
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
	 */
	boolean isDirty(Object oldState, Object currentState, boolean[] checkable, SharedSessionContractImplementor 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:
HibernateException – A problem occurred performing the checking
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
	 */
	boolean isModified(
			Object dbState,
			Object currentState,
			boolean[] checkable,
			SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
SQLException – An error from the JDBC driver
See Also:
alternative, 2-phase property initialization
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[], SharedSessionContractImplementor, Object) alternative, 2-phase property initialization
	 */
	Object nullSafeGet(ResultSet rs, String[] names, SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
SQLException – An error from the JDBC driver
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
	 */
	Object nullSafeGet(ResultSet rs, String name, SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
SQLException – An error from the JDBC driver/**
	 * 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
	 */
	void nullSafeSet(
			PreparedStatement st,
			Object value,
			int index,
			boolean[] settable,
			SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
SQLException – An error from the JDBC driver/**
	 * 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
	 */
	void nullSafeSet(PreparedStatement st, Object value, int index, SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
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
	 */
	String toLoggableString(Object value, SessionFactoryImplementor 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
	 */
	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:
HibernateException – An error from Hibernate
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
	 */
	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
	 */
	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:
HibernateException – An error from Hibernate
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
	 */
	Serializable disassemble(Object value, SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
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
	 */
	Object assemble(Serializable cached, SharedSessionContractImplementor 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
	 */
	void beforeAssemble(Serializable cached, SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
SQLException – An error from the JDBC driver
See Also:
resolve
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
	 */
	Object hydrate(ResultSet rs, String[] names, SharedSessionContractImplementor session, Object owner)
	throws HibernateException, SQLException;

	
See Also:
resolve(Object, SharedSessionContractImplementor, Object, Boolean)/**
	 * @see #resolve(Object, SharedSessionContractImplementor, Object, Boolean)
	 */
	Object resolve(Object value, SharedSessionContractImplementor session, Object owner)
	throws HibernateException;

	
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
overridingEager – can override eager from the mapping. For example because of LoadQueryInfluencers If null, then it does not override. If true or false then it overrides the mapping value.
Throws:
HibernateException – An error from Hibernate
See Also:
hydrate
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
	 * @param overridingEager can override eager from the mapping. For example because of {@link org.hibernate.engine.spi.LoadQueryInfluencers}
	 *   If null, then it does not override. If true or false then it overrides the mapping value.
	 *
	 * @return the given value, or the value associated with the identifier
	 *
	 * @throws HibernateException An error from Hibernate
	 *
	 * @see #hydrate
	 */
	default Object resolve(Object value, SharedSessionContractImplementor session, Object owner, Boolean overridingEager)
	throws HibernateException {
		return resolve(value, session, owner);
	}

	
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:
HibernateException – An error from Hibernate
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
	 */
	Object semiResolve(Object value, SharedSessionContractImplementor 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
	 */
	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:
HibernateException – An error from Hibernate
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
	 */
	Object replace(
			Object original,
			Object target,
			SharedSessionContractImplementor 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:
HibernateException – An error from Hibernate
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
	 */
	Object replace(
			Object original,
			Object target,
			SharedSessionContractImplementor 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
	 */
	boolean[] toColumnNullness(Object value, Mapping mapping);
	
}