All Superinterfaces:: 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");

Method Summary

Modifier and Type

Method

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

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 request having an OID corresponding to the provided control decoder.

List<Control>

getControls()

Returns a List containing the controls included with this request.

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(String filter)

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

SearchRequest

setFilter(Filter filter)

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

SearchRequest

setName(String dn)

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

SearchRequest

setName(DN 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.requests.Request
containsControl

Method Details
- 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: Request
  
  Adds the provided control to this request.
  
  Specified by:
  
  addControl in interface Request
  
  Parameters:
  
  control - The control to be added to this request.
  
  Returns:
  
  This request.
- 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: Request
  
  Decodes and returns the first control in this request having an OID corresponding to the provided control decoder.
  
  Specified by:
  
  getControl in interface Request
  
  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 request.
  
  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: Request
  
  Returns a List containing the controls included with this request. The returned List may be modified if permitted by this request.
  
  Specified by:
  
  getControls in interface Request
  
  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.
  
  org.forgerock.i18n.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:
  
  org.forgerock.i18n.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 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.
  
  Parameters:
  
  limit - The size limit that should be used in order to restrict the maximum number of entries returned by the search.
  
  Returns:
  
  This search request.
  
  Throws:
  
  UnsupportedOperationException - If this search request does not permit the size limit to be set.
  
  org.forgerock.i18n.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.
  
  org.forgerock.i18n.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.

Interface SearchRequest

Method Summary

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

Method Details

addAttribute

addControl

getAttributes

getControl

getControls

getDereferenceAliasesPolicy

getFilter

getName

getScope

getSizeLimit

isSingleEntrySearch

getTimeLimit

isTypesOnly

setDereferenceAliasesPolicy

setFilter

setFilter

setName

setName

setScope

setSizeLimit

setTimeLimit

setTypesOnly