Package com.unboundid.ldap.sdk
Class SearchRequest
- java.lang.Object
-
- com.unboundid.ldap.sdk.LDAPRequest
-
- com.unboundid.ldap.sdk.UpdatableLDAPRequest
-
- com.unboundid.ldap.sdk.SearchRequest
-
- All Implemented Interfaces:
ProtocolOp
,ReadOnlyLDAPRequest
,ReadOnlySearchRequest
,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 asFilter
objects. As noted in the documentation for theFilter
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 useFilter
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.
- 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 isnull
, then the entries and references will be collected and returned in theSearchResult
object that is returned.
- If the
LDAPInterface.search(SearchRequest)
method is used and the provided search request does not include aSearchResultListener
object, then the entries and references will be collected internally and made available in theSearchResult
object that is returned. - If the
LDAPInterface.search(SearchRequest)
method is used and the provided search request does include aSearchResultListener
object, then that listener will be used to provide access to the entries and references, and they will not be present in theSearchResult
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 anIterator
-like API to provide access to the entries that are returned, and any references returned will be included in theEntrySourceException
thrown on the appropriate call toLDAPEntrySource.nextEntry()
.
SearchRequest
objects are mutable and therefore can be altered and re-used for multiple requests. Note, however, thatSearchRequest
objects are not threadsafe and therefore a singleSearchRequest
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 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 Description 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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.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)
void
setAttributes(java.lang.String... attributes)
Specifies the set of requested attributes to include in matching entries.void
setAttributes(java.util.List<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, getResponseTimeoutMillis, hasControl, hasControl, setFollowReferrals, setIntermediateResponseListener, setReferralConnector, 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
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 theSearchResult
object returned when search processing is completed.- Parameters:
baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 theSearchResult
object returned when search processing is completed.- Parameters:
baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 benull
if the search results should be collected internally and returned in theSearchResult
object.baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 benull
if the search results should be collected internally and returned in theSearchResult
object.baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 theSearchResult
object returned when search processing is completed.- Parameters:
baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 theSearchResult
object returned when search processing is completed.- Parameters:
baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 benull
if the search results should be collected internally and returned in theSearchResult
object.baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 benull
if the search results should be collected internally and returned in theSearchResult
object.baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 benull
if the search results should be collected internally and returned in theSearchResult
object.controls
- The set of controls to include in the request. It may benull
or empty if no controls should be included in the request.baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 benull
if the search results should be collected internally and returned in theSearchResult
object.controls
- The set of controls to include in the request. It may benull
or empty if no controls should be included in the request.baseDN
- The base DN for the search request. It must not benull
.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 benull
.attributes
- The set of attributes that should be returned in matching entries. It may benull
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 interfaceReadOnlySearchRequest
- 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 benull
.
-
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 benull
.
-
getScope
public SearchScope getScope()
Retrieves the scope for this search request.- Specified by:
getScope
in interfaceReadOnlySearchRequest
- 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 interfaceReadOnlySearchRequest
- 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 interfaceReadOnlySearchRequest
- 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, anLDAPSearchException
will be thrown. If one or more entries or references have already been returned for the search, then theLDAPSearchException
methods likegetEntryCount
,getSearchEntries
,getReferenceCount
, andgetSearchReferences
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 thegetSearchEntries
andgetSearchReferences
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 interfaceReadOnlySearchRequest
- 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, anLDAPSearchException
will be thrown. If one or more entries or references have already been returned for the search, then theLDAPSearchException
methods likegetEntryCount
,getSearchEntries
,getReferenceCount
, andgetSearchReferences
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 thegetSearchEntries
andgetSearchReferences
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 interfaceReadOnlySearchRequest
- Returns:
true
if matching entries should include only attribute names, orfalse
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 interfaceReadOnlySearchRequest
- 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 benull
.- 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 benull
.
-
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 interfaceReadOnlySearchRequest
- 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 benull
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 benull
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 interfaceProtocolOp
- 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 interfaceProtocolOp
- 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 interfaceProtocolOp
- 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 theSearchResult
object that is returned, or will be interactively returned via theSearchResultListener
interface.- Specified by:
process
in classLDAPRequest
- 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
- Throws:
LDAPException
-
getLastMessageID
public int getLastMessageID()
Retrieves the message ID for the last LDAP message sent using this request.- Specified by:
getLastMessageID
in classLDAPRequest
- 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 classLDAPRequest
- 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 interfaceReadOnlyLDAPRequest
- Specified by:
duplicate
in interfaceReadOnlySearchRequest
- 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 interfaceReadOnlyLDAPRequest
- Specified by:
duplicate
in interfaceReadOnlySearchRequest
- 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 interfaceProtocolOp
- Specified by:
toString
in interfaceReadOnlyLDAPRequest
- Specified by:
toString
in classLDAPRequest
- 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 interfaceReadOnlyLDAPRequest
- 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 isnull
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 (iftrue
), or just to generate the request (iffalse
).
-
-