Package org.hibernate

Class 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 createDetachedProxy(SessionFactory, Class, Object) 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 Detail

      • 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

      • 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

      • 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 static boolean isPropertyInitialized​(Object proxy,
                                            String propertyName)
        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 potential proxy
        propertyName - 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

      • 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