Package in.co.akshitbansal.springwebquery.repository

Interface WebQueryRepository<E>

Type Parameters:
E - entity type backing the repository implementation
All Known Implementing Classes:
WebQueryRepositoryImpl
public interface WebQueryRepository<E>
Primary repository entry point of Spring Web Query.

This interface is exposed as a Spring Data repository fragment. Although it is declared as an interface for fragment composition, the Javadoc here describes the concrete behavior provided by the library's built-in JPA-backed implementation.

For each invocation, the fragment resolves the backing entity type from the current repository method call, obtains a tuple projection from the supplied SelectionsProvider, parses the optional RSQL filter, validates the parsed AST with a ValidationRSQLVisitor, maps selector paths from dtoClass to entity paths through DTOToEntityPathMapper, validates sortable fields through SortableFieldValidator, and delegates predicate construction to RSQLJPAPredicateConverter.

The supplied DTO class therefore controls both which field paths may be used for filtering and sorting and how the projected result is materialized. The resulting Criteria query applies sorting and pagination from Pageable. Query rows are fetched as tuples and converted to the requested DTO type through TupleConverter, so the selections produced by SelectionsProvider must be compatible in order and type with the conversion strategy discoverable for dtoClass. If the selections provider returns no selections, query execution fails with a QueryConfigurationException.

count(String, SpecificationCustomizer, Class, boolean, boolean, int) reuses the same filter construction pipeline without tuple projection. findAllPaged(String, Pageable, SelectionsProvider, SpecificationCustomizer, Class, boolean, boolean, int) uses the same filtering, sorting, pagination, and projection behavior as findAll(String, Pageable, SelectionsProvider, SpecificationCustomizer, Class, boolean, boolean, int); for paged requests it first executes a count query and skips the content query when the count is zero, while unpaged requests are wrapped directly in a PageImpl without a separate count query.

The overloads that do not accept explicit validation settings use the repository-wide defaults sourced from the properties spring-web-query.filtering.allow-and-operation, spring-web-query.filtering.allow-or-operation, and spring-web-query.filtering.max-ast-depth.

  • Method Details

    • findAll

      <D> List<D> findAll(@Nullable String rsqlQuery, org.springframework.data.domain.Pageable pageable, SelectionsProvider<E> selectionsProvider, @Nullable SpecificationCustomizer<E> specificationCustomizer, Class<D> dtoClass, boolean allowAndOperation, boolean allowOrOperation, int maxASTDepth)
      Executes the full Spring Web Query pipeline and returns only the projected content rows for the requested page window.

      If rsqlQuery is not null, the current implementation parses it, validates the AST against the supplied DTO type and the provided logical-operator and depth settings, translates validated selectors to entity paths, and creates a JPA Specification from the validated tree. The optional specificationCustomizer is then applied to that specification and may augment it, replace it, or remove it completely by returning null.

      The selectionsProvider defines the tuple select clause. The built-in implementation rejects an empty selection list, applies the sort orders and pagination window from pageable, executes the query, and converts each returned tuple into an instance of dtoClass through TupleConverter. Even though this method returns a List, the offset and page size from pageable are still applied to the query when pageable is paged.

      Type Parameters:
      D - projected DTO type
      Parameters:
      rsqlQuery - optional RSQL filter expression
      pageable - requested paging and sorting information
      selectionsProvider - callback that defines the tuple projection
      specificationCustomizer - optional hook to amend the generated filter specification before it is applied
      dtoClass - DTO type whose fields are used for filtering and sorting and whose shape is used for result projection
      allowAndOperation - whether logical AND is allowed in the RSQL expression
      allowOrOperation - whether logical OR is allowed in the RSQL expression
      maxASTDepth - maximum RSQL AST depth accepted during validation
      Returns:
      projected results for the requested page window, ordered according to the translated sort instructions
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if no selections are provided, selector translation fails because of invalid configuration, JPA sort order construction fails, or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing
      IllegalArgumentException - if pageable.getOffset() exceeds Integer.MAX_VALUE

    • findAll

      <D> List<D> findAll(@Nullable String rsqlQuery, org.springframework.data.domain.Pageable pageable, SelectionsProvider<E> selectionsProvider, @Nullable SpecificationCustomizer<E> specificationCustomizer, Class<D> dtoClass)
      Executes findAll(String, Pageable, SelectionsProvider, SpecificationCustomizer, Class, boolean, boolean, int) using the repository-wide validation defaults configured for the implementation.

      This overload keeps the same filtering, sorting, projection, and pagination semantics as the fully configurable variant, but derives the logical-operator and AST-depth settings from repository configuration instead of requiring them from the caller.

      The default values come from the properties spring-web-query.filtering.allow-and-operation, spring-web-query.filtering.allow-or-operation, and spring-web-query.filtering.max-ast-depth.

      Type Parameters:
      D - projected DTO type
      Parameters:
      rsqlQuery - optional RSQL filter expression
      pageable - requested paging and sorting information
      selectionsProvider - callback that defines the tuple projection
      specificationCustomizer - optional hook to amend the generated filter
      dtoClass - DTO type whose fields are used for filtering and sorting and whose shape is used for result projection
      Returns:
      projected results for the requested page window, ordered according to the translated sort instructions
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if no selections are provided, selector translation fails because of invalid configuration, JPA sort order construction fails, or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing
      IllegalArgumentException - if pageable.getOffset() exceeds Integer.MAX_VALUE

    • findAll

      default <D> List<D> findAll(@Nullable String rsqlQuery, @NonNull @NonNull org.springframework.data.domain.Pageable pageable, @NonNull @NonNull SelectionsProvider<E> selectionsProvider, @NonNull @NonNull Class<D> dtoClass)
      Executes a filtered, sorted, and paginated projection query without a specification customizer.

      This is a convenience overload equivalent to invoking the repository default-settings variant with a null customizer.

      Type Parameters:
      D - projected DTO type
      Parameters:
      rsqlQuery - optional RSQL filter expression
      pageable - requested paging and sorting information
      selectionsProvider - callback that defines the tuple projection
      dtoClass - DTO type whose fields are used for filtering and sorting and whose shape is used for result projection
      Returns:
      projected results for the requested page window, ordered according to the translated sort instructions
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if no selections are provided, selector translation fails because of invalid configuration, JPA sort order construction fails, or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing
      IllegalArgumentException - if pageable.getOffset() exceeds Integer.MAX_VALUE

    • count

      long count(@Nullable String rsqlQuery, @Nullable SpecificationCustomizer<E> specificationCustomizer, Class<?> dtoClass, boolean allowAndOperation, boolean allowOrOperation, int maxASTDepth)
      Executes the same filtering pipeline as findAll(String, Pageable, SelectionsProvider, SpecificationCustomizer, Class, boolean, boolean, int) but produces a row count instead of projected content.

      If rsqlQuery is null, the base specification is unrestricted and only the optional specificationCustomizer can add restrictions. Otherwise the RSQL expression is parsed, validated, and translated exactly as it is for findAll. The current implementation applies the resulting specification to a count query and uses countDistinct(root) when the underlying criteria query has been marked distinct; otherwise it uses a regular count(root).

      Parameters:
      rsqlQuery - optional RSQL filter expression
      specificationCustomizer - optional hook to amend the generated filter
      dtoClass - DTO type whose fields are used for filter validation and path translation
      allowAndOperation - whether logical AND is allowed in the RSQL expression
      allowOrOperation - whether logical OR is allowed in the RSQL expression
      maxASTDepth - maximum RSQL AST depth accepted during validation
      Returns:
      number of matching rows after the generated and customized filter specification has been applied
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if selector translation fails because of invalid configuration or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing

    • count

      long count(@Nullable String rsqlQuery, @Nullable SpecificationCustomizer<E> specificationCustomizer, Class<?> dtoClass)
      Counts rows using the repository-wide validation defaults configured for the implementation.

      This overload retains the same counting semantics as count(String, SpecificationCustomizer, Class, boolean, boolean, int) while sourcing the logical-operator and AST-depth settings from repository configuration.

      The default values come from the properties spring-web-query.filtering.allow-and-operation, spring-web-query.filtering.allow-or-operation, and spring-web-query.filtering.max-ast-depth.

      Parameters:
      rsqlQuery - optional RSQL filter expression
      specificationCustomizer - optional hook to amend the generated filter
      dtoClass - DTO type whose fields are used for filter validation and path translation
      Returns:
      number of matching rows after the generated and customized filter specification has been applied
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if selector translation fails because of invalid configuration or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing

    • count

      default long count(@Nullable String rsqlQuery, @NonNull @NonNull Class<?> dtoClass)
      Counts rows without a specification customizer.

      This is a convenience overload equivalent to invoking the repository default-settings variant with a null customizer.

      Parameters:
      rsqlQuery - optional RSQL filter expression
      dtoClass - DTO type whose fields are used for filter validation and path translation
      Returns:
      number of matching rows after applying only the repository-built filter specification
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if selector translation fails because of invalid configuration or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing

    • findAllPaged

      default <D> org.springframework.data.domain.Page<D> findAllPaged(@Nullable String rsqlQuery, @NonNull @NonNull org.springframework.data.domain.Pageable pageable, @NonNull @NonNull SelectionsProvider<E> selectionsProvider, @Nullable SpecificationCustomizer<E> specificationCustomizer, @NonNull @NonNull Class<D> dtoClass, boolean allowAndOperation, boolean allowOrOperation, int maxASTDepth)
      Executes the same query pipeline as findAll(String, Pageable, SelectionsProvider, SpecificationCustomizer, Class, boolean, boolean, int) but returns a Page with count metadata.

      The current implementation behaves in two modes. When pageable.isUnpaged() is true, it runs only findAll(...) and wraps the resulting content in a PageImpl. When pageable is paged, it first executes count(String, SpecificationCustomizer, Class, boolean, boolean, int). If that count is zero, it returns an empty page without issuing the content query. Otherwise it executes findAll(...) for the requested page window and combines the content with the total row count.

      Type Parameters:
      D - projected DTO type
      Parameters:
      rsqlQuery - optional RSQL filter expression
      pageable - requested paging and sorting information
      selectionsProvider - callback that defines the tuple projection
      specificationCustomizer - optional hook to amend the generated filter
      dtoClass - DTO type whose fields are used for filtering and sorting and whose shape is used for result projection
      allowAndOperation - whether logical AND is allowed in the RSQL expression
      allowOrOperation - whether logical OR is allowed in the RSQL expression
      maxASTDepth - maximum RSQL AST depth accepted during validation
      Returns:
      page of projected results together with paging metadata derived from the matching-row count
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if no selections are provided, selector translation fails because of invalid configuration, JPA sort order construction fails, or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing
      IllegalArgumentException - if pageable.getOffset() exceeds Integer.MAX_VALUE

    • findAllPaged

      <D> org.springframework.data.domain.Page<D> findAllPaged(@Nullable String rsqlQuery, org.springframework.data.domain.Pageable pageable, SelectionsProvider<E> selectionsProvider, @Nullable SpecificationCustomizer<E> specificationCustomizer, Class<D> dtoClass)
      Executes a filtered, sorted, and paginated projection query using the repository-wide validation defaults and returns a Page.

      This overload keeps the same page-assembly behavior as the fully configurable variant while sourcing the logical-operator and AST-depth settings from repository configuration.

      The default values come from the properties spring-web-query.filtering.allow-and-operation, spring-web-query.filtering.allow-or-operation, and spring-web-query.filtering.max-ast-depth.

      Type Parameters:
      D - projected DTO type
      Parameters:
      rsqlQuery - optional RSQL filter expression
      pageable - requested paging and sorting information
      selectionsProvider - callback that defines the tuple projection
      specificationCustomizer - optional hook to amend the generated filter
      dtoClass - DTO type whose fields are used for filtering and sorting and whose shape is used for result projection
      Returns:
      page of projected results together with paging metadata derived from the matching-row count
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if no selections are provided, selector translation fails because of invalid configuration, JPA sort order construction fails, or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing
      IllegalArgumentException - if pageable.getOffset() exceeds Integer.MAX_VALUE

    • findAllPaged

      default <D> org.springframework.data.domain.Page<D> findAllPaged(@Nullable String rsqlQuery, @NonNull @NonNull org.springframework.data.domain.Pageable pageable, @NonNull @NonNull SelectionsProvider<E> selectionsProvider, @NonNull @NonNull Class<D> dtoClass)
      Executes a filtered, sorted, and paginated projection query without a specification customizer and returns a Page.

      This is a convenience overload equivalent to invoking the repository default-settings variant with a null customizer.

      Type Parameters:
      D - projected DTO type
      Parameters:
      rsqlQuery - optional RSQL filter expression
      pageable - requested paging and sorting information
      selectionsProvider - callback that defines the tuple projection
      dtoClass - DTO type whose fields are used for filtering and sorting and whose shape is used for result projection
      Returns:
      page of projected results together with paging metadata derived from the matching-row count
      Throws:
      QueryValidationException - if the RSQL expression cannot be parsed or violates the configured validation rules
      QueryConfigurationException - if no selections are provided, selector translation fails because of invalid configuration, JPA sort order construction fails, or predicate creation fails after parsing and validation
      QueryException - if another Spring Web Query exception is raised during processing
      IllegalArgumentException - if pageable.getOffset() exceeds Integer.MAX_VALUE