Package org.hibernate.usertype

Interface CompositeUserType<J>

All Superinterfaces:
EmbeddableInstantiator, Instantiator
All Known Implementing Classes:
AbstractTimeZoneStorageCompositeUserType, OffsetDateTimeCompositeUserType, OffsetTimeCompositeUserType, ZonedDateTimeCompositeUserType
@Incubating public interface CompositeUserType<J> extends EmbeddableInstantiator
This interface should be implemented by user-defined custom types that have persistent attributes and can be thought of as something more like an embeddable object. However, these persistent "attributes" need not necessarily correspond directly to Java fields or properties.

A value type managed by a CompositeUserType may be used in almost every way that a regular embeddable type may be used. It may even contain many to one associations.

To "map" the attributes of a composite custom type, each CompositeUserType provides a regular embeddable class with the same logical structure as the value type managed by the custom type.

Properties of this embeddable class are sorted alphabetically by name, and assigned an index based on this ordering.

For example, if we were to implement a CompositeUserType for a MonetaryAmount class, we would also provide a MonetaryAmountEmbeddable class with a field for each logical persistent attribute of the custom type. Of course, MonetaryAmountEmbeddable is never instantiated at runtime, and is never referenced in any entity class. It is a source of metadata only.

Here's a full implementation of CompositeUserType for an immutable MonetaryAmount class: 

 public class MonetaryAmountUserType implements CompositeUserType<MonetaryAmount> {

    @Override
    public Object getPropertyValue(MonetaryAmount component, int property) {
         switch ( property ) {
             case 0:
                 return component.getCurrency();
             case 1:
                 return component.getValue();
         }
         throw new HibernateException( "Illegal property index: " + property );
    }

    @Override
    public MonetaryAmount instantiate(ValueAccess valueAccess, SessionFactoryImplementor sessionFactory) {
         final Currency currency = valueAccess.getValue(0, Currency.class);
         final BigDecimal value = valueAccess.getValue(1, BigDecimal.class);

         if ( value == null && currency == null ) {
             return null;
         }
         return new MonetaryAmount( value, currency );
    }

    @Override
    public Class<MonetaryAmountEmbeddable> embeddable() {
         return MonetaryAmountEmbeddable.class;
    }

    @Override
    public Class<MonetaryAmount> returnedClass() {
         return MonetaryAmount.class;
    }

    @Override
    public boolean isMutable() {
         return false;
    }

    @Override
    public MonetaryAmount deepCopy(MonetaryAmount value) {
         return value; // MonetaryAmount is immutable
    }

    @Override
    public boolean equals(MonetaryAmount x, MonetaryAmount y) {
         if ( x == y ) {
             return true;
        }
         if ( x == null || y == null ) {
             return false;
        }
         return x.equals( y );
    }

     @Override
     public Serializable disassemble(MonetaryAmount value) {
         return value;
     }

     @Override
     public MonetaryAmount assemble(Serializable cached, Object owner) {
         return (MonetaryAmount) cached;
     }

     @Override
     public MonetaryAmount replace(MonetaryAmount original, MonetaryAmount target, Object owner) {
         return original;
     }

     @Override
     public int hashCode(MonetaryAmount x) throws HibernateException {
         return x.hashCode();
     }

     // the embeddable class which acts as a source of metadata
     public static class MonetaryAmountEmbeddable {
         private BigDecimal value;
         private Currency currency;
     }
 }

Every implementor of CompositeUserType must be immutable and must declare a public default constructor.

A custom type may be applied to an attribute of an entity either:

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    J
    assemble(Serializable cached, Object owner)
    Reconstruct an object from the cacheable representation.
    J
    deepCopy(J value)
    Return a deep copy of the persistent state, stopping at entities and at collections.
    Serializable
    disassemble(J value)
    Transform the object into its cacheable representation.
    Class<?>
    embeddable()
    The class that represents the embeddable mapping of the type.
    boolean
    equals(J x, J y)
    Compare two instances of the class mapped by this type for persistence "equality".
    Object
    getPropertyValue(J component, int property)
    Get the value of the property with the given index.
    int
    hashCode(J x)
    Get a hashcode for the instance, consistent with persistence "equality"
    J
    instantiate(ValueAccess values)
    Create an instance of the embeddable
    default boolean
    isInstance(Object object)
    Performs and "instance of" check to see if the given object is an instance of managed structure
    boolean
    isMutable()
    Are objects of this type mutable?
    default boolean
    isSameClass(Object object)
     
    J
    replace(J detached, J managed, 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<J>
    returnedClass()
    The class returned by instantiate().

  • Method Details

    • getPropertyValue

      Object getPropertyValue(J component, int property) throws HibernateException
      Get the value of the property with the given index. Properties of the embeddable() are sorted by name and assigned an index based on this ordering.
      Parameters:
      component - an instance of class mapped by this "type"
      property - the property index
      Returns:
      the property value
      Throws:
      HibernateException

    • instantiate

      J instantiate(ValueAccess values)
      Description copied from interface: EmbeddableInstantiator
      Create an instance of the embeddable
      Specified by:
      instantiate in interface EmbeddableInstantiator

    • embeddable

      Class<?> embeddable()
      The class that represents the embeddable mapping of the type.

    • returnedClass

      Class<J> returnedClass()
      The class returned by instantiate().

    • equals

      boolean equals(J x, J y)
      Compare two instances of the class mapped by this type for persistence "equality". Equality of the persistent state.

    • hashCode

      int hashCode(J x)
      Get a hashcode for the instance, consistent with persistence "equality"

    • deepCopy

      J deepCopy(J value)
      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

    • isMutable

      boolean isMutable()
      Are objects of this type mutable?
      Returns:
      boolean

    • disassemble

      Serializable disassemble(J value)
      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 cacheable representation of the object

    • assemble

      J assemble(Serializable cached, Object owner)
      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 cacheable representation

    • replace

      J replace(J detached, J managed, 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. 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:
      detached - the value from the detached entity being merged
      managed - the value in the managed entity
      Returns:
      the value to be merged

    • isInstance

      default boolean isInstance(Object object)
      Description copied from interface: Instantiator
      Performs and "instance of" check to see if the given object is an instance of managed structure
      Specified by:
      isInstance in interface Instantiator
      See Also:

    • isSameClass

      default boolean isSameClass(Object object)
      Specified by:
      isSameClass in interface Instantiator
      See Also: