Package com.unboundid.ldap.sdk

Class SearchRequest

java.lang.Object
com.unboundid.ldap.sdk.LDAPRequest
com.unboundid.ldap.sdk.UpdatableLDAPRequest
com.unboundid.ldap.sdk.SearchRequest
All Implemented Interfaces:
ProtocolOp, ReadOnlyLDAPRequest, ReadOnlySearchRequest, Serializable
@Mutable @ThreadSafety(level=NOT_THREADSAFE) public final class SearchRequest extends UpdatableLDAPRequest implements ReadOnlySearchRequest, ProtocolOp
This class implements the processing necessary to perform an LDAPv3 search operation, which can be used to retrieve entries that match a given set of criteria. A search request may include the following elements:
  • Base DN -- Specifies the base DN for the search. Only entries at or below this location in the server (based on the scope) will be considered potential matches.
  • Scope -- Specifies the range of entries relative to the base DN that may be considered potential matches.
  • Dereference Policy -- Specifies the behavior that the server should exhibit if any alias entries are encountered while processing the search. If no dereference policy is provided, then a default of DereferencePolicy.NEVER will be used.
  • Size Limit -- Specifies the maximum number of entries that should be returned from the search. A value of zero indicates that there should not be any limit enforced. Note that the directory server may also be configured with a server-side size limit which can also limit the number of entries that may be returned to the client and in that case the smaller of the client-side and server-side limits will be used. If no size limit is provided, then a default of zero (unlimited) will be used.
  • Time Limit -- Specifies the maximum length of time in seconds that the server should spend processing the search. A value of zero indicates that there should not be any limit enforced. Note that the directory server may also be configured with a server-side time limit which can also limit the processing time, and in that case the smaller of the client-side and server-side limits will be used. If no time limit is provided, then a default of zero (unlimited) will be used.
  • Types Only -- Indicates whether matching entries should include only attribute names, or both attribute names and values. If no value is provided, then a default of false will be used.
  • Filter -- Specifies the criteria for determining which entries should be returned. See the Filter class for the types of filters that may be used.

    Note that filters can be specified using either their string representations or as Filter objects. As noted in the documentation for the Filter class, using the string representation may be somewhat dangerous if the data is not properly sanitized because special characters contained in the filter may cause it to be invalid or worse expose a vulnerability that could cause the filter to request more information than was intended. As a result, if the filter may include special characters or user-provided strings, then it is recommended that you use Filter objects created from their individual components rather than their string representations.
  • Attributes -- Specifies the set of attributes that should be included in matching entries. If no attributes are provided, then the server will default to returning all user attributes. If a specified set of attributes is given, then only those attributes will be included. Values that may be included to indicate a special meaning include:
    • NO_ATTRIBUTES -- Indicates that no attributes should be returned. That is, only the DNs of matching entries will be returned.
    • ALL_USER_ATTRIBUTES -- Indicates that all user attributes should be included in matching entries. This is the default if no attributes are provided, but this special value may be included if a specific set of operational attributes should be included along with all user attributes.
    • ALL_OPERATIONAL_ATTRIBUTES -- Indicates that all operational attributes should be included in matching entries.
    These special values may be used alone or in conjunction with each other and/or any specific attribute names or OIDs.
  • An optional set of controls to include in the request to send to the server.
  • An optional SearchResultListener which may be used to process search result entries and search result references returned by the server in the course of processing the request. If this is null, then the entries and references will be collected and returned in the SearchResult object that is returned.
When processing a search operation, there are three ways that the returned entries and references may be accessed:

SearchRequest objects are mutable and therefore can be altered and re-used for multiple requests. Note, however, that SearchRequest objects are not threadsafe and therefore a single SearchRequest object instance should not be used to process multiple requests at the same time.

Example

The following example demonstrates a simple search operation in which the client performs a search to find all users in the "Sales" department and then retrieves the name and e-mail address for each matching user: 
 // Construct a filter that can be used to find everyone in the Sales
 // department, and then create a search request to find all such users
 // in the directory.
 Filter filter = Filter.createEqualityFilter("ou", "Sales");
 SearchRequest searchRequest =
      new SearchRequest("dc=example,dc=com", SearchScope.SUB, filter,
           "cn", "mail");
 SearchResult searchResult;

 try
 {
   searchResult = connection.search(searchRequest);

   for (SearchResultEntry entry : searchResult.getSearchEntries())
   {
     String name = entry.getAttributeValue("cn");
     String mail = entry.getAttributeValue("mail");
   }
 }
 catch (LDAPSearchException lse)
 {
   // The search failed for some reason.
   searchResult = lse.getSearchResult();
   ResultCode resultCode = lse.getResultCode();
   String errorMessageFromServer = lse.getDiagnosticMessage();
 }
See Also:

  • Field Details

    • ALL_USER_ATTRIBUTES

      @NotNull public static final String ALL_USER_ATTRIBUTES
      The special value "*" that can be included in the set of requested attributes to indicate that all user attributes should be returned.
      See Also:

    • ALL_OPERATIONAL_ATTRIBUTES

      @NotNull public static final String ALL_OPERATIONAL_ATTRIBUTES
      The special value "+" that can be included in the set of requested attributes to indicate that all operational attributes should be returned.
      See Also:

    • NO_ATTRIBUTES

      @NotNull public static final String NO_ATTRIBUTES
      The special value "1.1" that can be included in the set of requested attributes to indicate that no attributes should be returned, with the exception of any other attributes explicitly named in the set of requested attributes.
      See Also:

    • REQUEST_ATTRS_DEFAULT

      @NotNull public static final String[] REQUEST_ATTRS_DEFAULT
      The default set of requested attributes that will be used, which will return all user attributes but no operational attributes.

  • Constructor Details

    • SearchRequest

      public SearchRequest(@NotNull String baseDN, @NotNull SearchScope scope, @NotNull String filter, @Nullable String... attributes) throws LDAPException
      Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
      Parameters:
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      filter - The string representation of the filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      Throws:
      LDAPException - If the provided filter string cannot be parsed as an LDAP filter.

    • SearchRequest

      public SearchRequest(@NotNull String baseDN, @NotNull SearchScope scope, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
      Parameters:
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      filter - The string representation of the filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@NotNull DN baseDN, @NotNull SearchScope scope, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
      Parameters:
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      filter - The string representation of the filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @NotNull String baseDN, @NotNull SearchScope scope, @NotNull String filter, @Nullable String... attributes) throws LDAPException
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      filter - The string representation of the filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      Throws:
      LDAPException - If the provided filter string cannot be parsed as an LDAP filter.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @NotNull String baseDN, @NotNull SearchScope scope, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      filter - The string representation of the filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @NotNull DN baseDN, @NotNull SearchScope scope, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      filter - The string representation of the filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@NotNull String baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull String filter, @Nullable String... attributes) throws LDAPException
      Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
      Parameters:
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      Throws:
      LDAPException - If the provided filter string cannot be parsed as an LDAP filter.

    • SearchRequest

      public SearchRequest(@NotNull String baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
      Parameters:
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@NotNull DN baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information. Search result entries and references will be collected internally and included in the SearchResult object returned when search processing is completed.
      Parameters:
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @NotNull String baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull String filter, @Nullable String... attributes) throws LDAPException
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      Throws:
      LDAPException - If the provided filter string cannot be parsed as an LDAP filter.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @NotNull String baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @NotNull DN baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @Nullable Control[] controls, @NotNull String baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull String filter, @Nullable String... attributes) throws LDAPException
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      controls - The set of controls to include in the request. It may be null or empty if no controls should be included in the request.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.
      Throws:
      LDAPException - If the provided filter string cannot be parsed as an LDAP filter.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @Nullable Control[] controls, @NotNull String baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      controls - The set of controls to include in the request. It may be null or empty if no controls should be included in the request.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

    • SearchRequest

      public SearchRequest(@Nullable SearchResultListener searchResultListener, @Nullable Control[] controls, @NotNull DN baseDN, @NotNull SearchScope scope, @NotNull DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, @NotNull Filter filter, @Nullable String... attributes)
      Creates a new search request with the provided information.
      Parameters:
      searchResultListener - The search result listener that should be used to return results to the client. It may be null if the search results should be collected internally and returned in the SearchResult object.
      controls - The set of controls to include in the request. It may be null or empty if no controls should be included in the request.
      baseDN - The base DN for the search request. It must not be null.
      scope - The scope that specifies the range of entries that should be examined for the search.
      derefPolicy - The dereference policy the server should use for any aliases encountered while processing the search.
      sizeLimit - The maximum number of entries that the server should return for the search. A value of zero indicates that there should be no limit.
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.
      typesOnly - Indicates whether to return only attribute names in matching entries, or both attribute names and values.
      filter - The filter to use to identify matching entries. It must not be null.
      attributes - The set of attributes that should be returned in matching entries. It may be null or empty if the default attribute set (all user attributes) is to be requested.

  • Method Details

    • getBaseDN

      @NotNull public String getBaseDN()
      Retrieves the base DN for this search request.
      Specified by:
      getBaseDN in interface ReadOnlySearchRequest
      Returns:
      The base DN for this search request.

    • getParsedBaseDN

      @NotNull public DN getParsedBaseDN() throws LDAPException
      Retrieves the base DN for this search request, parsed as a DN object.
      Specified by:
      getParsedBaseDN in interface ReadOnlySearchRequest
      Returns:
      The base DN for this search request, parsed as a DN object.
      Throws:
      LDAPException - If the base DN string cannot be parsed as a valid DN.

    • setBaseDN

      public void setBaseDN(@NotNull String baseDN)
      Specifies the base DN for this search request.
      Parameters:
      baseDN - The base DN for this search request. It must not be null.

    • setBaseDN

      public void setBaseDN(@NotNull DN baseDN)
      Specifies the base DN for this search request.
      Parameters:
      baseDN - The base DN for this search request. It must not be null.

    • getScope

      @NotNull public SearchScope getScope()
      Retrieves the scope for this search request.
      Specified by:
      getScope in interface ReadOnlySearchRequest
      Returns:
      The scope for this search request.

    • setScope

      public void setScope(@NotNull SearchScope scope)
      Specifies the scope for this search request.
      Parameters:
      scope - The scope for this search request.

    • getDereferencePolicy

      @NotNull public DereferencePolicy getDereferencePolicy()
      Retrieves the dereference policy that should be used by the server for any aliases encountered during search processing.
      Specified by:
      getDereferencePolicy in interface ReadOnlySearchRequest
      Returns:
      The dereference policy that should be used by the server for any aliases encountered during search processing.

    • setDerefPolicy

      public void setDerefPolicy(@NotNull DereferencePolicy derefPolicy)
      Specifies the dereference policy that should be used by the server for any aliases encountered during search processing.
      Parameters:
      derefPolicy - The dereference policy that should be used by the server for any aliases encountered during search processing.

    • getSizeLimit

      public int getSizeLimit()
      Retrieves the maximum number of entries that should be returned by the server when processing this search request.
      Specified by:
      getSizeLimit in interface ReadOnlySearchRequest
      Returns:
      The maximum number of entries that should be returned by the server when processing this search request, or zero if there is no limit.

    • setSizeLimit

      public void setSizeLimit(int sizeLimit)
      Specifies the maximum number of entries that should be returned by the server when processing this search request. A value of zero indicates that there should be no limit.

      Note that if an attempt to process a search operation fails because the size limit has been exceeded, an LDAPSearchException will be thrown. If one or more entries or references have already been returned for the search, then the LDAPSearchException methods like getEntryCount, getSearchEntries, getReferenceCount, and getSearchReferences may be used to obtain information about those entries and references (although if a search result listener was provided, then it will have been used to make any entries and references available, and they will not be available through the getSearchEntries and getSearchReferences methods).
      Parameters:
      sizeLimit - The maximum number of entries that should be returned by the server when processing this search request.

    • getTimeLimitSeconds

      public int getTimeLimitSeconds()
      Retrieves the maximum length of time in seconds that the server should spend processing this search request.
      Specified by:
      getTimeLimitSeconds in interface ReadOnlySearchRequest
      Returns:
      The maximum length of time in seconds that the server should spend processing this search request, or zero if there is no limit.

    • setTimeLimitSeconds

      public void setTimeLimitSeconds(int timeLimit)
      Specifies the maximum length of time in seconds that the server should spend processing this search request. A value of zero indicates that there should be no limit.

      Note that if an attempt to process a search operation fails because the time limit has been exceeded, an LDAPSearchException will be thrown. If one or more entries or references have already been returned for the search, then the LDAPSearchException methods like getEntryCount, getSearchEntries, getReferenceCount, and getSearchReferences may be used to obtain information about those entries and references (although if a search result listener was provided, then it will have been used to make any entries and references available, and they will not be available through the getSearchEntries and getSearchReferences methods).
      Parameters:
      timeLimit - The maximum length of time in seconds that the server should spend processing this search request.

    • typesOnly

      public boolean typesOnly()
      Indicates whether the server should return only attribute names in matching entries, rather than both names and values.
      Specified by:
      typesOnly in interface ReadOnlySearchRequest
      Returns:
      true if matching entries should include only attribute names, or false if matching entries should include both attribute names and values.

    • setTypesOnly

      public void setTypesOnly(boolean typesOnly)
      Specifies whether the server should return only attribute names in matching entries, rather than both names and values.
      Parameters:
      typesOnly - Specifies whether the server should return only attribute names in matching entries, rather than both names and values.

    • getFilter

      @NotNull public Filter getFilter()
      Retrieves the filter that should be used to identify matching entries.
      Specified by:
      getFilter in interface ReadOnlySearchRequest
      Returns:
      The filter that should be used to identify matching entries.

    • setFilter

      public void setFilter(@NotNull String filter) throws LDAPException
      Specifies the filter that should be used to identify matching entries.
      Parameters:
      filter - The string representation for the filter that should be used to identify matching entries. It must not be null.
      Throws:
      LDAPException - If the provided filter string cannot be parsed as a search filter.

    • setFilter

      public void setFilter(@NotNull Filter filter)
      Specifies the filter that should be used to identify matching entries.
      Parameters:
      filter - The filter that should be used to identify matching entries. It must not be null.

    • getAttributes

      @NotNull public String[] getAttributes()
      Retrieves the set of requested attributes to include in matching entries. The caller must not attempt to alter the contents of the array.
      Returns:
      The set of requested attributes to include in matching entries, or an empty array if the default set of attributes (all user attributes but no operational attributes) should be requested.

    • getAttributeList

      @NotNull public List<String> getAttributeList()
      Retrieves the set of requested attributes to include in matching entries.
      Specified by:
      getAttributeList in interface ReadOnlySearchRequest
      Returns:
      The set of requested attributes to include in matching entries, or an empty array if the default set of attributes (all user attributes but no operational attributes) should be requested.

    • setAttributes

      public void setAttributes(@Nullable String... attributes)
      Specifies the set of requested attributes to include in matching entries.
      Parameters:
      attributes - The set of requested attributes to include in matching entries. It may be null if the default set of attributes (all user attributes but no operational attributes) should be requested.

    • setAttributes

      public void setAttributes(@Nullable List<String> attributes)
      Specifies the set of requested attributes to include in matching entries.
      Parameters:
      attributes - The set of requested attributes to include in matching entries. It may be null if the default set of attributes (all user attributes but no operational attributes) should be requested.

    • getSearchResultListener

      @Nullable public SearchResultListener getSearchResultListener()
      Retrieves the search result listener for this search request, if available.
      Returns:
      The search result listener for this search request, or null if none has been configured.

    • getProtocolOpType

      public byte getProtocolOpType()
      Retrieves the BER type for this protocol op.
      Specified by:
      getProtocolOpType in interface ProtocolOp
      Returns:
      The BER type for this protocol op.

    • writeTo

      public void writeTo(@NotNull ASN1Buffer writer)
      Writes an ASN.1-encoded representation of this LDAP protocol op to the provided ASN.1 buffer. This method is intended for internal use only and should not be used by third-party code.
      Specified by:
      writeTo in interface ProtocolOp
      Parameters:
      writer - The ASN.1 buffer to which the encoded representation should be written.

    • encodeProtocolOp

      @NotNull public ASN1Element encodeProtocolOp()
      Encodes the search request protocol op to an ASN.1 element.
      Specified by:
      encodeProtocolOp in interface ProtocolOp
      Returns:
      The ASN.1 element with the encoded search request protocol op.

    • process

      @NotNull protected SearchResult process(@NotNull LDAPConnection connection, int depth) throws LDAPException
      Sends this search request to the directory server over the provided connection and returns the associated response. The search result entries and references will either be collected and returned in the SearchResult object that is returned, or will be interactively returned via the SearchResultListener interface.
      Specified by:
      process in class LDAPRequest
      Parameters:
      connection - The connection to use to communicate with the directory server.
      depth - The current referral depth for this request. It should always be one for the initial request, and should only be incremented when following referrals.
      Returns:
      An object that provides information about the result of the search processing, potentially including the sets of matching entries and/or search references.
      Throws:
      LDAPException - If a problem occurs while sending the request or reading the response.

    • responseReceived

      @InternalUseOnly public void responseReceived(@NotNull LDAPResponse response) throws LDAPException
      Throws:
      LDAPException

    • getLastMessageID

      public int getLastMessageID()
      Retrieves the message ID for the last LDAP message sent using this request.
      Specified by:
      getLastMessageID in class LDAPRequest
      Returns:
      The message ID for the last LDAP message sent using this request, or -1 if it no LDAP messages have yet been sent using this request.

    • getOperationType

      @NotNull public OperationType getOperationType()
      Retrieves the type of operation that is represented by this request.
      Specified by:
      getOperationType in class LDAPRequest
      Returns:
      The type of operation that is represented by this request.

    • duplicate

      @NotNull public SearchRequest duplicate()
      Creates a new instance of this LDAP request that may be modified without impacting this request.
      Specified by:
      duplicate in interface ReadOnlyLDAPRequest
      Specified by:
      duplicate in interface ReadOnlySearchRequest
      Returns:
      A new instance of this LDAP request that may be modified without impacting this request.

    • duplicate

      @NotNull public SearchRequest duplicate(@Nullable Control[] controls)
      Creates a new instance of this LDAP request that may be modified without impacting this request. The provided controls will be used for the new request instead of duplicating the controls from this request.
      Specified by:
      duplicate in interface ReadOnlyLDAPRequest
      Specified by:
      duplicate in interface ReadOnlySearchRequest
      Parameters:
      controls - The set of controls to include in the duplicate request.
      Returns:
      A new instance of this LDAP request that may be modified without impacting this request.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this request to the provided buffer.
      Specified by:
      toString in interface ProtocolOp
      Specified by:
      toString in interface ReadOnlyLDAPRequest
      Specified by:
      toString in class LDAPRequest
      Parameters:
      buffer - The buffer to which to append a string representation of this request.

    • toCode

      public void toCode(@NotNull List<String> lineList, @NotNull String requestID, int indentSpaces, boolean includeProcessing)
      Appends a number of lines comprising the Java source code that can be used to recreate this request to the given list.
      Specified by:
      toCode in interface ReadOnlyLDAPRequest
      Parameters:
      lineList - The list to which the source code lines should be added.
      requestID - The name that should be used as an identifier for the request. If this is null or empty, then a generic ID will be used.
      indentSpaces - The number of spaces that should be used to indent the generated code. It must not be negative.
      includeProcessing - Indicates whether the generated code should include code required to actually process the request and handle the result (if true), or just to generate the request (if false).