org.springframework.ldap.query

## Class LdapQueryBuilder

- java.lang.Object
- - org.springframework.ldap.query.LdapQueryBuilder

- All Implemented Interfaces:
    LdapQuery

      public final class LdapQueryBuilder
      extends Object
      implements LdapQuery

  Builder of LdapQueries. Start with a call to `query()`, proceed with specifying the basic search configuration (e.g. search base, time limit, etc.), finally specify the actual query. Example:

       import static org.springframework.ldap.query.LdapQueryBuilder.query;
       ...

       LdapQuery query = query()
        .base("dc=261consulting, dc=com")
        .searchScope(SearchScope.ONELEVEL)
        .timeLimit(200)
        .countLimit(221)
        .where("objectclass").is("person").and("cn").is("John Doe");

  Default configuration is that base path is `LdapUtils.emptyLdapName()`. All other parameters are undefined, meaning that (in the case of base search parameters), the LdapTemplate defaults will be used. Filter conditions must always be specified.

  Since:
    2.0
  Author:
    Mattias Hellborg Arthursson
  See Also:
    `SearchControls`, `LdapOperations.search(LdapQuery, org.springframework.ldap.core.AttributesMapper)`, `LdapOperations.search(LdapQuery, org.springframework.ldap.core.ContextMapper)`, `LdapOperations.searchForObject(LdapQuery, org.springframework.ldap.core.ContextMapper)`, `LdapOperations.searchForContext(LdapQuery)`

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `String[]` | `attributes()` Get the attributes to return.
    `LdapQueryBuilder` | `attributes(String... attributesToReturn)`
    `Name` | `base()` Get the search base.
    `LdapQueryBuilder` | `base(Name baseDn)` Set the base search path for the query.
    `LdapQueryBuilder` | `base(String baseDn)` Set the base search path for the query.
    `Integer` | `countLimit()` Get the count limit.
    `LdapQueryBuilder` | `countLimit(int countLimit)` Set the count limit for the query.
    `Filter` | `filter()` Get the filter.
    `LdapQuery` | `filter(Filter filter)` Specify the filter to use.
    `LdapQuery` | `filter(String hardcodedFilter)` Specify a hardcoded filter.
    `LdapQuery` | `filter(String filterFormat, Object... params)` Specify a hardcoded filter using the specified parameters.
    `static LdapQueryBuilder` | `query()` Construct a new LdapQueryBuilder.
    `SearchScope` | `searchScope()` Get the search scope.
    `LdapQueryBuilder` | `searchScope(SearchScope searchScope)` Set the search scope for the query.
    `Integer` | `timeLimit()` Get the time limit.
    `LdapQueryBuilder` | `timeLimit(int timeLimit)` Set the time limit for the query.
    `ConditionCriteria` | `where(String attribute)` Start specifying the filter conditions in this query.

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

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

- - ### Method Detail

    - #### query

          public static LdapQueryBuilder query()

      Construct a new LdapQueryBuilder.
      Returns:
        a new instance.

    - #### base

          public LdapQueryBuilder base(String baseDn)

      Set the base search path for the query. Default is `LdapUtils.emptyLdapName()`.
      Parameters:
        `baseDn` - the base search path.
      Returns:
        this instance.

    - #### base

          public LdapQueryBuilder base(Name baseDn)

      Set the base search path for the query. Default is `LdapUtils.emptyLdapName()`.
      Parameters:
        `baseDn` - the base search path.
      Returns:
        this instance.

    - #### searchScope

          public LdapQueryBuilder searchScope(SearchScope searchScope)

      Set the search scope for the query. Default is `SearchScope.SUBTREE`.
      Parameters:
        `searchScope` - the search scope.
      Returns:
        this instance.

    - #### countLimit

          public LdapQueryBuilder countLimit(int countLimit)

      Set the count limit for the query. Default is 0 (no limit).
      Parameters:
        `countLimit` - the count limit.
      Returns:
        this instance.

    - #### attributes

          public LdapQueryBuilder attributes(String... attributesToReturn)

    - #### timeLimit

          public LdapQueryBuilder timeLimit(int timeLimit)

      Set the time limit for the query. Default is 0 (no limit).
      Parameters:
        `timeLimit` - the time limit.
      Returns:
        this instance.

    - #### where

          public ConditionCriteria where(String attribute)

      Start specifying the filter conditions in this query.
      Parameters:
        `attribute` - The attribute that the first part of the filter should test against.
      Returns:
        A ConditionCriteria instance for specifying the compare operation.
      Throws:
        `IllegalStateException` - if a filter has already been specified.

    - #### filter

          public LdapQuery filter(String hardcodedFilter)

      Specify a hardcoded filter. Please note that using this method, the filter string will not be validated or escaped in any way. Never use direct user input and use it concatenating strings to use as LDAP filters. Doing so opens up for "LDAP injection", where malicious user may inject specifically constructed data to form filters at their convenience. When user input is used consider using `where(String)`, `filter(String, Object...)`, or `filter(Filter)` instead.
      Parameters:
        `hardcodedFilter` - The hardcoded filter string to use in the search.
      Returns:
        this instance.
      Throws:
        `IllegalStateException` - if a filter has already been specified.

    - #### filter

          public LdapQuery filter(Filter filter)

      Specify the filter to use.
      Parameters:
        `filter` - The filter to use in the search.
      Returns:
        this instance.
      Throws:
        `IllegalStateException` - if a filter has already been specified.

    - #### filter

          public LdapQuery filter(String filterFormat,
                                  Object... params)

      Specify a hardcoded filter using the specified parameters. The parameters will be properly encoded using `LdapEncoder.filterEncode(String)` to make sure no malicious data gets through. The `filterFormat` String should be formatted for input to `MessageFormat.format(String, Object...)`.
      Parameters:
        `filterFormat` - the filter format string, formatted for input to `MessageFormat.format(String, Object...)`.
        `params` - the parameters that will be used for building the final filter. All parameters will be properly encoded.
      Returns:
        this instance.
      Throws:
        `IllegalStateException` - if a filter has already been specified.

    - #### base

          public Name base()

      Description copied from interface: `LdapQuery`
      Get the search base. Default is `LdapUtils.emptyLdapName()`.
      Specified by:
        `base` in interface `LdapQuery`
      Returns:
        the search base.

    - #### searchScope

          public SearchScope searchScope()

      Description copied from interface: `LdapQuery`
      Get the search scope. Default is `null`, indicating that the LdapTemplate default should be used.
      Specified by:
        `searchScope` in interface `LdapQuery`
      Returns:
        the search scope.

    - #### countLimit

          public Integer countLimit()

      Description copied from interface: `LdapQuery`
      Get the count limit. Default is `null`, indicating that the LdapTemplate default should be used.
      Specified by:
        `countLimit` in interface `LdapQuery`
      Returns:
        the count limit.

    - #### timeLimit

          public Integer timeLimit()

      Description copied from interface: `LdapQuery`
      Get the time limit. Default is `null`, indicating that the LdapTemplate default should be used.
      Specified by:
        `timeLimit` in interface `LdapQuery`
      Returns:
        the time limit.

    - #### attributes

          public String[] attributes()

      Description copied from interface: `LdapQuery`
      Get the attributes to return. Default is `null`, indicating that all attributes should be returned.
      Specified by:
        `attributes` in interface `LdapQuery`
      Returns:
        the attributes to return.

    - #### filter

          public Filter filter()

      Description copied from interface: `LdapQuery`
      Get the filter.
      Specified by:
        `filter` in interface `LdapQuery`
      Returns:
        the filter.