Class Hibernate
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 ofObject.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, andgetClass(Object)
must be used instead of the Javainstanceof
operator.
- 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, andObject.getClass()
may be used as normal.
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 Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
Operations for obtaining references to persistent collections of a certain type. -
Method Summary
Modifier and TypeMethodDescriptionstatic <U> Hibernate.CollectionInterface<Collection<U>>
bag()
Obtain an instance ofHibernate.CollectionInterface
representing persistent bags of a given element type.static <C> Hibernate.CollectionInterface<C>
collection
(Class<C> collectionClass) Obtain an instance ofHibernate.CollectionInterface
representing persistent collections of the given type.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.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.static <T> T
Obtain the element of the given persistent list with the given index, without fetching the state of the list from the database.static <K,
V> V Obtain the value associated with the given key by the given persistent map, without fetching the state of the map from the database.static <T> Class<? extends T>
getClass
(T proxy) Get the true, underlying class of a proxied entity.static <T> Class<? extends T>
getClassLazy
(T proxy) Get the true, underlying class of a proxied entity.static void
initialize
(Object proxy) Force initialization of a proxy or persistent collection.static void
initializeProperty
(Object proxy, String attributeName) Initializes the property with the given name of the given entity instance.static boolean
isEmpty
(Collection<?> collection) Determine is the given persistent collection is empty, without fetching its state from the database.static boolean
isInitialized
(Object proxy) Determines if the given proxy or persistent collection is initialized.static boolean
isInstance
(Object proxy, Class<?> entityClass) Determine if the true, underlying class of the proxied entity is assignable to the given class.<E> boolean
isPropertyInitialized
(E entity, Attribute<? super E, ?> attribute) Determines if the given attribute of the given entity instance is initialized.static boolean
isPropertyInitialized
(Object proxy, String attributeName) Determines if the property with the given name of the given entity instance is initialized.static <U> Hibernate.CollectionInterface<List<U>>
list()
Obtain an instance ofHibernate.CollectionInterface
representing persistent lists of a given element type.static <U,
V> Hibernate.CollectionInterface<Map<U, V>> map()
Obtain an instance ofHibernate.CollectionInterface
representing persistent maps of a given key and value types.static <U> Hibernate.CollectionInterface<Set<U>>
set()
Obtain an instance ofHibernate.CollectionInterface
representing persistent sets of a given element type.static int
size
(Collection<?> collection) Obtain the size of a persistent collection, without fetching its state from the database.static <U,
V> Hibernate.CollectionInterface<Map<U, V>> Obtain an instance ofHibernate.CollectionInterface
representing sorted persistent maps of a given key and value types.static <U> Hibernate.CollectionInterface<SortedSet<U>>
Obtain an instance ofHibernate.CollectionInterface
representing sorted persistent sets of a given element type.static Object
If the given object is not a proxy, return it.static <T> T
If the given object is not a proxy, cast it to the given type, and return it.
-
Method Details
-
initialize
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 ornull
- Throws:
HibernateException
- if the proxy cannot be initialized at this time, for example, if theSession
was closed
-
isInitialized
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 ornull
- Returns:
- true if the argument is already initialized, or is not a proxy or collection
-
size
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
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
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
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 sessionkey
- a key belonging to the map- Returns:
- the value associated by the map with the given key
- Since:
- 6.1.1
-
get
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 sessionkey
- an index belonging to the list- Returns:
- the element of the list with the given index
- Since:
- 6.1.1
-
getClass
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
Get the true, underlying class of a proxied entity. LikegetClass(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
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
Determines if the given attribute of the given entity instance is initialized.- Parameters:
entity
- The entity instance or proxyattribute
- A persistent attribute of the entity- Returns:
- true if the named property of the object is not listed as uninitialized; false otherwise
-
isPropertyInitialized
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 returnstrue
.This operation is equivalent to
PersistenceUtil.isLoaded(Object, String)
.- Parameters:
proxy
- The entity instance or proxyattributeName
- 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
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 proxyattributeName
- the name of a persistent attribute of the object
-
unproxy
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
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 entityentityClass
- 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 associatedentityClass
- the entity classid
- the id of the persistent entity instance- Returns:
- a detached uninitialized proxy
- Since:
- 6.0
-
bag
Obtain an instance ofHibernate.CollectionInterface
representing persistent bags of a given element type.- Type Parameters:
U
- the element type- Since:
- 6.0
-
set
Obtain an instance ofHibernate.CollectionInterface
representing persistent sets of a given element type.- Type Parameters:
U
- the element type- Since:
- 6.0
-
list
Obtain an instance ofHibernate.CollectionInterface
representing persistent lists of a given element type.- Type Parameters:
U
- the element type- Since:
- 6.0
-
map
Obtain an instance ofHibernate.CollectionInterface
representing persistent maps of a given key and value types.- Type Parameters:
U
- the key typeV
- the value type- Since:
- 6.0
-
sortedSet
Obtain an instance ofHibernate.CollectionInterface
representing sorted persistent sets of a given element type.- Type Parameters:
U
- the element type- Since:
- 6.0
-
sortedMap
Obtain an instance ofHibernate.CollectionInterface
representing sorted persistent maps of a given key and value types.- Type Parameters:
U
- the key typeV
- the value type- Since:
- 6.0
-
collection
Obtain an instance ofHibernate.CollectionInterface
representing persistent collections of the given type.- Parameters:
collectionClass
- the Java class object representing the collection type- Since:
- 6.0
-