com.blazebit.persistence.FullQueryBuilder Maven / Gradle / Ivy
/*
* Copyright 2014 - 2021 Blazebit.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.blazebit.persistence;
import javax.persistence.TypedQuery;
import java.lang.reflect.Constructor;
/**
* A base interface for builders that support normal query functionality.
* This interface is shared between the criteria builder and paginated criteria builder.
*
* @param The query result type
* @param The concrete builder type
* @author Christian Beikov
* @since 1.1.0
*/
public interface FullQueryBuilder> extends QueryBuilder, FetchBuilder {
/**
* Copies this query builder into a new one, using it's projection as an overridable default.
*
* @param resultClass The result class of the query
* @param The type of the result class
* @return A new query builder
* @since 1.2.0
*/
public FullQueryBuilder copy(Class resultClass);
/**
* Returns a query that counts the results that would be produced if the current query was run.
*
* @return A query for determining the count of the result list represented by this query builder
* @since 1.2.0
*/
public TypedQuery getCountQuery();
/**
* Returns the query string that selects the count of elements.
*
* @return The query string
* @since 1.3.0
*/
public String getCountQueryString();
/**
* Returns a query that counts the results and counts up to the maximum value that is given that would be produced if the current query was run.
*
* @param maximumCount the maximum value up to which should be counted
* @return A query for determining the count of the result list represented by this query builder
* @since 1.5.0
*/
public TypedQuery getCountQuery(long maximumCount);
/**
* Returns the query string that selects the count of elements and counts up to the maximum value that is given.
*
* @param maximumCount the maximum value up to which should be counted
* @return The query string
* @since 1.5.0
*/
public String getCountQueryString(long maximumCount);
/**
* Invokes {@link FullQueryBuilder#pageBy(int, int, String, String...)} with the identifiers of the query root entity.
*
* @param firstResult The position of the first result to retrieve, numbered from 0
* @param maxResults The maximum number of results to retrieve
* @return This query builder as paginated query builder
*/
public PaginatedCriteriaBuilder page(int firstResult, int maxResults);
/**
* Invokes {@link FullQueryBuilder#pageByAndNavigate(Object, int, String, String...)} with the identifiers of the query root entity.
*
* @deprecated This method causes a method resolution ambiguity. Use {{@link #pageAndNavigate(Object, int)}} instead.
* @param entityId The id of the entity which should be located on the page
* @param maxResults The maximum number of results to retrieve
* @return This query builder as paginated query builder
*/
@Deprecated
public PaginatedCriteriaBuilder page(Object entityId, int maxResults);
/**
* Invokes {@link FullQueryBuilder#pageByAndNavigate(Object, int, String, String...)} with the identifiers of the query root entity.
*
* @param entityId The id of the entity which should be located on the page
* @param maxResults The maximum number of results to retrieve
* @return This query builder as paginated query builder
* @since 1.3.0
*/
public PaginatedCriteriaBuilder pageAndNavigate(Object entityId, int maxResults);
/**
* Invokes {@link FullQueryBuilder#pageBy(KeysetPage, int, int, String, String...)} with the identifiers of the query root entity.
*
* @param keysetPage The key set from a previous result, may be null
* @param firstResult The position of the first result to retrieve, numbered from 0
* @param maxResults The maximum number of results to retrieve
* @return This query builder as paginated query builder
* @see PagedList#getKeysetPage()
*/
public PaginatedCriteriaBuilder page(KeysetPage keysetPage, int firstResult, int maxResults);
/**
* Like {@link FullQueryBuilder#pageBy(int, int, String, String...)} but lacks the varargs parameter to avoid heap pollution.
*
* @param firstResult The position of the first result to retrieve, numbered from 0
* @param maxResults The maximum number of results to retrieve
* @param identifierExpression The first identifier expression
* @return This query builder as paginated query builder
* @since 1.3.0
*/
public PaginatedCriteriaBuilder pageBy(int firstResult, int maxResults, String identifierExpression);
/**
* Like {@link FullQueryBuilder#pageByAndNavigate(Object, int, String, String...)} but lacks the varargs parameter to avoid heap pollution.
*
* @param entityId The id of the entity which should be located on the page
* @param maxResults The maximum number of results to retrieve
* @param identifierExpression The first identifier expression
* @return This query builder as paginated query builder
* @since 1.3.0
*/
public PaginatedCriteriaBuilder pageByAndNavigate(Object entityId, int maxResults, String identifierExpression);
/**
* Like {@link FullQueryBuilder#pageBy(KeysetPage, int, int, String, String...)} but lacks the varargs parameter to avoid heap pollution.
*
* @param keysetPage The key set from a previous result, may be null
* @param firstResult The position of the first result to retrieve, numbered from 0
* @param maxResults The maximum number of results to retrieve
* @param identifierExpression The first identifier expression
* @return This query builder as paginated query builder
* @since 1.3.0
* @see PagedList#getKeysetPage()
*/
public PaginatedCriteriaBuilder pageBy(KeysetPage keysetPage, int firstResult, int maxResults, String identifierExpression);
/**
* Paginates the results of this query based on the given identifier expressions.
*
* In JPA, the use of setFirstResult
and setMaxResults
is not defined when involving fetch joins for collections.
* When no collection joins are involved, this is fine as rows essentially represent objects, but when collections are joined, this is no longer true.
* JPA providers usually fall back to querying all data and doing pagination in-memory based on objects or simply don't support that kind of query.
*
* This API allows to specify the identifier expressions to use for pagination and transparently handles collection join support.
* The big advantage of this API over plain setFirstResult
and setMaxResults
can also be seen when doing scalar queries.
*
*
* An example for such queries would be a query that joins a collection:
*
* SELECT d.id, contacts.name FROM Document d LEFT JOIN d.contacts contacts
*
* If one Document
has associated multiple contacts, the above query will produce multiple result set rows for that document.
* Paginating via setFirstResult
and setMaxResults
would produce unexpected results whereas using this API, will produce the expected results.
*
*
*
* When paginating on the identifier i.e. d.id
, the results are implicitly grouped by the document id and distinct. Therefore calling
* distinct() on a PaginatedCriteriaBuilder is not allowed.
*
*
* @param firstResult The position of the first result to retrieve, numbered from 0
* @param maxResults The maximum number of results to retrieve
* @param identifierExpression The first identifier expression
* @param identifierExpressions The other identifier expressions
* @return This query builder as paginated query builder
* @since 1.3.0
*/
public PaginatedCriteriaBuilder pageBy(int firstResult, int maxResults, String identifierExpression, String... identifierExpressions);
/**
* Paginates the results of this query and navigates to the page on which
* the object with the given identifier is located.
*
* Beware that the same limitations like for {@link FullQueryBuilder#page(int, int)} apply.
* If the object with the given identifier does not exist in the result list:
*
* - The result of {@link PaginatedCriteriaBuilder#getResultList()} will contain the first page
* - {@link PagedList#getFirstResult()} will return
-1
*
*
* @param entityId The id of the object which should be located on the page
* @param maxResults The maximum number of results to retrieve
* @param identifierExpression The first identifier expression
* @param identifierExpressions The other identifier expressions
* @return This query builder as paginated query builder
* @since 1.3.0
*/
public PaginatedCriteriaBuilder pageByAndNavigate(Object entityId, int maxResults, String identifierExpression, String... identifierExpressions);
/**
* Like {@link FullQueryBuilder#page(int, int)} but additionally uses key set pagination when possible.
*
* Beware that keyset pagination should not be used as a direct replacement for offset pagination.
* Since entries that have a lower rank than some keyset might be added or removed, the calculations
* for the firstResult might be wrong. If strict pagination is required, then the {@link KeysetPage} should
* not be used when the count of lower ranked items changes which will result in the use of offset pagination for that request.
*
*
* Key set pagination is possible if and only if the following conditions are met:
*
* - The keyset reference values fit the order by expressions of this query builder AND
* - {@link KeysetPage#getMaxResults()} and
maxResults
evaluate to the same value AND
* - One of the following conditions is met:
*
* - The absolute value of {@link KeysetPage#getFirstResult()}
- firstResult
is 0
* - The absolute value of {@link KeysetPage#getFirstResult()}
- firstResult
is equal to the value of
* maxResults
*
*
*
*
*
* @param keysetPage The key set from a previous result, may be null
* @param firstResult The position of the first result to retrieve, numbered from 0
* @param maxResults The maximum number of results to retrieve
* @param identifierExpression The first identifier expression
* @param identifierExpressions The other identifier expressions
* @return This query builder as paginated query builder
* @since 1.3.0
* @see PagedList#getKeysetPage()
*/
public PaginatedCriteriaBuilder pageBy(KeysetPage keysetPage, int firstResult, int maxResults, String identifierExpression, String... identifierExpressions);
/**
* Like calling {@link #pageBy(int, int, String)} and then {@link PaginatedCriteriaBuilder#createPageIdQuery()} but more efficient.
*
* @param firstResult The position of the first result to retrieve, numbered from 0
* @param maxResults The maximum number of results to retrieve
* @param identifierExpression The first identifier expression
* @return the {@link CriteriaBuilder} to query id values
* @since 1.4.1
*/
public CriteriaBuilder