Interface JpaSpecificationExecutor<T>

All Known Subinterfaces:

JpaRepositoryImplementation<T,ID>

All Known Implementing Classes:

SimpleJpaRepository

public interface JpaSpecificationExecutor<T>

Interface to allow execution of Specifications based on the JPA criteria API.

Author:

Oliver Gierke, Christoph Strobl, Diego Krupitza, Mark Paluch, Joshua Chen

See Also:

• Specification
• UpdateSpecification
• DeleteSpecification
• PredicateSpecification

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	JpaSpecificationExecutor.SpecificationFluentQuery<T>	Extension to FluentQuery.FetchableFluentQuery allowing slice results and pagination with a custom count Specification.

Method Summary

Modifier and Type	Method	Description
default long	count(PredicateSpecification<T> spec)	Returns the number of instances that the given PredicateSpecification will return.
long	count(Specification<T> spec)	Returns the number of instances that the given Specification will return.
long	delete(DeleteSpecification<T> spec)	Deletes by the UpdateSpecification and returns the number of rows deleted.
default long	delete(PredicateSpecification<T> spec)	Deletes by the PredicateSpecification and returns the number of rows deleted.
default boolean	exists(PredicateSpecification<T> spec)	Checks whether the data store contains elements that match the given PredicateSpecification.
boolean	exists(Specification<T> spec)	Checks whether the data store contains elements that match the given Specification.
Page<T>	findAll(@Nullable Specification<T> spec, @Nullable Specification<T> countSpec, Pageable pageable)	Returns a Page of entities matching the given Specification.
default List<T>	findAll(PredicateSpecification<T> spec)	Returns all entities matching the given PredicateSpecification.
List<T>	findAll(Specification<T> spec)	Returns all entities matching the given Specification.
Page<T>	findAll(Specification<T> spec, Pageable pageable)	Returns a Page of entities matching the given Specification.
List<T>	findAll(Specification<T> spec, Sort sort)	Returns all entities matching the given Specification and Sort.
default <S extends T, R> R	findBy(PredicateSpecification<T> spec, Function<? super JpaSpecificationExecutor.SpecificationFluentQuery<S>, R> queryFunction)	Returns entities matching the given Specification applying the queryFunction that defines the query and its result type.
<S extends T, R extends @Nullable Object> R	findBy(Specification<T> spec, Function<? super JpaSpecificationExecutor.SpecificationFluentQuery<S>, R> queryFunction)	Returns entities matching the given Specification applying the queryFunction that defines the query and its result type.
default Optional<T>	findOne(PredicateSpecification<T> spec)	Returns a single entity matching the given PredicateSpecification or Optional.empty() if none found.
Optional<T>	findOne(Specification<T> spec)	Returns a single entity matching the given Specification or Optional.empty() if none found.
long	update(UpdateSpecification<T> spec)	Updates entities by the UpdateSpecification and returns the number of rows updated.

Method Details

findOne

default Optional<T> findOne(PredicateSpecification<T> spec)

Returns a single entity matching the given PredicateSpecification or Optional.empty() if none found.

Parameters:

spec - must not be null.

Returns:

never null.

Throws:

IncorrectResultSizeDataAccessException - if more than one entity found.

See Also:

• Specification.unrestricted()

findOne

Optional<T> findOne(Specification<T> spec)

Returns a single entity matching the given Specification or Optional.empty() if none found.

Parameters:

spec - must not be null.

Returns:

never null.

Throws:

IncorrectResultSizeDataAccessException - if more than one entity found.

See Also:

• Specification.unrestricted()

findAll

default List<T> findAll(PredicateSpecification<T> spec)

Returns all entities matching the given PredicateSpecification.

Parameters:

spec - must not be null.

Returns:

never null.

See Also:

• Specification.unrestricted()

findAll

List<T> findAll(Specification<T> spec)

Returns all entities matching the given Specification.

Parameters:

spec - must not be null.

Returns:

never null.

See Also:

• Specification.unrestricted()

findAll

Page<T> findAll(Specification<T> spec,
 Pageable pageable)

Returns a Page of entities matching the given Specification.

Parameters:

spec - must not be null.

pageable - must not be null.

Returns:

never null.

See Also:

• Specification.unrestricted()

findAll

Page<T> findAll(@Nullable Specification<T> spec,
 @Nullable Specification<T> countSpec,
 Pageable pageable)

Returns a Page of entities matching the given Specification.

Supports counting the total number of entities matching the Specification.

Parameters:

spec - can be null, if no Specification is given all entities matching <T> will be selected.

countSpec - can be null，if no Specification is given all entities matching <T> will be counted.

pageable - must not be null.

Returns:

never null.

Since:

3.5

findAll

List<T> findAll(Specification<T> spec,
 Sort sort)

Returns all entities matching the given Specification and Sort.

Parameters:

spec - must not be null.

sort - must not be null.

Returns:

never null.

See Also:

• Specification.unrestricted()

count

default long count(PredicateSpecification<T> spec)

Returns the number of instances that the given PredicateSpecification will return.

Parameters:

spec - the PredicateSpecification to count instances for, must not be null.

Returns:

the number of instances.

See Also:

• Specification.unrestricted()

count

long count(Specification<T> spec)

Returns the number of instances that the given Specification will return.

Parameters:

spec - the Specification to count instances for, must not be null.

Returns:

the number of instances.

See Also:

• Specification.unrestricted()

exists

default boolean exists(PredicateSpecification<T> spec)

Checks whether the data store contains elements that match the given PredicateSpecification.

Parameters:

spec - the PredicateSpecification to use for the existence check, must not be null.

Returns:

true if the data store contains elements that match the given PredicateSpecification otherwise false.

See Also:

• Specification.unrestricted()

exists

boolean exists(Specification<T> spec)

Checks whether the data store contains elements that match the given Specification.

Parameters:

spec - the Specification to use for the existence check, must not be null.

Returns:

true if the data store contains elements that match the given Specification otherwise false.

See Also:

• Specification.unrestricted()

update

long update(UpdateSpecification<T> spec)

Updates entities by the UpdateSpecification and returns the number of rows updated.

This method uses Criteria API bulk update that maps directly to database update operations. The persistence context is not synchronized with the result of the bulk update.

Parameters:

spec - the UpdateSpecification to use for the update query must not be null.

Returns:

the number of entities deleted.

Since:

4.0

delete

default long delete(PredicateSpecification<T> spec)

Deletes by the PredicateSpecification and returns the number of rows deleted.

This method uses Criteria API bulk delete that maps directly to database delete operations. The persistence context is not synchronized with the result of the bulk delete.

Parameters:

spec - the PredicateSpecification to use for the delete query, must not be null.

Returns:

the number of entities deleted.

Since:

3.0

See Also:

• PredicateSpecification.unrestricted()

delete

long delete(DeleteSpecification<T> spec)

Deletes by the UpdateSpecification and returns the number of rows deleted.

This method uses Criteria API bulk delete that maps directly to database delete operations. The persistence context is not synchronized with the result of the bulk delete.

Parameters:

spec - the UpdateSpecification to use for the delete query must not be null.

Returns:

the number of entities deleted.

Since:

3.0

See Also:

• DeleteSpecification.unrestricted()

findBy

default <S extends T, R> R findBy(PredicateSpecification<T> spec,
 Function<? super JpaSpecificationExecutor.SpecificationFluentQuery<S>, R> queryFunction)

Returns entities matching the given Specification applying the queryFunction that defines the query and its result type.

The query object used with queryFunction is only valid inside the findBy(…) method call. This requires the query function to return a query result and not the FluentQuery object itself to ensure the query is executed inside the findBy(…) method.

Parameters:

spec - must not be null.

queryFunction - the query function defining projection, sorting, and the result type

Returns:

all entities matching the given Example.

Since:

4.0

findBy

<S extends T, R extends @Nullable Object> R findBy(Specification<T> spec,
 Function<? super JpaSpecificationExecutor.SpecificationFluentQuery<S>, R> queryFunction)

Returns entities matching the given Specification applying the queryFunction that defines the query and its result type.

The query object used with queryFunction is only valid inside the findBy(…) method call. This requires the query function to return a query result and not the FluentQuery object itself to ensure the query is executed inside the findBy(…) method.

Parameters:

spec - must not be null.

queryFunction - the query function defining projection, sorting, and the result type

Returns:

all entities matching the given specification.

Throws:

InvalidDataAccessApiUsageException - if the query function returns the FluentQuery instance.

Since:

3.0