org.appng.persistence.repository

## Class SearchQuery<T>

- java.lang.Object
- - org.appng.persistence.repository.SearchQuery<T>

-     public class SearchQuery<T>
      extends Object

  A `SearchQuery` can be used to perform JPA-queries for JPA entities. Therefore multiple criteria can be added, which are being used in the WHERE-clause of the query (with an and-concatenation).
  Example:
  To retrieve all male users aged over 30 whose name starts with "John", the following query could be build:

       SearchQuery<User> searchQuery = userRepository.createSearchQuery();
       searchQuery.startsWith("name", "John").equals("gender", "male").greaterThan("age", 30);

  This would result in a JPA-query like this:

       from User e where e.name like ?1 and e.gender = ?2 and e.age > ?3

  The query can then be executed by calling `execute(javax.persistence.EntityManager)` or `execute(org.springframework.data.domain.Pageable, javax.persistence.EntityManager)` .

  This class can be sub-classed to implement custom behavior.

  Note that the methods which are used to add a criteria are null-safe, which means the criteria is ignored if the given value is `null`.
  Author:
    Matthias Müller
  See Also:
    `SearchRepository.search(SearchQuery, Pageable)`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `SearchQuery.Clause` A part of a JPQL query that provides it's own parameters.
    `protected class` | `SearchQuery.Criterion` A criterion consisting of the property's name and and `SearchQuery.Operand`, optionally providing a value (it depends on the operand if a value is needed).
    `protected static class` | `SearchQuery.Operand` An operand that is applied to a `SearchQuery.Criterion`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static String` | `AND`
    `protected List<SearchQuery.Clause>` | `andClauses`
    `protected boolean` | `appendEntityAlias`
    `protected List<SearchQuery.Criterion>` | `criteria`
    `protected boolean` | `distinct`
    `protected Class<T>` | `domainClass`
    `protected static String` | `DOT`
    `protected String` | `entityAlias`
    `protected String` | `joinQuery`
    `protected static String` | `PERCENT`
    `protected static String` | `WHERE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SearchQuery(Class<T> domainClass)` Creates a new `SearchQuery` for the given type.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `SearchQuery<T>` | `and(String clause)` Adds a parameterless JPQL AND-clause to this query. Usage example:
    `SearchQuery<T>` | `and(String clause, Map<String,Object> params)` Adds a parameterized JPQL AND-clause to this query.
    `protected StringBuilder` | `appendJoinAndWhereClause(StringBuilder queryBuilder)` Appends a JOIN-clause (if present) and the WHERE-clause to the given `queryBuilder`
    `protected void` | `appendOrder(org.springframework.data.domain.Pageable pageable, StringBuilder queryBuilder, String entityName)` Appends an `ORDER BY` clause, derived from the `pageable`, to the `queryBuilder`, using the given `entityName`.
    `protected void` | `appendOrder(org.springframework.data.domain.Sort sort, StringBuilder queryBuilder, String entityName)` Appends an `ORDER BY` clause, derived from the `sort`, to the `queryBuilder`, using the given `entityName`.
    `protected org.springframework.data.domain.Pageable` | `applyPagination(javax.persistence.Query query, Long total, org.springframework.data.domain.Pageable pageable)` Applies the given `pageable` to the query.
    `protected StringBuilder` | `buildQueryString()` Builds and returns the JPQL query string based on the `domainClass` the `entityAlias` and `appendEntityAlias` the `joinQuery` the `criteria` the `andClauses`
    `SearchQuery<T>` | `contains(String name, Object value)` Checks if the attribute is contains the given value. JPQL-fragment:
    `SearchQuery<T>` | `distinct()` Causes the JPQL-query to select `distinct` entities only.
    `SearchQuery<T>` | `endsWith(String name, Object value)` Checks if the attribute is ends with the given value. JPQL-fragment:
    `SearchQuery<T>` | `equals(String name, Object value)` Checks if the attribute equals the given value. JPQL-fragment:
    `List<T>` | `execute(javax.persistence.EntityManager entityManager)` Executes this `SearchQuery` with the given `EntityManager`.
    `org.springframework.data.domain.Page<T>` | `execute(org.springframework.data.domain.Pageable pageable, javax.persistence.EntityManager entityManager)` Executes this `SearchQuery` with the given `EntityManager`, applying the given `Pageable` (if any) for paging and sorting the results.
    `String` | `getEntityAlias()` Gets the entity alias to by used in JPQL queries
    `SearchQuery<T>` | `greaterEquals(String name, Object value)` Checks if the attribute is greater or equals the given value. JPQL-fragment:
    `SearchQuery<T>` | `greaterThan(String name, Object value)` Checks if the attribute is greater than the given value. JPQL-fragment:
    `SearchQuery<T>` | `in(String name, Collection<?> values)` Checks if the attribute is in the given values. JPQL-fragment:
    `boolean` | `isAppendEntityAlias()` Checks whether or not to add the entity alias `e.` for each criteria in the JPQL query.
    `SearchQuery<T>` | `isNotNull(String name)` Checks if the attribute is not null. JPQL-fragment:
    `SearchQuery<T>` | `isNull(String name)` Checks if the attribute is null. JPQL-fragment:
    `SearchQuery<T>` | `join(String joinQuery)` Adds one or more joins to the resulting JPQL-query. The alias for the entity is `e`, so you could add a join like
    `SearchQuery<T>` | `lessEquals(String name, Object value)` Checks if the attribute is less or equals the given value. JPQL-fragment:
    `SearchQuery<T>` | `lessThan(String name, Object value)` Checks if the attribute is less than the given value. JPQL-fragment:
    `SearchQuery<T>` | `like(String name, Object value)` Checks if the attribute is like the given value. JPQL-fragment:
    `SearchQuery<T>` | `notEquals(String name, Object value)` Checks if the attribute not equals the given value. JPQL-fragment:
    `SearchQuery<T>` | `notIn(String name, Collection<?> values)` Checks if the attribute is not in the given values. JPQL-fragment:
    `SearchQuery<T>` | `notLike(String name, Object value)` Checks if the attribute is not like the given value. JPQL-fragment:
    `void` | `setAppendEntityAlias(boolean appendEntityAlias)` Set to `false` to avoid adding the entity alias `e.` for each criteria in the JPQL query.
    `SearchQuery<T>` | `setEntityAlias(String entityAlias)` Sets the entity alias to by used in JPQL queries
    `protected SearchQuery<T>` | `setQueryParameters(javax.persistence.Query... queries)` Sets the parameters defined by `criteria` for the given queries.
    `SearchQuery<T>` | `startsWith(String name, Object value)` Checks if the attribute is starts with the given value. JPQL-fragment:
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### WHERE

          protected static final String WHERE

      See Also:
        Constant Field Values

    - #### AND

          protected static final String AND

      See Also:
        Constant Field Values

    - #### PERCENT

          protected static final String PERCENT

      See Also:
        Constant Field Values

    - #### DOT

          protected static final String DOT

      See Also:
        Constant Field Values

    - #### criteria

          protected List<SearchQuery.Criterion> criteria

    - #### domainClass

          protected Class<T> domainClass

    - #### distinct

          protected boolean distinct

    - #### joinQuery

          protected String joinQuery

    - #### appendEntityAlias

          protected boolean appendEntityAlias

    - #### entityAlias

          protected String entityAlias

    - #### andClauses

          protected List<SearchQuery.Clause> andClauses

  - ### Constructor Detail

    - #### SearchQuery

          public SearchQuery(Class<T> domainClass)

      Creates a new `SearchQuery` for the given type.
      Parameters:
        `domainClass` - the type of the JPA `Entity`

  - ### Method Detail

    - #### isAppendEntityAlias

          public boolean isAppendEntityAlias()

      Checks whether or not to add the entity alias `e.` for each criteria in the JPQL query. Default is `true` .
      Returns:
        `true` when entity alias gets appended, `false` otherwise

    - #### and

          public SearchQuery<T> and(String clause,
                                    Map<String,Object> params)

      Adds a parameterized JPQL AND-clause to this query. Avoid using the same parameter names for different calls of this method.
      Usage example:

           SearchQuery query= repository.createSearchQuery();
           Map<String, Object> params = new HashMap<String, Object>();
           params.put("date", new Date());
           query.and("(e.valid_from before :date or e.valid_from is null)", params);

      Parameters:
        `clause` - the AND clause
        `params` - the named parameters for the AND-clause
      Returns:
        the current `SearchQuery`
      See Also:
        `and(String)`, `setAppendEntityAlias(boolean)`

    - #### and

          public SearchQuery<T> and(String clause)

      Adds a parameterless JPQL AND-clause to this query.
      Usage example:

           SearchQuery query = repository.createSearchQuery();
           query.and("(e.valid_from before now() or e.valid_from is null)");

      Parameters:
        `clause` - the AND-clause
      Returns:
        the current `SearchQuery`
      See Also:
        `and(String, Map)`, `setAppendEntityAlias(boolean)`

    - #### setAppendEntityAlias

          public void setAppendEntityAlias(boolean appendEntityAlias)

      Set to `false` to avoid adding the entity alias `e.` for each criteria in the JPQL query.
      Parameters:
        `appendEntityAlias` -
      See Also:
        `isAppendEntityAlias()`, `setEntityAlias(String)`

    - #### getEntityAlias

          public String getEntityAlias()

      Gets the entity alias to by used in JPQL queries
      Returns:
        the alias

    - #### setEntityAlias

          public SearchQuery<T> setEntityAlias(String entityAlias)

      Sets the entity alias to by used in JPQL queries
      Parameters:
        `entityAlias` - the alias
      Returns:
        the current `SearchQuery`

    - #### equals

          public final SearchQuery<T> equals(String name,
                                             Object value)

      Checks if the attribute equals the given value.
      JPQL-fragment:

           e.name = :value

      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`

    - #### notEquals

          public final SearchQuery<T> notEquals(String name,
                                                Object value)

      Checks if the attribute not equals the given value.
      JPQL-fragment:

           e.name != :value

      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`

    - #### greaterThan

          public final SearchQuery<T> greaterThan(String name,
                                                  Object value)

      Checks if the attribute is greater than the given value.
      JPQL-fragment:

           e.name > :value

      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`

    - #### greaterEquals

          public final SearchQuery<T> greaterEquals(String name,
                                                    Object value)

      Checks if the attribute is greater or equals the given value.
      JPQL-fragment:

           e.name >= :value

      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`

    - #### lessThan

          public final SearchQuery<T> lessThan(String name,
                                               Object value)

      Checks if the attribute is less than the given value.
      JPQL-fragment:

           e.name < :value

      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`

    - #### lessEquals

          public final SearchQuery<T> lessEquals(String name,
                                                 Object value)

      Checks if the attribute is less or equals the given value.
      JPQL-fragment:

           e.name <= :value

      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`

    - #### in

          public final SearchQuery<T> in(String name,
                                         Collection<?> values)

      Checks if the attribute is in the given values.
      JPQL-fragment:

           e.name in :value

      Parameters:
        `name` - the name of the attribute
        `values` - the values to check
      Returns:
        the current `SearchQuery`

    - #### notIn

          public final SearchQuery<T> notIn(String name,
                                            Collection<?> values)

      Checks if the attribute is not in the given values.
      JPQL-fragment:

           e.name not in :value

      Parameters:
        `name` - the name of the attribute
        `values` - the values to check
      Returns:
        the current `SearchQuery`

    - #### contains

          public final SearchQuery<T> contains(String name,
                                               Object value)

      Checks if the attribute is contains the given value.
      JPQL-fragment:

           e.name like :value

      You don't have to add the wildcard '`%`' before and after the `value`, this is done internally!
      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`

    - #### like

          public final SearchQuery<T> like(String name,
                                           Object value)

      Checks if the attribute is like the given value.
      JPQL-fragment:

           e.name like :value

      The `value` should contain some wildcards ('`%`').
      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`
      See Also:
        `startsWith(String, Object)`, `endsWith(String, Object)`

    - #### notLike

          public final SearchQuery<T> notLike(String name,
                                              Object value)

      Checks if the attribute is not like the given value.
      JPQL-fragment:

           e.name not like :value

      The `value` should contain some wildcards ('`%`').
      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`
      See Also:
        `startsWith(String, Object)`, `endsWith(String, Object)`

    - #### startsWith

          public final SearchQuery<T> startsWith(String name,
                                                 Object value)

      Checks if the attribute is starts with the given value.
      JPQL-fragment:

           e.name like :value

      You don't have to add the wildcard '`%`' after the `value`, this is done internally!
      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`
      See Also:
        `like(String, Object)`

    - #### endsWith

          public final SearchQuery<T> endsWith(String name,
                                               Object value)

      Checks if the attribute is ends with the given value.
      JPQL-fragment:

           e.name like :value

      You don't have to add the wildcard '`%`' before the `value`, this is done internally!
      Parameters:
        `name` - the name of the attribute
        `value` - the value to check
      Returns:
        the current `SearchQuery`
      See Also:
        `like(String, Object)`

    - #### isNotNull

          public final SearchQuery<T> isNotNull(String name)

      Checks if the attribute is not null.
      JPQL-fragment:

           e.name is not null

      Parameters:
        `name` - the name of the attribute
      Returns:
        the current `SearchQuery`

    - #### isNull

          public final SearchQuery<T> isNull(String name)

      Checks if the attribute is null.
      JPQL-fragment:

           e.name is null

      Parameters:
        `name` - the name of the attribute
      Returns:
        the current `SearchQuery`

    - #### appendOrder

          protected void appendOrder(org.springframework.data.domain.Pageable pageable,
                                     StringBuilder queryBuilder,
                                     String entityName)

      Appends an `ORDER BY` clause, derived from the `pageable`, to the `queryBuilder`, using the given `entityName`.
      Parameters:
        `pageable` - the `Pageable`, may be `null`
        `queryBuilder` - the query builder
        `entityName` - the name for the entity

    - #### appendOrder

          protected void appendOrder(org.springframework.data.domain.Sort sort,
                                     StringBuilder queryBuilder,
                                     String entityName)

      Appends an `ORDER BY` clause, derived from the `sort`, to the `queryBuilder`, using the given `entityName`.
      Parameters:
        `sort` - the `Sort`, may be `null`
        `queryBuilder` - the query builder
        `entityName` - the name for the entity

    - #### join

          public SearchQuery<T> join(String joinQuery)

      Adds one or more joins to the resulting JPQL-query.
      The alias for the entity is `e`, so you could add a join like

           join e.addresses a

      Parameters:
        `joinQuery` - the join-part of a JPQL query
      Returns:
        the current `SearchQuery`

    - #### distinct

          public SearchQuery<T> distinct()

      Causes the JPQL-query to select `distinct` entities only.
      Returns:
        the current `SearchQuery`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### execute

          public List<T> execute(javax.persistence.EntityManager entityManager)

      Executes this `SearchQuery` with the given `EntityManager`.
      Parameters:
        `entityManager` - the `EntityManager`
      Returns:
        the result-list

    - #### execute

          public org.springframework.data.domain.Page<T> execute(org.springframework.data.domain.Pageable pageable,
                                                                 javax.persistence.EntityManager entityManager)

      Executes this `SearchQuery` with the given `EntityManager`, applying the given `Pageable` (if any) for paging and sorting the results.
      Parameters:
        `pageable` - a `Pageable` (optional)
        `entityManager` - the `EntityManager`
      Returns:
        the result-`Page`
      See Also:
        `SearchRepository.search(SearchQuery, Pageable)`

    - #### buildQueryString

          protected StringBuilder buildQueryString()

      Builds and returns the JPQL query string based on
      - the `domainClass`
      - the `entityAlias` and `appendEntityAlias`
      - the `joinQuery`
      - the `criteria`
      - the `andClauses`
      Returns:
        a `StringBuilder` containing the query string.
      See Also:
        `join(String)`, `and(String)`, `and(String, Map)`, `setEntityAlias(String)`, `setAppendEntityAlias(boolean)`

    - #### appendJoinAndWhereClause

          protected StringBuilder appendJoinAndWhereClause(StringBuilder queryBuilder)

      Appends a JOIN-clause (if present) and the WHERE-clause to the given `queryBuilder`
      Parameters:
        `queryBuilder` - the `StringBuilder` used to build the query
      Returns:
        the `queryBuilder`
      See Also:
        `join(String)`

    - #### setQueryParameters

          protected SearchQuery<T> setQueryParameters(javax.persistence.Query... queries)

      Sets the parameters defined by `criteria` for the given queries.
      Parameters:
        `queries` -
      Returns:
        the current `SearchQuery`

    - #### applyPagination

          protected org.springframework.data.domain.Pageable applyPagination(javax.persistence.Query query,
                                                                             Long total,
                                                                             org.springframework.data.domain.Pageable pageable)

      Applies the given `pageable` to the query. If the pageable's offset is >= `total`, a new `Pageable` starting at page 0 is returned.
      Parameters:
        `query` - the `Query`
        `total` - the total number of items
        `pageable` - the `Pageable`
      Returns:
        a (possibly new) `Pageable`

Copyright © 2011–2023 aiticon GmbH. All rights reserved.