Package org.hibernate.usertype

Interface UserType

  • All Known Subinterfaces:
    EnhancedUserType, UserVersionType
    All Known Implementing Classes:
    EnumType
    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.
    See Also:
    for more complex cases, Type

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.lang.Object assemble​(java.io.Serializable cached, java.lang.Object owner)
      Reconstruct an object from the cacheable representation.
      java.lang.Object deepCopy​(java.lang.Object value)
      Return a deep copy of the persistent state, stopping at entities and at collections.
      java.io.Serializable disassemble​(java.lang.Object value)
      Transform the object into its cacheable representation.
      boolean equals​(java.lang.Object x, java.lang.Object y)
      Compare two instances of the class mapped by this type for persistence "equality".
      int hashCode​(java.lang.Object x)
      Get a hashcode for the instance, consistent with persistence "equality"
      boolean isMutable()
      Are objects of this type mutable?
      java.lang.Object nullSafeGet​(java.sql.ResultSet rs, java.lang.String[] names, SharedSessionContractImplementor session, java.lang.Object owner)
      Retrieve an instance of the mapped class from a JDBC resultset.
      void nullSafeSet​(java.sql.PreparedStatement st, java.lang.Object value, int index, SharedSessionContractImplementor session)
      Write an instance of the mapped class to a prepared statement.
      java.lang.Object replace​(java.lang.Object original, java.lang.Object target, java.lang.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.
      java.lang.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

        java.lang.Class returnedClass()
        The class returned by nullSafeGet().
        Returns:
        Class

      • equals

        boolean equals​(java.lang.Object x,
               java.lang.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

      • nullSafeGet

        java.lang.Object nullSafeGet​(java.sql.ResultSet rs,
                             java.lang.String[] names,
                             SharedSessionContractImplementor session,
                             java.lang.Object owner)
                      throws HibernateException,
                             java.sql.SQLException
        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
        session -
        owner - the containing entity @return Object
        Throws:
        HibernateException
        java.sql.SQLException

      • nullSafeSet

        void nullSafeSet​(java.sql.PreparedStatement st,
                 java.lang.Object value,
                 int index,
                 SharedSessionContractImplementor session)
          throws HibernateException,
                 java.sql.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.
        Parameters:
        st - a JDBC prepared statement
        value - the object to write
        index - statement parameter index
        session -
        Throws:
        HibernateException
        java.sql.SQLException

      • deepCopy

        java.lang.Object deepCopy​(java.lang.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

        java.io.Serializable disassemble​(java.lang.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

        java.lang.Object assemble​(java.io.Serializable cached,
                          java.lang.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

        java.lang.Object replace​(java.lang.Object original,
                         java.lang.Object target,
                         java.lang.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