org.forgerock.opendj.ldap.messages

Interface SearchRequest

All Superinterfaces:

ProtocolOp, Request

public interface SearchRequest
extends Request

The Search operation is used to request a server to return, subject to access controls and other restrictions, a set of entries matching a complex search criterion. This can be used to read attributes from a single entry, from entries immediately subordinate to a particular entry, or from a whole subtree of entries.

Use Requests.newSearchRequest(Dn, SearchScope, Filter, String...) or Requests.newSearchRequest(String, SearchScope, String, String...) to create a new search request.

 SearchRequest request = Requests.newSearchRequest("dc=example,dc=com", SearchScope.WHOLE_SUBTREE,
         "(sn=Jensen)", "cn");
 

Alternatively, use the Connection.search() method to specify the arguments directly.

 Connection connection = ...;
 ConnectionEntryReader reader = connection.search(
          "dc=example,dc=com", SearchScope.WHOLE_SUBTREE, "(sn=Jensen)", "cn");
 

Nested Class Summary

Nested classes/interfaces inherited from interface org.forgerock.opendj.ldap.messages.Request

Request.RequestType

Method Summary

Modifier and Type	Method and Description
SearchRequest	addAttribute(String... attributeDescriptions) Adds the provided attribute name(s) to the list of attributes to be included with each entry that matches the search criteria.
SearchRequest	addControl(Control control) Adds the provided control to this protocol-op.
SearchRequest	addControls(Iterable<? extends Control> controls) Adds the provided controls to this protocol-op.
List<String>	getAttributes() Returns a List containing the list of attributes to be included with each entry that matches the search criteria.
<C extends Control> C	getControl(ControlDecoder<C> decoder, DecodeOptions options) Decodes and returns the first control in this protocol-op having an OID corresponding to the provided control decoder.
List<Control>	getControls() Returns a List containing the controls included with this protocol-op.
DereferenceAliasesPolicy	getDereferenceAliasesPolicy() Returns an indication as to whether alias entries are to be dereferenced during the search.
Filter	getFilter() Returns the filter that defines the conditions that must be fulfilled in order for an entry to be returned.
Dn	getName() Returns the distinguished name of the base entry relative to which the search is to be performed.
SearchScope	getScope() Returns the scope of the search.
int	getSizeLimit() Returns the size limit that should be used in order to restrict the maximum number of entries returned by the search.
int	getTimeLimit() Returns the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.
boolean	isSingleEntrySearch() Indicates whether search result is expected to be limited to a single entry.
boolean	isTypesOnly() Indicates whether search results are to contain both attribute descriptions and values, or just attribute descriptions.
SearchRequest	setDereferenceAliasesPolicy(DereferenceAliasesPolicy policy) Sets the alias dereferencing policy to be used during the search.
SearchRequest	setFilter(Filter filter) Sets the filter that defines the conditions that must be fulfilled in order for an entry to be returned.
SearchRequest	setFilter(String filter) Sets the filter that defines the conditions that must be fulfilled in order for an entry to be returned.
SearchRequest	setName(Dn dn) Sets the distinguished name of the base entry relative to which the search is to be performed.
SearchRequest	setName(String dn) Sets the distinguished name of the base entry relative to which the search is to be performed.
SearchRequest	setScope(SearchScope scope) Sets the scope of the search.
SearchRequest	setSizeLimit(int limit) Sets the size limit that should be used in order to restrict the maximum number of entries returned by the search.
SearchRequest	setTimeLimit(int limit) Sets the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.
SearchRequest	setTypesOnly(boolean typesOnly) Specifies whether search results are to contain both attribute descriptions and values, or just attribute descriptions.

Methods inherited from interface org.forgerock.opendj.ldap.messages.Request

accept, getType

Methods inherited from interface org.forgerock.opendj.ldap.messages.ProtocolOp

containsControl, getControl

Method Detail

addAttribute

SearchRequest addAttribute(String... attributeDescriptions)

Adds the provided attribute name(s) to the list of attributes to be included with each entry that matches the search criteria. Attributes that are sub-types of listed attributes are implicitly included.

Parameters:

attributeDescriptions - The name(s) of the attribute to be included with each entry.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit attribute names to be added.

NullPointerException - If attributeDescriptions was null.

addControl

SearchRequest addControl(Control control)

Description copied from interface: ProtocolOp

Adds the provided control to this protocol-op.

Specified by:

addControl in interface ProtocolOp

Specified by:

addControl in interface Request

Parameters:

control - The control to be added to this protocol-op.

Returns:

This protocol-op.

addControls

SearchRequest addControls(Iterable<? extends Control> controls)

Description copied from interface: ProtocolOp

Adds the provided controls to this protocol-op.

Specified by:

addControls in interface ProtocolOp

Specified by:

addControls in interface Request

Parameters:

controls - The controls to be added to this protocol-op.

Returns:

This protocol-op.

getAttributes

List<String> getAttributes()

Returns a List containing the list of attributes to be included with each entry that matches the search criteria. Attributes that are sub-types of listed attributes are implicitly included. The returned List may be modified if permitted by this search request.

Returns:

A List containing the list of attributes.

getControl

<C extends Control> C getControl(ControlDecoder<C> decoder,
                                 DecodeOptions options)
                          throws DecodeException

Description copied from interface: ProtocolOp

Decodes and returns the first control in this protocol-op having an OID corresponding to the provided control decoder.

Specified by:

getControl in interface ProtocolOp

Type Parameters:

C - The type of control to be decoded and returned.

Parameters:

decoder - The control decoder.

options - The set of decode options which should be used when decoding the control.

Returns:

The decoded control, or null if the control is not included with this protocol-op.

Throws:

DecodeException - If the control could not be decoded because it was malformed in some way (e.g. the control value was missing, or its content could not be decoded).

getControls

List<Control> getControls()

Description copied from interface: ProtocolOp

Returns a List containing the controls included with this protocol-op. The returned List may be modified if permitted by this protocol-op.

Specified by:

getControls in interface ProtocolOp

Returns:

A List containing the controls.

getDereferenceAliasesPolicy

DereferenceAliasesPolicy getDereferenceAliasesPolicy()

Returns an indication as to whether alias entries are to be dereferenced during the search.

Returns:

The alias dereferencing policy.

getFilter

Filter getFilter()

Returns the filter that defines the conditions that must be fulfilled in order for an entry to be returned.

Returns:

The search filter.

getName

Dn getName()

Returns the distinguished name of the base entry relative to which the search is to be performed.

Returns:

The distinguished name of the base entry.

getScope

SearchScope getScope()

Returns the scope of the search.

Returns:

The search scope.

getSizeLimit

int getSizeLimit()

Returns the size limit that should be used in order to restrict the maximum number of entries returned by the search.

A value of zero (the default) in this field indicates that no client-requested size limit restrictions are in effect. Servers may also enforce a maximum number of entries to return.

Returns:

The size limit that should be used in order to restrict the maximum number of entries returned by the search.

isSingleEntrySearch

boolean isSingleEntrySearch()

Indicates whether search result is expected to be limited to a single entry.

It is the case if size limit is equal to 1 or if scope is equal to SearchScope.BASE_OBJECT.

If search results contain more than one entry, the search operation will throw a MultipleEntriesFoundException.

Returns:

true if the search is limited to a single entry result, or false (the default) otherwise.

getTimeLimit

int getTimeLimit()

Returns the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.

A value of zero (the default) in this field indicates that no client-requested time limit restrictions are in effect for the search. Servers may also enforce a maximum time limit for the search.

Returns:

The time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.

isTypesOnly

boolean isTypesOnly()

Indicates whether search results are to contain both attribute descriptions and values, or just attribute descriptions.

Returns:

true if only attribute descriptions (and not values) are to be returned, or false (the default) if both attribute descriptions and values are to be returned.

setDereferenceAliasesPolicy

SearchRequest setDereferenceAliasesPolicy(DereferenceAliasesPolicy policy)

Sets the alias dereferencing policy to be used during the search.

Parameters:

policy - The alias dereferencing policy to be used during the search.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the alias dereferencing policy to be set.

NullPointerException - If policy was null.

setFilter

SearchRequest setFilter(Filter filter)

Sets the filter that defines the conditions that must be fulfilled in order for an entry to be returned.

Parameters:

filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the filter to be set.

NullPointerException - If filter was null.

setFilter

SearchRequest setFilter(String filter)

Sets the filter that defines the conditions that must be fulfilled in order for an entry to be returned.

Parameters:

filter - The filter that defines the conditions that must be fulfilled in order for an entry to be returned.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the filter to be set.

LocalizedIllegalArgumentException - If filter is not a valid LDAP string representation of a filter.

NullPointerException - If filter was null.

setName

SearchRequest setName(Dn dn)

Sets the distinguished name of the base entry relative to which the search is to be performed.

Parameters:

dn - The distinguished name of the base entry relative to which the search is to be performed.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the distinguished name to be set.

NullPointerException - If dn was null.

setName

SearchRequest setName(String dn)

Sets the distinguished name of the base entry relative to which the search is to be performed.

Parameters:

dn - The distinguished name of the base entry relative to which the search is to be performed.

Returns:

This search request.

Throws:

LocalizedIllegalArgumentException - If dn could not be decoded using the default schema.

UnsupportedOperationException - If this search request does not permit the distinguished name to be set.

NullPointerException - If dn was null.

setScope

SearchRequest setScope(SearchScope scope)

Sets the scope of the search.

Parameters:

scope - The scope of the search.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the scope to be set.

NullPointerException - If scope was null.

setSizeLimit

SearchRequest setSizeLimit(int limit)

Sets the size limit that should be used in order to restrict the maximum number of entries returned by the search.

A value of 0 (the default) in this field indicates that no client-requested size limit restrictions are in effect. Servers may also enforce a maximum number of entries to return.

Parameters:

limit - The maximum number of entries that will be returned by the search. 0 means an unlimited number of entries will be returned.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the size limit to be set.

LocalizedIllegalArgumentException - If limit was negative.

setTimeLimit

SearchRequest setTimeLimit(int limit)

Sets the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.

A value of zero (the default) in this field indicates that no client-requested time limit restrictions are in effect for the search. Servers may also enforce a maximum time limit for the search.

Parameters:

limit - The time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the time limit to be set.

LocalizedIllegalArgumentException - If limit was negative.

setTypesOnly

SearchRequest setTypesOnly(boolean typesOnly)

Specifies whether search results are to contain both attribute descriptions and values, or just attribute descriptions.

Parameters:

typesOnly - true if only attribute descriptions (and not values) are to be returned, or false (the default) if both attribute descriptions and values are to be returned.

Returns:

This search request.

Throws:

UnsupportedOperationException - If this search request does not permit the types-only parameter to be set.