Package org.hibernate

Interface NaturalIdLoadAccess<T>

All Known Implementing Classes:

NaturalIdLoadAccessImpl

public interface NaturalIdLoadAccess<T>

Loads an entity by its natural identifier, which may be a composite value comprising more than one attribute of the entity. If the entity has exactly one attribute annotated @NaturalId, then SimpleNaturalIdLoadAccess may be used instead.

 Book book =
         session.byNaturalId(Book.class)
             .using(Book_.isbn, isbn)
             .using(Book_.printing, printing)
             .load();
 

See Also:

Session.byNaturalId(Class), NaturalId, SimpleNaturalIdLoadAccess

Method Summary

Modifier and Type	Method	Description
NaturalIdLoadAccess<T>	disableFetchProfile(String profileName)	Customize the associations fetched by specifying a fetch profile that should be disabled during this operation.
NaturalIdLoadAccess<T>	enableFetchProfile(String profileName)	Customize the associations fetched by specifying a fetch profile that should be enabled during this operation.
T	getReference()	Return the persistent instance with the full natural id specified by previous calls to using(jakarta.persistence.metamodel.SingularAttribute<? super T, X>, X).
T	load()	Return the persistent instance with the full natural id specified by previous calls to using(jakarta.persistence.metamodel.SingularAttribute<? super T, X>, X), or null if there is no such persistent instance.
Optional<T>	loadOptional()	Just like load(), except that here an Optional is returned.
NaturalIdLoadAccess<T>	setSynchronizationEnabled(boolean enabled)	Determines if cached natural id cross-references are synchronized before query execution with unflushed modifications made in memory to mutable natural ids.
<X> NaturalIdLoadAccess<T>	using(SingularAttribute<? super T,X> attribute, X value)	Add a @NaturalId attribute value in a typesafe way.
NaturalIdLoadAccess<T>	using(Object... mappings)	Deprecated. use using(Map) with Map.of(), which is slightly more typesafe
NaturalIdLoadAccess<T>	using(String attributeName, Object value)	Add a @NaturalId attribute value.
NaturalIdLoadAccess<T>	using(Map<String,?> mappings)	Set multiple @NaturalId attribute values at once.
NaturalIdLoadAccess<T>	with(RootGraph<T> graph, GraphSemantic semantic)	Customize the associations fetched by specifying an entity graph, and how it should be interpreted.
NaturalIdLoadAccess<T>	with(LockOptions lockOptions)	Specify the lock options to use when querying the database.
default NaturalIdLoadAccess<T>	withFetchGraph(RootGraph<T> graph)	Override the associations fetched by default by specifying the complete list of associations to be fetched as an entity graph.
default NaturalIdLoadAccess<T>	withLoadGraph(RootGraph<T> graph)	Augment the associations fetched by default by specifying a list of additional associations to be fetched as an entity graph.

Method Detail

with

NaturalIdLoadAccess<T> with(LockOptions lockOptions)

Specify the lock options to use when querying the database.

Parameters:

lockOptions - The lock options to use.

Returns:

this, for method chaining

withFetchGraph

default NaturalIdLoadAccess<T> withFetchGraph(RootGraph<T> graph)

Override the associations fetched by default by specifying the complete list of associations to be fetched as an entity graph.

withLoadGraph

default NaturalIdLoadAccess<T> withLoadGraph(RootGraph<T> graph)

Augment the associations fetched by default by specifying a list of additional associations to be fetched as an entity graph.

with

NaturalIdLoadAccess<T> with(RootGraph<T> graph,
                            GraphSemantic semantic)

Customize the associations fetched by specifying an entity graph, and how it should be interpreted.

enableFetchProfile

NaturalIdLoadAccess<T> enableFetchProfile(String profileName)

Customize the associations fetched by specifying a fetch profile that should be enabled during this operation.

This allows the session-level fetch profiles to be temporarily overridden.

Since:

6.3

disableFetchProfile

NaturalIdLoadAccess<T> disableFetchProfile(String profileName)

Customize the associations fetched by specifying a fetch profile that should be disabled during this operation.

This allows the session-level fetch profiles to be temporarily overridden.

Since:

6.3

using

<X> NaturalIdLoadAccess<T> using(SingularAttribute<? super T,X> attribute,
                                 X value)

Add a @NaturalId attribute value in a typesafe way.

Parameters:

attribute - A typesafe reference to an attribute of the entity that is annotated @NaturalId

value - The value of the attribute

Returns:

this, for method chaining

using

NaturalIdLoadAccess<T> using(String attributeName,
                             Object value)

Add a @NaturalId attribute value.

Parameters:

attributeName - The name of an attribute of the entity that is annotated @NaturalId

value - The value of the attribute

Returns:

this, for method chaining

using

NaturalIdLoadAccess<T> using(Map<String,?> mappings)

Set multiple @NaturalId attribute values at once. An even number of arguments is expected, with each attribute name followed by its value, for example:

 Book book =
         session.byNaturalId(Book.class)
             .using(Map.of(Book_.ISBN, isbn, Book_.PRINTING, printing))
             .load();
 

Returns:

this, for method chaining

using

@Deprecated(since="6.3")
NaturalIdLoadAccess<T> using(Object... mappings)

Deprecated.

use using(Map) with Map.of(), which is slightly more typesafe

Set multiple @NaturalId attribute values at once. An even number of arguments is expected, with each attribute name followed by its value, for example:

 Book book =
         session.byNaturalId(Book.class)
             .using(Book_.ISBN, isbn, Book_.PRINTING, printing)
             .load();
 

Returns:

this, for method chaining

setSynchronizationEnabled

NaturalIdLoadAccess<T> setSynchronizationEnabled(boolean enabled)

Determines if cached natural id cross-references are synchronized before query execution with unflushed modifications made in memory to mutable natural ids.

By default, every cached cross-reference is updated to reflect any modification made in memory.

Here "synchronization" means updating the natural id to primary key cross-reference maintained by the session. When enabled, before performing the lookup, Hibernate will check all entities associated with the session of the given type to determine if any natural id values have changed and, if so, update the cross-references.

There's some cost associated with this synchronization, so if it's completely certain the no natural ids have been modified, synchronization may be safely disabled to avoid that cost. Disabling this setting when natural id values have been modified may lead to incorrect results.

Parameters:

enabled - Should synchronization be performed? true indicates synchronization will be performed; false indicates it will be circumvented.

Returns:

this, for method chaining

getReference

T getReference()

Return the persistent instance with the full natural id specified by previous calls to using(jakarta.persistence.metamodel.SingularAttribute<? super T, X>, X). This method might return a proxied instance that is initialized on-demand, when a non-identifier method is accessed.

You should not use this method to determine if an instance exists; to check for existence, use load() instead. Use this method only to retrieve an instance that you assume exists, where non-existence would be an actual error.

Returns:

the persistent instance or proxy

load

T load()

Return the persistent instance with the full natural id specified by previous calls to using(jakarta.persistence.metamodel.SingularAttribute<? super T, X>, X), or null if there is no such persistent instance. If the instance is already associated with the session, return that instance, initializing it if needed. This method never returns an uninitialized instance.

Returns:

The persistent instance or null

loadOptional

Optional<T> loadOptional()

Just like load(), except that here an Optional is returned.

Returns:

The persistent instance, if one, as an Optional