Interface NaturalIdMultiLoadAccess<T>

public interface NaturalIdMultiLoadAccess<T>

Loads multiple instances of a given entity type at once, by specifying a list of natural id values. This allows the entities to be fetched from the database in batches.

List<Book> books =
        session.byMultipleNaturalId(Book.class)
            .withBatchSize(10)
            .multiLoad(isbnList);

Composite natural ids may be accommodated by passing a list of maps of type Map<String,Object> to multiLoad(Object...). Each map must contain the natural id attribute values keyed by @NaturalId attribute name.

var compositeNaturalId =
        Map.of(Book_.ISBN, isbn, Book_.PRINTING, printing);

See Also:

• Session.byMultipleNaturalId(Class)
• NaturalId

Method Summary

Modifier and Type	Method	Description
NaturalIdMultiLoadAccess<T>	enableOrderedReturn(boolean enabled)	Should the returned list of entity instances be ordered, with the position of an entity instance determined by the position of its identifier in the list if ids passed to multiLoad(Object...)?
NaturalIdMultiLoadAccess<T>	enableReturnOfDeletedEntities(boolean enabled)	Should multiLoad(Object...) return entity instances that have been marked for removal in the current session, but not yet deleted in the database?
List<T>	multiLoad(Object... ids)	Retrieve the entities with the given natural id values.
List<T>	multiLoad(List<?> ids)	Retrieve the entities with the given natural id values.
default NaturalIdMultiLoadAccess<T>	with(EntityGraph<T> graph)	Deprecated. use withLoadGraph(EntityGraph)
NaturalIdMultiLoadAccess<T>	with(EntityGraph<T> graph, GraphSemantic semantic)	Customize the associations fetched by specifying an entity graph, and how it should be interpreted.
NaturalIdMultiLoadAccess<T>	with(Timeout timeout)	Specify the timeout to use when querying the database.
NaturalIdMultiLoadAccess<T>	with(CacheMode cacheMode)	Specify the CacheMode to use when obtaining an entity.
default NaturalIdMultiLoadAccess<T>	with(LockMode lockMode)	Specify the lock mode to use when querying the database.
NaturalIdMultiLoadAccess<T>	with(LockMode lockMode, PessimisticLockScope lockScope)	Specify the lock mode to use when querying the database.
NaturalIdMultiLoadAccess<T>	with(LockOptions lockOptions)	Deprecated, for removal: This API element is subject to removal in a future version. Use one of with(LockMode), with(LockMode, PessimisticLockScope) and/or with(Timeout) instead.
NaturalIdMultiLoadAccess<T>	withBatchSize(int batchSize)	Specify a batch size, that is, how many entities should be fetched in each request to the database.
default NaturalIdMultiLoadAccess<T>	withFetchGraph(EntityGraph<T> graph)	Override the associations fetched by default by specifying the complete list of associations to be fetched as an entity graph.
default NaturalIdMultiLoadAccess<T>	withLoadGraph(EntityGraph<T> graph)	Augment the associations fetched by default by specifying a list of additional associations to be fetched as an entity graph.

Method Details

with

default NaturalIdMultiLoadAccess<T> with(LockMode lockMode)

Specify the lock mode to use when querying the database.

Parameters:

lockMode - The lock mode to apply

Returns:

this, for method chaining

with

NaturalIdMultiLoadAccess<T> with(LockMode lockMode,
 PessimisticLockScope lockScope)

Specify the lock mode to use when querying the database.

Parameters:

lockMode - The lock mode to apply

Returns:

this, for method chaining

with

NaturalIdMultiLoadAccess<T> with(Timeout timeout)

Specify the timeout to use when querying the database.

Parameters:

timeout - The timeout to apply to the database operation

Returns:

this, for method chaining

with

@Deprecated(since="7.0",
            forRemoval=true)
NaturalIdMultiLoadAccess<T> with(LockOptions lockOptions)

Deprecated, for removal: This API element is subject to removal in a future version.

Use one of with(LockMode), with(LockMode, PessimisticLockScope) and/or with(Timeout) instead.

Specify the lock options to use when querying the database.

Parameters:

lockOptions - The lock options to use

Returns:

this, for method chaining

with

NaturalIdMultiLoadAccess<T> with(CacheMode cacheMode)

Specify the CacheMode to use when obtaining an entity.

Parameters:

cacheMode - The CacheMode to use

Returns:

this, for method chaining

withFetchGraph

default NaturalIdMultiLoadAccess<T> withFetchGraph(EntityGraph<T> graph)

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

Since:

6.3

withLoadGraph

default NaturalIdMultiLoadAccess<T> withLoadGraph(EntityGraph<T> graph)

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

Since:

6.3

with

@Deprecated(since="6.3")
default NaturalIdMultiLoadAccess<T> with(EntityGraph<T> graph)

Deprecated.

use withLoadGraph(EntityGraph)

with

NaturalIdMultiLoadAccess<T> with(EntityGraph<T> graph,
 GraphSemantic semantic)

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

withBatchSize

NaturalIdMultiLoadAccess<T> withBatchSize(int batchSize)

Specify a batch size, that is, how many entities should be fetched in each request to the database.

• By default, the batch sizing strategy is determined by the SQL dialect, but
• if some batchSize>1 is specified as an argument to this method, then that batch size will be used.

If an explicit batch size is set manually, care should be taken to not exceed the capabilities of the underlying database.

A batch size is considered a hint.

Parameters:

batchSize - The batch size

Returns:

this, for method chaining

enableReturnOfDeletedEntities

NaturalIdMultiLoadAccess<T> enableReturnOfDeletedEntities(boolean enabled)

Should multiLoad(Object...) return entity instances that have been marked for removal in the current session, but not yet deleted in the database?

By default, instances marked for removal are replaced by null in the returned list of entities when enableOrderedReturn(boolean) is used.

Parameters:

enabled - true if removed entities should be returned; false if they should be replaced by null values.

Returns:

this, for method chaining

enableOrderedReturn

NaturalIdMultiLoadAccess<T> enableOrderedReturn(boolean enabled)

Should the returned list of entity instances be ordered, with the position of an entity instance determined by the position of its identifier in the list if ids passed to multiLoad(Object...)?

By default, the returned list is ordered and the positions of the entities correspond to the positions of their ids. In this case, the handling of entities marked for removal becomes important.

Parameters:

enabled - true if entity instances should be ordered; false if they may be returned in any order.

Returns:

this, for method chaining

multiLoad

List<T> multiLoad(Object... ids)

Retrieve the entities with the given natural id values.

Note that the options enableReturnOfDeletedEntities(boolean) and enableOrderedReturn(boolean) affect the size and shape of the returned list of entity instances.

Parameters:

ids - The natural id values to load

Returns:

The managed entities.

multiLoad

List<T> multiLoad(List<?> ids)

Retrieve the entities with the given natural id values.

Note that the options enableReturnOfDeletedEntities(boolean) and enableOrderedReturn(boolean) affect the size and shape of the returned list of entity instances.

Parameters:

ids - The natural id values to load

Returns:

The managed entities.