/*
 * 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.usertype;
import java.io.Serializable;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

import org.hibernate.HibernateException;
import org.hibernate.engine.spi.SharedSessionContractImplementor;
import org.hibernate.type.Type;

A UserType that may be dereferenced in a query.
This interface allows a custom type to define "properties".
These need not necessarily correspond to physical JavaBeans
style properties.



A CompositeUserType may be used in almost every way
that a component may be used. It may even contain many-to-one
associations.



Implementors must be immutable and must declare a public
default constructor.



Unlike UserType, cacheability does not depend upon
serializability. Instead, assemble() and
disassemble provide conversion to/from a cacheable
representation.
Author:
Gavin King
See Also:
for more simple cases
Type/**
 * A <tt>UserType</tt> that may be dereferenced in a query.
 * This interface allows a custom type to define "properties".
 * These need not necessarily correspond to physical JavaBeans
 * style properties.<br>
 * <br>
 * A <tt>CompositeUserType</tt> may be used in almost every way
 * that a component may be used. It may even contain many-to-one
 * associations.<br>
 * <br>
 * Implementors must be immutable and must declare a public
 * default constructor.<br>
 * <br>
 * Unlike <tt>UserType</tt>, cacheability does not depend upon
 * serializability. Instead, <tt>assemble()</tt> and
 * <tt>disassemble</tt> provide conversion to/from a cacheable
 * representation.
 *
 * @see UserType for more simple cases
 * @see org.hibernate.type.Type
 * @author Gavin King
 */
public interface CompositeUserType {

	
Get the "property names" that may be used in a
query.
Returns:
an array of "property names"/**
	 * Get the "property names" that may be used in a
	 * query.
	 *
	 * @return an array of "property names"
	 */
	String[] getPropertyNames();

	
Get the corresponding "property types".
Returns:
an array of Hibernate types/**
	 * Get the corresponding "property types".
	 *
	 * @return an array of Hibernate types
	 */
	Type[] getPropertyTypes();

	
Get the value of a property.
Params:
component – an instance of class mapped by this "type"
property – 
Throws:
HibernateException – 
Returns:
the property value/**
	 * Get the value of a property.
	 *
	 * @param component an instance of class mapped by this "type"
	 * @param property
	 * @return the property value
	 * @throws HibernateException
	 */
	Object getPropertyValue(Object component, int property) throws HibernateException;

	
Set the value of a property.
Params:
component – an instance of class mapped by this "type"
property – 
value – the value to set
Throws:
HibernateException – /**
	 * Set the value of a property.
	 *
	 * @param component an instance of class mapped by this "type"
	 * @param property
	 * @param value the value to set
	 * @throws HibernateException
	 */
	void setPropertyValue(Object component, int property, Object value) throws HibernateException;

	
The class returned by nullSafeGet().
Returns:
Class/**
	 * The class returned by <tt>nullSafeGet()</tt>.
	 *
	 * @return Class
	 */
	Class returnedClass();

	
Compare two instances of the class mapped by this type for persistence "equality".
Equality of the persistent state.
Throws:
HibernateException – /**
	 * Compare two instances of the class mapped by this type for persistence "equality".
	 * Equality of the persistent state.
     *
	 * @throws HibernateException
	 */
	boolean equals(Object x, Object y) throws HibernateException;
	
	
Get a hashcode for the instance, consistent with persistence "equality"
/**
	 * Get a hashcode for the instance, consistent with persistence "equality"
	 */
	int hashCode(Object x) throws HibernateException;

	
Retrieve an instance of the mapped class from a JDBC resultset. Implementors
should handle possibility of null values.
Params:
rs – a JDBC result set
names – the column names
session – 
owner – the containing entity
Throws:
HibernateException – 
SQLException – 
Returns:
Object/**
	 * Retrieve an instance of the mapped class from a JDBC resultset. Implementors
	 * should handle possibility of null values.
	 *
	 * @param rs a JDBC result set
	 * @param names the column names
	 * @param session
	 * @param owner the containing entity
	 * @return Object
	 * @throws HibernateException
	 * @throws SQLException
	 */
	Object nullSafeGet(ResultSet rs, String[] names, SharedSessionContractImplementor session, Object owner) throws HibernateException, SQLException;

	
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.
Params:
st – a JDBC prepared statement
value – the object to write
index – statement parameter index
session – 
Throws:
HibernateException – 
SQLException – /**
	 * 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 <tt>index</tt>.
	 *
	 * @param st a JDBC prepared statement
	 * @param value the object to write
	 * @param index statement parameter index
	 * @param session
	 * @throws HibernateException
	 * @throws SQLException
	 */
	void nullSafeSet(PreparedStatement st, Object value, int index, SharedSessionContractImplementor session) throws HibernateException, SQLException;

	
Return a deep copy of the persistent state, stopping at entities and at collections.
Params:
value – generally a collection element or entity field
Throws:
HibernateException – 
Returns:
Object a copy/**
	 * Return a deep copy of the persistent state, stopping at entities and at collections.
	 *
	 * @param value generally a collection element or entity field
	 * @return Object a copy
	 * @throws HibernateException
	 */
	Object deepCopy(Object value) throws HibernateException;

	
Check if objects of this type mutable.
Returns:
boolean/**
	 * Check if objects of this type mutable.
	 *
	 * @return boolean
	 */
	boolean isMutable();

	
Transform the object into its cacheable representation. At the very least this
method should perform a deep copy. That may not be enough for some implementations,
however; for example, associations must be cached as identifier values. (optional
operation)
Params:
value – the object to be cached
session – 
Throws:
HibernateException – 
Returns:
a cachable representation of the object/**
	 * Transform the object into its cacheable representation. At the very least this
	 * method should perform a deep copy. That may not be enough for some implementations,
	 * however; for example, associations must be cached as identifier values. (optional
	 * operation)
	 *
	 * @param value the object to be cached
	 * @param session
	 * @return a cachable representation of the object
	 * @throws HibernateException
	 */
	Serializable disassemble(Object value, SharedSessionContractImplementor session) throws HibernateException;

	
Reconstruct an object from the cacheable representation. At the very least this
method should perform a deep copy. (optional operation)
Params:
cached – the object to be cached
session – 
owner – the owner of the cached object
Throws:
HibernateException – 
Returns:
a reconstructed object from the cachable representation/**
	 * Reconstruct an object from the cacheable representation. At the very least this
	 * method should perform a deep copy. (optional operation)
	 *
	 * @param cached the object to be cached
	 * @param session
	 * @param owner the owner of the cached object
	 * @return a reconstructed object from the cachable representation
	 * @throws HibernateException
	 */
	Object assemble(Serializable cached, SharedSessionContractImplementor session, Object owner) 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. However, since
composite user types often define component values, it might make sense to recursively
replace component values in the target object.
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. However, since
	 * composite user types often define component values, it might make sense to recursively
	 * replace component values in the target object.
	 *
	 * @throws HibernateException
	 */
	Object replace(Object original, Object target, SharedSessionContractImplementor session, Object owner) throws HibernateException;
}