com.unboundid.ldap.sdk
Class SearchRequest

java.lang.Object
  extended by com.unboundid.ldap.sdk.LDAPRequest
      extended by com.unboundid.ldap.sdk.UpdatableLDAPRequest
          extended by 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:

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:
Serialized Form

Field Summary
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
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, 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
 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.
 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, getResponseTimeoutMillis, hasControl, hasControl, setFollowReferrals, setIntermediateResponseListener, 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, getResponseTimeoutMillis, hasControl, hasControl, toString
 

Field Detail

ALL_USER_ATTRIBUTES

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

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

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

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(java.lang.String baseDN,
                     SearchScope scope,
                     java.lang.String filter,
                     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(java.lang.String baseDN,
                     SearchScope scope,
                     Filter filter,
                     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(SearchResultListener searchResultListener,
                     java.lang.String baseDN,
                     SearchScope scope,
                     java.lang.String filter,
                     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(SearchResultListener searchResultListener,
                     java.lang.String baseDN,
                     SearchScope scope,
                     Filter filter,
                     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(java.lang.String baseDN,
                     SearchScope scope,
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     java.lang.String filter,
                     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(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. 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(SearchResultListener searchResultListener,
                     java.lang.String baseDN,
                     SearchScope scope,
                     DereferencePolicy derefPolicy,
                     int sizeLimit,
                     int timeLimit,
                     boolean typesOnly,
                     java.lang.String filter,
                     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(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.

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(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)
              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(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.

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

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.

setBaseDN

public void setBaseDN(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(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

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(SearchScope scope)
Specifies the scope for this search request.

Parameters:
scope - The scope for this search request.

getDereferencePolicy

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(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

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(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(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

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

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(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(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

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(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

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

protected SearchResult process(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(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

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

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

public SearchRequest duplicate(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(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(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.

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).