Package org.forgerock.opendj.ldap.messages

Record Class SearchRequest

java.lang.Object
java.lang.Record
org.forgerock.opendj.ldap.messages.SearchRequest
Record Components:
name - the distinguished name of the base entry relative to which the search is to be performed.
scope - the scope of the search.
filter - the filter that defines the conditions that must be fulfilled in order for an entry to be returned.
dereferenceAliasesPolicy - an indication whether alias entries are to be.
timeLimit - the time limit that should be used in order to restrict the maximum time (in seconds) allowed for the search.

A value of 0 (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.

sizeLimit - the maximum number of entries that will be returned by the search.

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

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.
attributes - the List containing the attributes requested by the client to be included with each entry that matches the search criteria. Attributes that are subtypes of listed attributes are implicitly included. The returned List may be modified if permitted by this search request. Attributes are a List<String> rather a Set<AttributeDescription> because:
  • The values are not even attribute descriptions. * and + are allowed as well as @ObjectClass.
  • While a Set<String> would avoid duplicates with the same alphabetical spelling, you could still end up with duplicates like "cn", or "CN", "commonName", "CoMmOnNaMe", numeric OIDs, etc.
  • A list aligns with the protocol representation. If we used a set then we would manipulate what was being sent over the network.
controls - the List containing the controls.
All Implemented Interfaces:
ProtocolOp, Request
public record SearchRequest(Dn name, SearchScope scope, DereferenceAliasesPolicy dereferenceAliasesPolicy, int sizeLimit, int timeLimit, boolean typesOnly, Filter filter, List<String> attributes, List<Control> controls) extends Record 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(String, SearchScope, String, String...) to specify the arguments directly. 
 Connection connection = ...;
 ConnectionEntryReader reader = connection.search("dc=example,dc=com", SearchScope.BASE_ONLY, "(sn=Jensen)", "cn");

  • Constructor Details

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

    • 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

    • withName

      public SearchRequest withName(Dn name)
      Create a new SearchRequest from existing one with new distinguished name.
      Parameters:
      name - the distinguished name of the base entry relative to which the search is to be performed.
      Returns:
      New search request.

    • withNameAndScope

      public SearchRequest withNameAndScope(Dn name, SearchScope scope)
      Create a new SearchRequest from existing one with new distinguished name and the scope of the search.
      Parameters:
      name - the distinguished name of the base entry relative to which the search is to be performed.
      scope - the scope of the search.
      Returns:
      New search request.

    • withFilter

      public SearchRequest withFilter(Filter filter)
      Create a new SearchRequest from existing one with new 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:
      New search request.

    • withSizeLimit

      public SearchRequest withSizeLimit(int sizeLimit)
      Create a new SearchRequest from existing one with new maximum number of entries to be returned by the search.
      Parameters:
      sizeLimit - the maximum number of entries that will be returned by the search. 0 means an unlimited number of entries will be returned.
      Returns:
      New search request.

    • withTypesOnly

      public SearchRequest withTypesOnly(boolean typesOnly)
      Create a new SearchRequest from existing one with new typesOnly flag.
      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:
      New search request.

    • toString

      public String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • name

      public Dn name()
      Returns the value of the name record component.
      Returns:
      the value of the name record component

    • scope

      public SearchScope scope()
      Returns the value of the scope record component.
      Returns:
      the value of the scope record component

    • dereferenceAliasesPolicy

      public DereferenceAliasesPolicy dereferenceAliasesPolicy()
      Returns the value of the dereferenceAliasesPolicy record component.
      Returns:
      the value of the dereferenceAliasesPolicy record component

    • sizeLimit

      public int sizeLimit()
      Returns the value of the sizeLimit record component.
      Returns:
      the value of the sizeLimit record component

    • timeLimit

      public int timeLimit()
      Returns the value of the timeLimit record component.
      Returns:
      the value of the timeLimit record component

    • typesOnly

      public boolean typesOnly()
      Returns the value of the typesOnly record component.
      Returns:
      the value of the typesOnly record component

    • filter

      public Filter filter()
      Returns the value of the filter record component.
      Returns:
      the value of the filter record component

    • attributes

      public List<String> attributes()
      Returns the value of the attributes record component.
      Returns:
      the value of the attributes record component

    • controls

      public List<Control> controls()
      Returns the value of the controls record component.
      Specified by:
      controls in interface ProtocolOp
      Returns:
      the value of the controls record component