Package org.forgerock.opendj.ldap.messages

Class SearchRequest

java.lang.Object
org.forgerock.opendj.ldap.messages.SearchRequest
All Implemented Interfaces:
ProtocolOp, Request
public final class SearchRequest extends Object implements 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 Details

    • accept

      public <R, P, E extends Exception> R accept(RequestVisitor<R,P,E> v, P p) throws E
      Description copied from interface: Request
      Applies a RequestVisitor to this Request.
      Specified by:
      accept in interface Request
      Type Parameters:
      R - The return type of the visitor's methods.
      P - The type of the additional parameters to the visitor's methods.
      E - The type of the exception thrown by the visitor method if it fails, or NeverThrowsException if the visitor cannot fail.
      Parameters:
      v - The request visitor.
      p - Optional additional visitor parameter.
      Returns:
      A result as specified by the visitor.
      Throws:
      E - If the visitor failed.

    • addAttribute

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

    • getAttributes

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

    • getDereferenceAliasesPolicy

      public DereferenceAliasesPolicy getDereferenceAliasesPolicy()
      Returns an indication as to whether alias entries are to be dereferenced during the search.
      Returns:
      The alias dereferencing policy.

    • getFilter

      public 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

      public 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

      public SearchScope getScope()
      Returns the scope of the search.
      Returns:
      The search scope.

    • getSizeLimit

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

      public 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

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

    • getType

      public Request.RequestType getType()
      Description copied from interface: Request
      Returns the type of this request to avoid expensive instanceof checks.
      Specified by:
      getType in interface Request
      Returns:
      the type of this request

    • toString

      public String toString()

    • addControl

      public final SearchRequest addControl(Control control)
      Description copied from interface: ProtocolOp
      Adds the provided control to this protocol-op.
      Specified by:
      addControl in interface ProtocolOp
      Parameters:
      control - The control to be added to this protocol-op.
      Returns:
      This protocol-op.

    • addControls

      public final 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
      Parameters:
      controls - The controls to be added to this protocol-op.
      Returns:
      This protocol-op.

    • removeControls

      public final SearchRequest removeControls(String oid)
      Description copied from interface: ProtocolOp
      Removes all the controls having the specified OID.
      Specified by:
      removeControls in interface ProtocolOp
      Parameters:
      oid - The numeric OID of the protocol-op control to remove.
      Returns:
      This protocol-op.

    • containsControl

      public final boolean containsControl(String oid)
      Description copied from interface: ProtocolOp
      Returns true if this protocol-op contains the specified control.
      Specified by:
      containsControl in interface ProtocolOp
      Parameters:
      oid - The numeric OID of the protocol-op control.
      Returns:
      true if this protocol-op contains the specified control.

    • getControl

      public final <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

      public final 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.