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, java.io.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:

• If the LDAPInterface.search(SearchRequest) method is used and the provided search request does not include a SearchResultListener object, then the entries and references will be collected internally and made available in the SearchResult object that is returned.
• If the LDAPInterface.search(SearchRequest) method is used and the provided search request does include a SearchResultListener object, then that listener will be used to provide access to the entries and references, and they will not be present in the SearchResult object (although the number of entries and references returned will still be available).
• The LDAPEntrySource object may be used to access the entries and references returned from the search. It uses an Iterator-like API to provide access to the entries that are returned, and any references returned will be included in the EntrySourceException thrown on the appropriate call to LDAPEntrySource.nextEntry().

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:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.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.
static java.lang.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.
static java.lang.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.
static java.lang.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 Summary

Constructors

Constructor and Description
SearchRequest(DN baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(DN baseDN, SearchScope scope, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, Control[] controls, DN baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, Control[] controls, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, Control[] controls, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, java.lang.String filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, DN baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, DN baseDN, SearchScope scope, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, java.lang.String filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, java.lang.String baseDN, SearchScope scope, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(SearchResultListener searchResultListener, java.lang.String baseDN, SearchScope scope, java.lang.String filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(java.lang.String baseDN, SearchScope scope, DereferencePolicy derefPolicy, int sizeLimit, int timeLimit, boolean typesOnly, java.lang.String filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(java.lang.String baseDN, SearchScope scope, Filter filter, java.lang.String... attributes) Creates a new search request with the provided information.
SearchRequest(java.lang.String baseDN, SearchScope scope, java.lang.String filter, java.lang.String... attributes) Creates a new search request with the provided information.

Method Summary

Modifier and Type	Method and Description
SearchRequest	duplicate() Creates a new instance of this LDAP request that may be modified without impacting this request.
SearchRequest	duplicate(Control[] controls) Creates a new instance of this LDAP request that may be modified without impacting this request.
ASN1Element	encodeProtocolOp() Encodes the search request protocol op to an ASN.1 element.
java.util.List<java.lang.String>	getAttributeList() Retrieves the set of requested attributes to include in matching entries.
java.lang.String[]	getAttributes() Retrieves the set of requested attributes to include in matching entries.
java.lang.String	getBaseDN() Retrieves the base DN for this search request.
DereferencePolicy	getDereferencePolicy() Retrieves the dereference policy that should be used by the server for any aliases encountered during search processing.
Filter	getFilter() Retrieves the filter that should be used to identify matching entries.
int	getLastMessageID() Retrieves the message ID for the last LDAP message sent using this request.
OperationType	getOperationType() Retrieves the type of operation that is represented by this request.
DN	getParsedBaseDN() Retrieves the base DN for this search request, parsed as a DN object.
byte	getProtocolOpType() Retrieves the BER type for this protocol op.
SearchScope	getScope() Retrieves the scope for this search request.
SearchResultListener	getSearchResultListener() Retrieves the search result listener for this search request, if available.
int	getSizeLimit() Retrieves the maximum number of entries that should be returned by the server when processing this search request.
int	getTimeLimitSeconds() Retrieves the maximum length of time in seconds that the server should spend processing this search request.
protected SearchResult	process(LDAPConnection connection, int depth) Sends this search request to the directory server over the provided connection and returns the associated response.
void	responseReceived(LDAPResponse response) Indicates that the provided LDAP response has been received by from the server.
void	setAttributes(java.util.List<java.lang.String> attributes) Specifies the set of requested attributes to include in matching entries.
void	setAttributes(java.lang.String... attributes) Specifies the set of requested attributes to include in matching entries.
void	setBaseDN(DN baseDN) Specifies the base DN for this search request.
void	setBaseDN(java.lang.String baseDN) Specifies the base DN for this search request.
void	setDerefPolicy(DereferencePolicy derefPolicy) Specifies the dereference policy that should be used by the server for any aliases encountered during search processing.
void	setFilter(Filter filter) Specifies the filter that should be used to identify matching entries.
void	setFilter(java.lang.String filter) Specifies the filter that should be used to identify matching entries.
void	setScope(SearchScope scope) Specifies the scope for this search request.
void	setSizeLimit(int sizeLimit) Specifies the maximum number of entries that should be returned by the server when processing this search request.
void	setTimeLimitSeconds(int timeLimit) Specifies the maximum length of time in seconds that the server should spend processing this search request.
void	setTypesOnly(boolean typesOnly) Specifies whether the server should return only attribute names in matching entries, rather than both names and values.
void	toCode(java.util.List<java.lang.String> lineList, java.lang.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.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this request to the provided buffer.
boolean	typesOnly() Indicates whether the server should return only attribute names in matching entries, rather than both names and values.
void	writeTo(ASN1Buffer writer) Writes an ASN.1-encoded representation of this LDAP protocol op to the provided ASN.1 buffer.

Methods inherited from class com.unboundid.ldap.sdk.UpdatableLDAPRequest

addControl, addControls, clearControls, removeControl, removeControl, replaceControl, replaceControl, setControls, setControls

Methods inherited from class com.unboundid.ldap.sdk.LDAPRequest

followReferrals, getControl, getControlList, getControls, getIntermediateResponseListener, getReferralConnector, getReferralConnectorInternal, getReferralDepth, getResponseTimeoutMillis, hasControl, hasControl, setFollowReferrals, setIntermediateResponseListener, setReferralConnector, setReferralDepth, setResponseTimeoutMillis, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.unboundid.ldap.sdk.ReadOnlyLDAPRequest

followReferrals, getControl, getControlList, getControls, getReferralConnector, getResponseTimeoutMillis, hasControl, hasControl, toString

Field Detail

ALL_USER_ATTRIBUTES

@NotNull
public static final java.lang.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:

Constant Field Values

ALL_OPERATIONAL_ATTRIBUTES

@NotNull
public static final java.lang.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:

Constant Field Values

NO_ATTRIBUTES

@NotNull
public static final java.lang.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:

Constant Field Values

REQUEST_ATTRS_DEFAULT

@NotNull
public static final java.lang.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 Detail

SearchRequest

public SearchRequest(@NotNull
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     java.lang.String filter,
                     @Nullable
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     Filter filter,
                     @Nullable
                     java.lang.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
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     java.lang.String filter,
                     @Nullable
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     Filter filter,
                     @Nullable
                     java.lang.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
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     @NotNull
                     java.lang.String filter,
                     @Nullable
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     @NotNull
                     Filter filter,
                     @Nullable
                     java.lang.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
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     @NotNull
                     java.lang.String filter,
                     @Nullable
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     @NotNull
                     Filter filter,
                     @Nullable
                     java.lang.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
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     @NotNull
                     java.lang.String filter,
                     @Nullable
                     java.lang.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
                     java.lang.String baseDN,
                     @NotNull
                     SearchScope scope,
                     @NotNull
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     @NotNull
                     Filter filter,
                     @Nullable
                     java.lang.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
                     java.lang.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 Detail

getBaseDN

@NotNull
public java.lang.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
                      java.lang.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
                      java.lang.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 java.lang.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 java.util.List<java.lang.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
                          java.lang.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
                          java.util.List<java.lang.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

Indicates that the provided LDAP response has been received by from the server.

Parameters:

response - The LDAP response that has been received from the server. It may be null if the connection has been closed without having received any response.

Throws:

LDAPException - If a problem occurs while handling the response.

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
                     java.lang.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
                   java.util.List<java.lang.String> lineList,
                   @NotNull
                   java.lang.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).