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

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	Hibernate.CollectionInterface< the type of collection, for example, `List<User>` C> Operations for obtaining references to persistent collections of a certain type.

Access	Constructor and Description
private	Hibernate() Cannot be instantiated.

Method Summary

Modifier and Type	Method and Description
public static < the element type U> Hibernate.CollectionInterface<Collection<U>>	bag() Obtain an instance of `CollectionInterface` representing persistent bags of a given element type.
public static <C> Hibernate.CollectionInterface<C>	collection(Class<C> the Java class object representing the collection type collectionClass) Obtain an instance of `CollectionInterface` representing persistent collections of the given type.
public static <T> boolean	Returns: true if the collection does contain the given element contains(Collection<? super T> a persistent collection associated with an open session collection, T element) Determine if the given persistent collection contains the given element, without fetching its state from the database.
public static <E> E	Returns: a detached uninitialized proxy createDetachedProxy(SessionFactory the session factory with which the entity is associated sessionFactory, Class<E> the entity class entityClass, Object the id of the persistent entity instance id) Obtain a detached, uninitialized reference (a proxy) for a persistent entity with the given identifier.
public static <K, V> V	Returns: the value associated by the map with the given key get(Map<? super K, V> a persistent map associated with an open session map, K a key belonging to the map key) Obtain the value associated with the given key by the given persistent map, without fetching the state of the map from the database.
public static <T> T	Returns: the element of the list with the given index get(List<T> a persistent list associated with an open session list, int an index belonging to the list key) Obtain the element of the given persistent list with the given index, without fetching the state of the list from the database.
public static <T> Class<? extends T>	Returns: the true class of the instance getClass(T an entity instance or proxy proxy) Get the true, underlying class of a proxied entity.
public static <T> Class<? extends T>	Returns: the true class of the instance getClassLazy(T an entity instance or proxy proxy) Get the true, underlying class of a proxied entity.
public static void	initialize(Object a persistable object, proxy, persistent collection or `null` proxy) Force initialization of a proxy or persistent collection.
public static boolean	Returns: true if the argument is already initialized, or is not a proxy or collection isInitialized(Object a persistable object, proxy, persistent collection or `null` proxy) Determines if the given proxy or persistent collection is initialized.
public static boolean	Returns: `true` if the entity is an instance of the given class isInstance(Object an entity instance or proxy proxy, Class<?> entityClass) Determine if the true, underlying class of the proxied entity is assignable to the given class.
public <E> boolean	Returns: true if the named property of the object is not listed as uninitialized; false otherwise isPropertyInitialized(E The entity instance or proxy entity, Attribute<? super E, ?> A persistent attribute of the entity attribute) Determines if the given attribute of the given entity instance is initialized.
public static boolean	Returns: true if the named property of the object is not listed as uninitialized; false otherwise isPropertyInitialized(Object The entity instance or proxy proxy, String the name of a persistent attribute of the object attributeName) Determines if the property with the given name of the given entity instance is initialized.
public static < the element type U> Hibernate.CollectionInterface<List<U>>	list() Obtain an instance of `CollectionInterface` representing persistent lists of a given element type.
public static < the key type U, the value type V> Hibernate.CollectionInterface<Map<U, V>>	map() Obtain an instance of `CollectionInterface` representing persistent maps of a given key and value types.
public static < the element type U> Hibernate.CollectionInterface<Set<U>>	set() Obtain an instance of `CollectionInterface` representing persistent sets of a given element type.
public static int	Returns: the size of the collection size(Collection<?> a persistent collection associated with an open session collection) Obtain the size of a persistent collection, without fetching its state from the database.
public static < the key type U, the value type V> Hibernate.CollectionInterface<Map<U, V>>	sortedMap() Obtain an instance of `CollectionInterface` representing sorted persistent maps of a given key and value types.
public static < the element type U> Hibernate.CollectionInterface<SortedSet<U>>	sortedSet() Obtain an instance of `CollectionInterface` representing sorted persistent sets of a given element type.
public static Object	Returns: a reference that is never proxied unproxy(Object an object which might be a proxy for an entity proxy) If the given object is not a proxy, return it.
public static <T> T	Returns: a reference that is never proxied unproxy(T an object which might be a proxy for an entity proxy, Class<T> an entity type to cast to entityClass) If the given object is not a proxy, cast it to the given type, and return it.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

Hibernate	back to summary
private Hibernate() Cannot be instantiated.

Method Detail

bag back to summary

bag	back to summary
public static <U> Hibernate.CollectionInterface<Collection<U>> bag() Obtain an instance of `CollectionInterface` representing persistent bags of a given element type. Parameters <U> the element type Since 6.0

public static Hibernate.CollectionInterface<Collection> bag()

Obtain an instance of CollectionInterface representing persistent bags of a given element type.

Parameters

: the element type

Since

6.0

collection back to summary

collection	back to summary
public static <C> Hibernate.CollectionInterface<C> collection(Class<C> collectionClass) Obtain an instance of `CollectionInterface` representing persistent collections of the given type. Parameters collectionClass:Class<C> the Java class object representing the collection type Annotations @SuppressWarnings:unchecked Since 6.0

public static <C> Hibernate.CollectionInterface<C> collection(Class<C> collectionClass)

Obtain an instance of CollectionInterface representing persistent collections of the given type.

Parameters

collectionClass:Class<C>: the Java class object representing the collection type

Annotations

@SuppressWarnings:unchecked

Since

6.0

contains	back to summary
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:Collection<? super T> a persistent collection associated with an open session Returns:boolean true if the collection does contain the given element Since 6.1.1

contains

back to summary

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:Collection<? super T>: a persistent collection associated with an open session

Returns:boolean

true if the collection does contain the given element

Since

6.1.1

createDetachedProxy back to summary

createDetachedProxy	back to summary
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:SessionFactory the session factory with which the entity is associated entityClass:Class<E> the entity class id:Object the id of the persistent entity instance Returns:E a detached uninitialized proxy Annotations @SuppressWarnings:unchecked Since 6.0

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:SessionFactory: the session factory with which the entity is associated
entityClass:Class<E>: the entity class
id:Object: the id of the persistent entity instance

Returns:E

a detached uninitialized proxy

Annotations

@SuppressWarnings:unchecked

Since

6.0

get	back to summary
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:Map<? super K, V> a persistent map associated with an open session key:K a key belonging to the map Returns:V the value associated by the map with the given key Since 6.1.1

get

back to summary

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:Map<? super K, V>: a persistent map associated with an open session
key:K: a key belonging to the map

Returns:V

the value associated by the map with the given key

Since

6.1.1

get	back to summary
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:List<T> a persistent list associated with an open session key:int an index belonging to the list Returns:T the element of the list with the given index Since 6.1.1

get

back to summary

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:List<T>: a persistent list associated with an open session
key:int: an index belonging to the list

Returns:T

the element of the list with the given index

Since

6.1.1

getClass	back to summary
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:T an entity instance or proxy Returns:Class<? extends T> the true class of the instance Annotations @SuppressWarnings:unchecked

getClass

back to summary

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:T: an entity instance or proxy

Returns:Class<? extends T>

the true class of the instance

Annotations

@SuppressWarnings:unchecked

getClassLazy back to summary

getClassLazy	back to summary
public static <T> Class<? extends T> getClassLazy(T proxy) Get the true, underlying class of a proxied entity. Like `getClass`, 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:T an entity instance or proxy Returns:Class<? extends T> the true class of the instance Annotations @SuppressWarnings:unchecked

public static <T> Class<? extends T> getClassLazy(T proxy)

Get the true, underlying class of a proxied entity.

Like getClass, 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:T: an entity instance or proxy

Returns:Class<? extends T>

the true class of the instance

Annotations

@SuppressWarnings:unchecked

initialize back to summary

initialize	back to summary
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:Object a persistable object, proxy, persistent collection or `null` Exceptions HibernateException: if the proxy cannot be initialized at this time, for example, if the `Session` was closed

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:Object: a persistable object, proxy, persistent collection or null

Exceptions

HibernateException:: if the proxy cannot be initialized at this time, for example, if the Session was closed

isInitialized back to summary

isInitialized	back to summary
public static boolean isInitialized(Object proxy) Determines if the given proxy or persistent collection is initialized. This operation is equivalent to `jakarta.persistence.PersistenceUtil#isLoaded(Object)`. Parameters proxy:Object a persistable object, proxy, persistent collection or `null` Returns:boolean true if the argument is already initialized, or is not a proxy or collection

public static boolean isInitialized(Object proxy)

Determines if the given proxy or persistent collection is initialized.

This operation is equivalent to jakarta.persistence.PersistenceUtil#isLoaded(Object).

Parameters

proxy:Object: a persistable object, proxy, persistent collection or null

Returns:boolean

true if the argument is already initialized, or is not a proxy or collection

isInstance back to summary

isInstance	back to summary
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:Object an entity instance or proxy Returns:boolean `true` if the entity is an instance of the given class Since 6.2

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:Object: an entity instance or proxy

Returns:boolean

true if the entity is an instance of the given class

Since

6.2

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

isPropertyInitialized

back to summary

public <E> boolean isPropertyInitialized(E entity, Attribute<? super E, ?> attribute)

Determines if the given attribute of the given entity instance is initialized.

Parameters

entity:E: The entity instance or proxy
attribute:Attribute<? super E, ?>: A persistent attribute of the entity

Returns:boolean

true if the named property of the object is not listed as uninitialized; false otherwise

isPropertyInitialized back to summary

isPropertyInitialized	back to summary
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 `jakarta.persistence.PersistenceUtil#isLoaded(Object, String)`. Parameters proxy:Object The entity instance or proxy attributeName:String the name of a persistent attribute of the object Returns:boolean true if the named property of the object is not listed as uninitialized; false otherwise

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 jakarta.persistence.PersistenceUtil#isLoaded(Object, String).

Parameters

proxy:Object: The entity instance or proxy
attributeName:String: the name of a persistent attribute of the object

Returns:boolean

true if the named property of the object is not listed as uninitialized; false otherwise

list back to summary

list	back to summary
public static <U> Hibernate.CollectionInterface<List<U>> list() Obtain an instance of `CollectionInterface` representing persistent lists of a given element type. Parameters <U> the element type Since 6.0

public static Hibernate.CollectionInterface<List> list()

Obtain an instance of CollectionInterface representing persistent lists of a given element type.

Parameters

: the element type

Since

6.0

map back to summary

map	back to summary
public static <U, V> Hibernate.CollectionInterface<Map<U, V>> map() Obtain an instance of `CollectionInterface` representing persistent maps of a given key and value types. Parameters <U> the key type <V> the value type Since 6.0

public static <U, V> Hibernate.CollectionInterface<Map<U, V>> map()

Obtain an instance of CollectionInterface representing persistent maps of a given key and value types.

Parameters

: the key type
<V>: the value type

Since

6.0

set back to summary

set	back to summary
public static <U> Hibernate.CollectionInterface<Set<U>> set() Obtain an instance of `CollectionInterface` representing persistent sets of a given element type. Parameters <U> the element type Since 6.0

public static Hibernate.CollectionInterface<Set> set()

Obtain an instance of CollectionInterface representing persistent sets of a given element type.

Parameters

: the element type

Since

6.0

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

size

back to summary

public static int size(Collection<?> collection)

Obtain the size of a persistent collection, without fetching its state from the database.

Parameters

collection:Collection<?>: a persistent collection associated with an open session

Returns:int

the size of the collection

Since

6.1.1

sortedMap back to summary

sortedMap	back to summary
public static <U, V> Hibernate.CollectionInterface<Map<U, V>> sortedMap() Obtain an instance of `CollectionInterface` representing sorted persistent maps of a given key and value types. Parameters <U> the key type <V> the value type Since 6.0

public static <U, V> Hibernate.CollectionInterface<Map<U, V>> sortedMap()

Obtain an instance of CollectionInterface representing sorted persistent maps of a given key and value types.

Parameters

: the key type
<V>: the value type

Since

6.0

sortedSet back to summary

sortedSet	back to summary
public static <U> Hibernate.CollectionInterface<SortedSet<U>> sortedSet() Obtain an instance of `CollectionInterface` representing sorted persistent sets of a given element type. Parameters <U> the element type Since 6.0

public static Hibernate.CollectionInterface<SortedSet> sortedSet()

Obtain an instance of CollectionInterface representing sorted persistent sets of a given element type.

Parameters

: the element type

Since

6.0

unproxy	back to summary
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:Object an object which might be a proxy for an entity Returns:Object a reference that is never proxied Exceptions LazyInitializationException: if this operation is called on an uninitialized proxy that is not associated with an open session.

unproxy

back to summary

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:Object: an object which might be a proxy for an entity

Returns:Object

a reference that is never proxied

Exceptions

LazyInitializationException:: if this operation is called on an uninitialized proxy that is not associated with an open session.

unproxy	back to summary
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:T an object which might be a proxy for an entity entityClass:Class<T> an entity type to cast to Returns:T a reference that is never proxied Exceptions LazyInitializationException: if this operation is called on an uninitialized proxy that is not associated with an open session.

unproxy

back to summary

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:T: an object which might be a proxy for an entity
entityClass:Class<T>: an entity type to cast to

Returns:T

a reference that is never proxied

Exceptions

LazyInitializationException:: if this operation is called on an uninitialized proxy that is not associated with an open session.

org.hibernate back to summary

public final Class Hibernate.CollectionInterface<C>

Class Inheritance

extends Object

java.lang.Object
org.hibernate.Hibernate.CollectionInterface

Type Parameters

<C>: the type of collection, for example, List<User>

Operations for obtaining references to persistent collections of a certain type.

Since: 6.0

Field Summary

Modifier and Type	Field and Description
private final Supplier<C>	created
private final Supplier<C>	detached

Constructor Summary

Access	Constructor and Description
private	CollectionInterface(Supplier<C> detached, Supplier<C> created)

Method Summary

Modifier and Type	Method and Description
public C	Returns: an uninitialized persistent collection createDetachedInstance() Obtain a detached, uninitialized persistent collection of the type represented by this object.
public C	Returns: a newly-instantiated empty collection createNewInstance() Instantiate an empty collection of the type represented by this object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

created	back to summary
private final Supplier<C> created

detached	back to summary
private final Supplier<C> detached

Constructor Detail

CollectionInterface	back to summary
private CollectionInterface(Supplier<C> detached, Supplier<C> created)

Method Detail

createDetachedInstance back to summary

createDetachedInstance	back to summary
public C createDetachedInstance() Obtain a detached, uninitialized persistent collection of the type represented by this object. The returned wrapper object is not associated with any session, and cannot be initialized by calling `initialize(Object)`. It can be used to represent an uninitialized collection when working with a detached object graph. Returns:C an uninitialized persistent collection

public C createDetachedInstance()

Obtain a detached, uninitialized persistent collection of the type represented by this object.

The returned wrapper object is not associated with any session, and cannot be initialized by calling initialize(Object). It can be used to represent an uninitialized collection when working with a detached object graph.

Returns:C: an uninitialized persistent collection

createNewInstance	back to summary
public C createNewInstance() Instantiate an empty collection of the type represented by this object. Returns:C a newly-instantiated empty collection

createNewInstance

back to summary

public C createNewInstance()

Instantiate an empty collection of the type represented by this object.

Returns:C: a newly-instantiated empty collection