Hibernate example source code file (CompositeUserType.java)

This example Hibernate source code file (CompositeUserType.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Hibernate tags/keywords

class, compositeusertype, hibernateexception, hibernateexception, io, jdbc, object, object, serializable, sessionimplementor, sessionimplementor, sql, sqlexception, sqlexception, string, type

The Hibernate CompositeUserType.java source code

/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * Copyright (c) 2008, Red Hat Middleware LLC 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 Middleware LLC.
 *
 * 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.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.SessionImplementor;
import org.hibernate.type.Type;

/**
 * A <tt>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.<br>
 * <br>
 * A <tt>CompositeUserType 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, cacheability does not depend upon
 * serializability. Instead, <tt>assemble() and
 * <tt>disassemble 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.
	 *
	 * @return an array of "property names"
	 */
	public String[] getPropertyNames();

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

	/**
	 * Get the value of a property.
	 *
	 * @param component an instance of class mapped by this "type"
	 * @param property
	 * @return the property value
	 * @throws HibernateException
	 */
	public Object getPropertyValue(Object component, int property) 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
	 */
	public void setPropertyValue(Object component, int property, Object value) throws HibernateException;

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

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

	/**
	 * 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
	 */
	public Object nullSafeGet(ResultSet rs, String[] names, SessionImplementor 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 <tt>index.
	 *
	 * @param st a JDBC prepared statement
	 * @param value the object to write
	 * @param index statement parameter index
	 * @param session
	 * @throws HibernateException
	 * @throws SQLException
	 */
	public void nullSafeSet(PreparedStatement st, Object value, int index, SessionImplementor session) 
	throws HibernateException, SQLException;

	/**
	 * 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
	 */
	public Object deepCopy(Object value) throws HibernateException;

	/**
	 * Check if objects of this type mutable.
	 *
	 * @return boolean
	 */
	public 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)
	 *
	 * @param value the object to be cached
	 * @param session
	 * @return a cachable representation of the object
	 * @throws HibernateException
	 */
	public Serializable disassemble(Object value, SessionImplementor session) throws HibernateException;

	/**
	 * 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
	 */
	public Object assemble(Serializable cached, SessionImplementor 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.
	 * 
	 * @param original
	 * @param target
	 * @param session
	 * @param owner
	 * @return
	 * @throws HibernateException
	 */
	public Object replace(Object original, Object target, SessionImplementor session, Object owner) 
	throws HibernateException;
}