Package org.hibernate

Class Hibernate

java.lang.Object
org.hibernate.Hibernate

public final class Hibernate extends Object
Various utility functions for working with proxies and lazy collection references.

Operations like isInitialized(Object) and initialize(Object) are of general purpose. But createDetachedProxy(SessionFactory, Class, Object) and Hibernate.CollectionInterface.createDetachedInstance() are intended for use by generic code that must materialize an "amputated" graph of Hibernate entities. (For example, a library which deserializes entities from JSON.)

Lazy fetching of a one to one or many to one association requires special bytecode tricks. The tricks used depend on whether build-time bytecode enhancement is enabled.

When bytecode enhancement is not used, an unfetched lazy association is represented by a proxy object which holds the identifier (foreign key) of the associated entity instance.

  • The identifier property of the proxy object is set when the proxy is instantiated. The program may obtain the entity identifier value of an unfetched proxy, without triggering lazy fetching, by calling the corresponding getter method. (It's even possible to set an association to reference an unfetched proxy.)
  • A delegate entity instance is lazily fetched when any other method of the proxy is called. Once fetched, the proxy delegates all method invocations to the delegate.
  • The proxy does not have the same concrete type as the proxied delegate, and so getClass(Object) must be used in place of Object.getClass(), and this method fetches the entity by side-effect.
  • For a polymorphic association, the concrete type of the associated entity is not known until the delegate is fetched from the database, and so unproxy(Object, Class)} must be used to perform typecasts, and getClass(Object) must be used instead of the Java instanceof operator.
When bytecode enhancement is used, there is no such indirection, but the associated entity instance is initially in an unloaded state, with only its identifier field set.
  • The identifier field of an unloaded entity instance is set when the unloaded instance is instantiated. The program may obtain the identifier of an unloaded entity, without triggering lazy loading, by accessing the field containing the identifier.
  • The remaining non-lazy state of the entity instance is loaded lazily when any other field is accessed.
  • Typecasts, the Java instanceof operator, and Object.getClass() may be used as normal.
As an exception to the above rules, polymorphic associations always work as if bytecode enhancement was not enabled.

Graphs of Hibernate entities obtained from a Session are usually in an amputated form, with associations and collections replaced by proxies and lazy collections. (That is, by instances of the internal types HibernateProxy and PersistentCollection.) These objects are fully serializable using Java serialization, but can cause discomfort when working with custom serialization libraries. Therefore, this class defines operations that may be used to write code that completely removes the amputated leaves of the graph (the proxies) during serialization, and rematerializes and reattaches them during deserialization. It's possible, in principle, to use these operations, together with reflection, or with the Hibernate metamodel, to write such generic code for any given serialization library, but the details depend on what facilities the library itself offers for the program to intervene in the process of serialization and of deserialization.

  • Method Details

    • initialize

      public static void initialize(Object proxy) throws HibernateException
      Force initialization of a proxy or persistent collection. In the case of a many-valued association, only the collection itself is initialized. It is not guaranteed that the associated entities held within the collection will be initialized.
      Parameters:
      proxy - a persistable object, proxy, persistent collection or null
      Throws:
      HibernateException - if the proxy cannot be initialized at this time, for example, if the Session was closed
    • isInitialized

      public static boolean isInitialized(Object proxy)
      Determines if the given proxy or persistent collection is initialized.

      This operation is equivalent to PersistenceUtil.isLoaded(Object).

      Parameters:
      proxy - a persistable object, proxy, persistent collection or null
      Returns:
      true if the argument is already initialized, or is not a proxy or collection
    • size

      public static int size(Collection<?> collection)
      Obtain the size of a persistent collection, without fetching its state from the database.
      Parameters:
      collection - a persistent collection associated with an open session
      Returns:
      the size of the collection
      Since:
      6.1.1
    • isEmpty

      public static boolean isEmpty(Collection<?> collection)
      Determine is the given persistent collection is empty, without fetching its state from the database.
      Parameters:
      collection - a persistent collection associated with an open session
      Returns:
      true if the collection is empty
      Since:
      7.0
    • contains

      public static <T> boolean contains(Collection<? super T> collection, T element)
      Determine if the given persistent collection contains the given element, without fetching its state from the database.
      Parameters:
      collection - a persistent collection associated with an open session
      Returns:
      true if the collection does contain the given element
      Since:
      6.1.1
    • get

      public static <K, V> V get(Map<? super K,V> map, K key)
      Obtain the value associated with the given key by the given persistent map, without fetching the state of the map from the database.
      Parameters:
      map - a persistent map associated with an open session
      key - a key belonging to the map
      Returns:
      the value associated by the map with the given key
      Since:
      6.1.1
    • get

      public static <T> T get(List<T> list, int key)
      Obtain the element of the given persistent list with the given index, without fetching the state of the list from the database.
      Parameters:
      list - a persistent list associated with an open session
      key - an index belonging to the list
      Returns:
      the element of the list with the given index
      Since:
      6.1.1
    • getClass

      public static <T> Class<? extends T> getClass(T proxy)
      Get the true, underlying class of a proxied entity. This operation will initialize a proxy by side effect.
      Parameters:
      proxy - an entity instance or proxy
      Returns:
      the true class of the instance
    • getClassLazy

      public static <T> Class<? extends T> getClassLazy(T proxy)
      Get the true, underlying class of a proxied entity.

      Like getClass(T), this operation might initialize a proxy by side effect. However, here the initialization is avoided if possible. If the entity type is defined with subclasses, the proxy will need to be initialized to properly determine the class.

      Parameters:
      proxy - an entity instance or proxy
      Returns:
      the true class of the instance
      Since:
      6.3
    • isInstance

      public static boolean isInstance(Object proxy, Class<?> entityClass)
      Determine if the true, underlying class of the proxied entity is assignable to the given class. This operation will initialize a proxy by side effect.
      Parameters:
      proxy - an entity instance or proxy
      Returns:
      true if the entity is an instance of the given class
      Since:
      6.2
    • isPropertyInitialized

      public <E> boolean isPropertyInitialized(E entity, Attribute<? super E,?> attribute)
      Determines if the given attribute of the given entity instance is initialized.
      Parameters:
      entity - The entity instance or proxy
      attribute - A persistent attribute of the entity
      Returns:
      true if the named property of the object is not listed as uninitialized; false otherwise
    • isPropertyInitialized

      public static boolean isPropertyInitialized(Object proxy, String attributeName)
      Determines if the property with the given name of the given entity instance is initialized. If the named property does not exist or is not persistent, this method always returns true.

      This operation is equivalent to PersistenceUtil.isLoaded(Object, String).

      Parameters:
      proxy - The entity instance or proxy
      attributeName - the name of a persistent attribute of the object
      Returns:
      true if the named property of the object is not listed as uninitialized; false otherwise
    • initializeProperty

      public static void initializeProperty(Object proxy, String attributeName)
      Initializes the property with the given name of the given entity instance.

      This operation is equivalent to PersistenceUnitUtil.load(Object, String).

      Parameters:
      proxy - The entity instance or proxy
      attributeName - the name of a persistent attribute of the object
    • unproxy

      public static Object unproxy(Object proxy)
      If the given object is not a proxy, return it. But, if it is a proxy, ensure that the proxy is initialized, and return a direct reference to its proxied entity object.
      Parameters:
      proxy - an object which might be a proxy for an entity
      Returns:
      a reference that is never proxied
      Throws:
      LazyInitializationException - if this operation is called on an uninitialized proxy that is not associated with an open session.
    • unproxy

      public static <T> T unproxy(T proxy, Class<T> entityClass)
      If the given object is not a proxy, cast it to the given type, and return it. But, if it is a proxy, ensure that the proxy is initialized, and return a direct reference to its proxied entity object, after casting to the given type.
      Parameters:
      proxy - an object which might be a proxy for an entity
      entityClass - an entity type to cast to
      Returns:
      a reference that is never proxied
      Throws:
      LazyInitializationException - if this operation is called on an uninitialized proxy that is not associated with an open session.
    • createDetachedProxy

      public static <E> E createDetachedProxy(SessionFactory sessionFactory, Class<E> entityClass, Object id)
      Obtain a detached, uninitialized reference (a proxy) for a persistent entity with the given identifier.

      The returned proxy is not associated with any session, and cannot be initialized by calling initialize(Object). It can be used to represent a reference to the entity when working with a detached object graph.

      Parameters:
      sessionFactory - the session factory with which the entity is associated
      entityClass - the entity class
      id - the id of the persistent entity instance
      Returns:
      a detached uninitialized proxy
      Since:
      6.0
    • bag

      public static <U> Hibernate.CollectionInterface<Collection<U>> bag()
      Obtain an instance of Hibernate.CollectionInterface representing persistent bags of a given element type.
      Type Parameters:
      U - the element type
      Since:
      6.0
    • set

      public static <U> Hibernate.CollectionInterface<Set<U>> set()
      Obtain an instance of Hibernate.CollectionInterface representing persistent sets of a given element type.
      Type Parameters:
      U - the element type
      Since:
      6.0
    • list

      public static <U> Hibernate.CollectionInterface<List<U>> list()
      Obtain an instance of Hibernate.CollectionInterface representing persistent lists of a given element type.
      Type Parameters:
      U - the element type
      Since:
      6.0
    • map

      public static <U, V> Hibernate.CollectionInterface<Map<U,V>> map()
      Obtain an instance of Hibernate.CollectionInterface representing persistent maps of a given key and value types.
      Type Parameters:
      U - the key type
      V - the value type
      Since:
      6.0
    • sortedSet

      public static <U> Hibernate.CollectionInterface<SortedSet<U>> sortedSet()
      Obtain an instance of Hibernate.CollectionInterface representing sorted persistent sets of a given element type.
      Type Parameters:
      U - the element type
      Since:
      6.0
    • sortedMap

      public static <U, V> Hibernate.CollectionInterface<Map<U,V>> sortedMap()
      Obtain an instance of Hibernate.CollectionInterface representing sorted persistent maps of a given key and value types.
      Type Parameters:
      U - the key type
      V - the value type
      Since:
      6.0
    • collection

      public static <C> Hibernate.CollectionInterface<C> collection(Class<C> collectionClass)
      Obtain an instance of Hibernate.CollectionInterface representing persistent collections of the given type.
      Parameters:
      collectionClass - the Java class object representing the collection type
      Since:
      6.0