Open Source Repository

Home /hibernate/hibernate-3.2.4.ga | Repository Home


org/hibernate/usertype/CompositeUserType.java
//$Id: CompositeUserType.java 6471 2005-04-19 20:36:59Z oneovthafew $
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.SessionImplementor;
import org.hibernate.type.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.
   *
   @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 propertythrows 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 valuethrows HibernateException;

  /**
   * The class returned by <tt>nullSafeGet()</tt>.
   *
   @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 ythrows HibernateException;
  
  /**
   * Get a hashcode for the instance, consistent with persistence "equality"
   */
  public int hashCode(Object xthrows 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</tt>.
   *
   @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 valuethrows 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 sessionthrows 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;
}