## org.hibernate.usertype
Interface UserType

All Known Subinterfaces:
  EnhancedUserType, UserVersionType

All Known Implementing Classes:
  EnumType, RevisionTypeType, StringClobType

    public interface UserType

This interface should be implemented by user-defined "types". A "type" class is not the actual property type - it is a class that knows how to serialize instances of another class to and from JDBC.
This interface

- abstracts user code from future changes to the `Type` interface,
- simplifies the implementation of custom types and
- hides certain "internal" interfaces from user code.

Implementors must be immutable and must declare a public default constructor.
The actual class mapped by a `UserType` may be just about anything.
`CompositeUserType` provides an extended version of this interface that is useful for more complex cases.
Alternatively, custom types could implement `Type` directly or extend one of the abstract classes in `org.hibernate.type`. This approach risks future incompatible changes to classes or interfaces in that package.

Author:
  Gavin King
See Also:
  `for more complex cases`, `Type`

Method Summary
`Object` `assemble(Serializable cached, Object owner)` Reconstruct an object from the cacheable representation.
`Object` `deepCopy(Object value)` Return a deep copy of the persistent state, stopping at entities and at collections.
`Serializable` `disassemble(Object value)` Transform the object into its cacheable representation.
`boolean` `equals(Object x, Object y)` Compare two instances of the class mapped by this type for persistence "equality".
`int` `hashCode(Object x)` Get a hashcode for the instance, consistent with persistence "equality"
`boolean` `isMutable()` Are objects of this type mutable?
`Object` `nullSafeGet(ResultSet rs, String[] names, Object owner)` Deprecated. SessionImplementor will be added as an argument in a future version (see HHH-5968)
`void` `nullSafeSet(PreparedStatement st, Object value, int index)` Deprecated. SessionImplementor will be added as an argument in a future version (see HHH-5968)
`Object` `replace(Object original, Object target, Object owner)` 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.
`Class` `returnedClass()` The class returned by `nullSafeGet()`.
`int[]` `sqlTypes()` Return the SQL type codes for the columns mapped by this type.

Method Detail

### sqlTypes

    int[] sqlTypes()

  Return the SQL type codes for the columns mapped by this type. The codes are defined on `java.sql.Types`.

  Returns:
    int[] the typecodes
  See Also:
    `Types`

### returnedClass

    Class returnedClass()

  The class returned by `nullSafeGet()`.

  Returns:
    Class

### equals

    boolean equals(Object x,
                   Object y)
                   throws HibernateException

  Compare two instances of the class mapped by this type for persistence "equality". Equality of the persistent state.

  Parameters:
    `x` -
    `y` -
  Returns:
    boolean
  Throws:
    `HibernateException`

### hashCode

    int hashCode(Object x)
                 throws HibernateException

  Get a hashcode for the instance, consistent with persistence "equality"

  Throws:
    `HibernateException`

### nullSafeGet

    Object nullSafeGet(ResultSet rs,
                       String[] names,
                       Object owner)
                       throws HibernateException,
                              SQLException

  Deprecated. SessionImplementor will be added as an argument in a future version (see HHH-5968)

  Retrieve an instance of the mapped class from a JDBC resultset. Implementors should handle possibility of null values.

  Parameters:
    `rs` - a JDBC result set
    `names` - the column names
    `owner` - the containing entity
  Returns:
    Object
  Throws:
    `HibernateException`
    `SQLException`

### nullSafeSet

    void nullSafeSet(PreparedStatement st,
                     Object value,
                     int index)
                     throws HibernateException,
                            SQLException

  Deprecated. SessionImplementor will be added as an argument in a future version (see HHH-5968)

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

  Parameters:
    `st` - a JDBC prepared statement
    `value` - the object to write
    `index` - statement parameter index
  Throws:
    `HibernateException`
    `SQLException`

### deepCopy

    Object deepCopy(Object value)
                    throws HibernateException

  Return a deep copy of the persistent state, stopping at entities and at collections. It is not necessary to copy immutable objects, or null values, in which case it is safe to simply return the argument.

  Parameters:
    `value` - the object to be cloned, which may be null
  Returns:
    Object a copy
  Throws:
    `HibernateException`

### isMutable

    boolean isMutable()

  Are objects of this type mutable?

  Returns:
    boolean

### disassemble

    Serializable disassemble(Object value)
                             throws HibernateException

  Transform the object into its cacheable representation. At the very least this method should perform a deep copy if the type is mutable. That may not be enough for some implementations, however; for example, associations must be cached as identifier values. (optional operation)

  Parameters:
    `value` - the object to be cached
  Returns:
    a cachable representation of the object
  Throws:
    `HibernateException`

### assemble

    Object assemble(Serializable cached,
                    Object owner)
                    throws HibernateException

  Reconstruct an object from the cacheable representation. At the very least this method should perform a deep copy if the type is mutable. (optional operation)

  Parameters:
    `cached` - the object to be cached
    `owner` - the owner of the cached object
  Returns:
    a reconstructed object from the cachable representation
  Throws:
    `HibernateException`

### replace

    Object replace(Object original,
                   Object target,
                   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. For objects with component values, it might make sense to recursively replace component values.

  Parameters:
    `original` - the value from the detached entity being merged
    `target` - the value in the managed entity
  Returns:
    the value to be merged
  Throws:
    `HibernateException`

Copyright © 2001-2010 Red Hat, Inc. All Rights Reserved.