Package 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");

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

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

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