Class MatchingEntryCountResponseControl

  • All Implemented Interfaces:
    DecodeableControl, java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class MatchingEntryCountResponseControl
    extends Control
    implements DecodeableControl
    This class provides a response control that may be used to provide information about the number of entries that match a given set of search criteria. The control will be included in the search result done message for any successful search operation in which the request contained a matching entry count request control.
    NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

    The matching entry count response control has an OID of "1.3.6.1.4.1.30221.2.5.37", a criticality of false, and a value with the following encoding:
       MatchingEntryCountResponse ::= SEQUENCE {
            entryCount               CHOICE {
                 examinedCount            [0] INTEGER,
                 unexaminedCount          [1] INTEGER,
                 upperBound               [2] INTEGER,
                 unknown                  [3] NULL,
                 ... }
            debugInfo                [0] SEQUENCE OF OCTET STRING OPTIONAL,
            searchIndexed            [1] BOOLEAN DEFAULT TRUE,
            shortCircuited           [2] BOOLEAN OPTIONAL,
            fullyIndexed             [3] BOOLEAN OPTIONAL,
            candidatesAreInScope     [4] BOOLEAN OPTIONAL,
            remainingFilter          [5] Filter OPTIONAL,
            ... }
     
    See Also:
    MatchingEntryCountRequestControl, Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String MATCHING_ENTRY_COUNT_RESPONSE_OID
      The OID (1.3.6.1.4.1.30221.2.5.37) for the matching entry count response control.
    • Constructor Summary

      Constructors 
      Constructor Description
      MatchingEntryCountResponseControl​(java.lang.String oid, boolean isCritical, ASN1OctetString value)
      Creates a new matching entry count response control decoded from the given generic control contents.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static MatchingEntryCountResponseControl createExactCountResponse​(int count, boolean examined, boolean searchIndexed, java.lang.Boolean shortCircuited, java.lang.Boolean fullyIndexed, java.lang.Boolean candidatesAreInScope, Filter remainingFilter, java.util.Collection<java.lang.String> debugInfo)
      Creates a new matching entry count response control for the case in which the exact number of matching entries is known.
      static MatchingEntryCountResponseControl createExactCountResponse​(int count, boolean examined, boolean searchIndexed, java.util.Collection<java.lang.String> debugInfo)
      Creates a new matching entry count response control for the case in which the exact number of matching entries is known.
      static MatchingEntryCountResponseControl createExactCountResponse​(int count, boolean examined, java.util.Collection<java.lang.String> debugInfo)
      Creates a new matching entry count response control for the case in which the exact number of matching entries is known.
      static MatchingEntryCountResponseControl createUnknownCountResponse​(java.util.Collection<java.lang.String> debugInfo)
      Creates a new matching entry count response control for the case in which the server was unable to make any meaningful determination about the number of entries matching the search criteria.
      static MatchingEntryCountResponseControl createUpperBoundResponse​(int upperBound, boolean searchIndexed, java.lang.Boolean shortCircuited, java.lang.Boolean fullyIndexed, java.lang.Boolean candidatesAreInScope, Filter remainingFilter, java.util.Collection<java.lang.String> debugInfo)
      Creates a new matching entry count response control for the case in which the exact number of matching entries is not known, but the server was able to determine an upper bound on the number of matching entries.
      static MatchingEntryCountResponseControl createUpperBoundResponse​(int upperBound, boolean searchIndexed, java.util.Collection<java.lang.String> debugInfo)
      Creates a new matching entry count response control for the case in which the exact number of matching entries is not known, but the server was able to determine an upper bound on the number of matching entries.
      static MatchingEntryCountResponseControl createUpperBoundResponse​(int upperBound, java.util.Collection<java.lang.String> debugInfo)
      Creates a new matching entry count response control for the case in which the exact number of matching entries is not known, but the server was able to determine an upper bound on the number of matching entries.
      MatchingEntryCountResponseControl decodeControl​(java.lang.String oid, boolean isCritical, ASN1OctetString value)
      Creates a new instance of this decodeable control from the provided information.
      static MatchingEntryCountResponseControl decodeJSONControl​(JSONObject controlObject, boolean strict)
      Attempts to decode the provided object as a JSON representation of a matching entry count response control.
      static MatchingEntryCountResponseControl get​(SearchResult result)
      Extracts a matching entry count response control from the provided search result.
      java.lang.Boolean getCandidatesAreInScope()
      Indicates whether the server can determine that all the identified candidates are within the scope of the search.
      java.lang.String getControlName()
      Retrieves the user-friendly name for this control, if available.
      MatchingEntryCountType getCountType()
      Retrieves the matching entry count type for the response control.
      int getCountValue()
      Retrieves the matching entry count value for the response control.
      java.util.List<java.lang.String> getDebugInfo()
      Retrieves a list of messages with debug information about the processing performed by the server in the course of obtaining the matching entry count.
      java.lang.Boolean getFullyIndexed()
      Indicates whether the server considers the search criteria to be fully indexed.
      Filter getRemainingFilter()
      Retrieves the portion of the filter that was either identified as not indexed or that was not evaluated during candidate processing (e.g., because the server short-circuited processing before examining all filter components).
      java.lang.Boolean getShortCircuited()
      Indicates whether the server short-circuited during candidate set processing before evaluating all elements of the search criteria (the filter and scope).
      boolean searchIndexed()
      Indicates whether the server considers the search criteria to be indexed and therefore it could be processed more efficiently than examining all entries with a full database scan.
      JSONObject toJSONControl()
      Retrieves a representation of this matching entry count response control as a JSON object.
      void toString​(java.lang.StringBuilder buffer)
      Appends a string representation of this LDAP control to the provided buffer.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • MatchingEntryCountResponseControl

        public MatchingEntryCountResponseControl​(@NotNull
                                                 java.lang.String oid,
                                                 boolean isCritical,
                                                 @Nullable
                                                 ASN1OctetString value)
                                          throws LDAPException
        Creates a new matching entry count response control decoded from the given generic control contents.
        Parameters:
        oid - The OID for the control.
        isCritical - Indicates whether this control should be marked critical.
        value - The encoded value for the control.
        Throws:
        LDAPException - If a problem occurs while attempting to decode the generic control as a matching entry count response control.
    • Method Detail

      • createExactCountResponse

        @NotNull
        public static MatchingEntryCountResponseControl createExactCountResponse​(int count,
                                                                                 boolean examined,
                                                                                 @Nullable
                                                                                 java.util.Collection<java.lang.String> debugInfo)
        Creates a new matching entry count response control for the case in which the exact number of matching entries is known.
        Parameters:
        count - The exact number of entries matching the associated search criteria. It must be greater than or equal to zero.
        examined - Indicates whether the server examined the entries to exclude those entries that would not be returned to the client in a normal search with the same criteria.
        debugInfo - An optional list of messages providing debug information about the processing performed by the server. It may be null or empty if no debug messages should be included.
        Returns:
        The matching entry count response control that was created.
      • createExactCountResponse

        @NotNull
        public static MatchingEntryCountResponseControl createExactCountResponse​(int count,
                                                                                 boolean examined,
                                                                                 boolean searchIndexed,
                                                                                 @Nullable
                                                                                 java.util.Collection<java.lang.String> debugInfo)
        Creates a new matching entry count response control for the case in which the exact number of matching entries is known.
        Parameters:
        count - The exact number of entries matching the associated search criteria. It must be greater than or equal to zero.
        examined - Indicates whether the server examined the entries to exclude those entries that would not be returned to the client in a normal search with the same criteria.
        searchIndexed - Indicates whether the search criteria is considered at least partially indexed and could be processed more efficiently than examining all entries with a full database scan.
        debugInfo - An optional list of messages providing debug information about the processing performed by the server. It may be null or empty if no debug messages should be included.
        Returns:
        The matching entry count response control that was created.
      • createExactCountResponse

        @NotNull
        public static MatchingEntryCountResponseControl createExactCountResponse​(int count,
                                                                                 boolean examined,
                                                                                 boolean searchIndexed,
                                                                                 @Nullable
                                                                                 java.lang.Boolean shortCircuited,
                                                                                 @Nullable
                                                                                 java.lang.Boolean fullyIndexed,
                                                                                 @Nullable
                                                                                 java.lang.Boolean candidatesAreInScope,
                                                                                 @Nullable
                                                                                 Filter remainingFilter,
                                                                                 @Nullable
                                                                                 java.util.Collection<java.lang.String> debugInfo)
        Creates a new matching entry count response control for the case in which the exact number of matching entries is known.
        Parameters:
        count - The exact number of entries matching the associated search criteria. It must be greater than or equal to zero.
        examined - Indicates whether the server examined the entries to exclude those entries that would not be returned to the client in a normal search with the same criteria.
        searchIndexed - Indicates whether the search criteria is considered at least partially indexed and could be processed more efficiently than examining all entries with a full database scan.
        shortCircuited - Indicates whether the server short-circuited during candidate set processing before evaluating all elements of the search criteria (the filter and scope). This may be null if it is not available (e.g., because extended response data was not requested).
        fullyIndexed - Indicates whether the search is considered fully indexed. Note that this may be false even if the filter is actually fully indexed if server index processing short-circuited before evaluating all components of the filter. To avoid this, issue the request control with both fast and slow short-circuit thresholds set to zero. This may be null if this is not available (e.g., because extended response data was not requested).
        candidatesAreInScope - Indicates whether all the identified candidate entries are within the scope of the search. It may be null if this is not available (e.g., because extended response data was not requested).
        remainingFilter - The portion of the filter that was either identified as unindexed or that was not evaluated because processing short-circuited in the course of building the candidate set. It may be null if there is no remaining filter or if this information is not available (e.g., because extended response data was not requested).
        debugInfo - An optional list of messages providing debug information about the processing performed by the server. It may be null or empty if no debug messages should be included.
        Returns:
        The matching entry count response control that was created.
      • createUpperBoundResponse

        @NotNull
        public static MatchingEntryCountResponseControl createUpperBoundResponse​(int upperBound,
                                                                                 @Nullable
                                                                                 java.util.Collection<java.lang.String> debugInfo)
        Creates a new matching entry count response control for the case in which the exact number of matching entries is not known, but the server was able to determine an upper bound on the number of matching entries. This upper bound count may include entries that do not match the search filter, that are outside the scope of the search, and/or that match the search criteria but would not have been returned to the client in a normal search with the same criteria.
        Parameters:
        upperBound - The upper bound on the number of entries that match the associated search criteria. It must be greater than zero.
        debugInfo - An optional list of messages providing debug information about the processing performed by the server. It may be null or empty if no debug messages should be included.
        Returns:
        The matching entry count response control that was created.
      • createUpperBoundResponse

        @NotNull
        public static MatchingEntryCountResponseControl createUpperBoundResponse​(int upperBound,
                                                                                 boolean searchIndexed,
                                                                                 @Nullable
                                                                                 java.util.Collection<java.lang.String> debugInfo)
        Creates a new matching entry count response control for the case in which the exact number of matching entries is not known, but the server was able to determine an upper bound on the number of matching entries. This upper bound count may include entries that do not match the search filter, that are outside the scope of the search, and/or that match the search criteria but would not have been returned to the client in a normal search with the same criteria.
        Parameters:
        upperBound - The upper bound on the number of entries that match the associated search criteria. It must be greater than zero.
        searchIndexed - Indicates whether the search criteria is considered at least partially indexed and could be processed more efficiently than examining all entries with a full database scan.
        debugInfo - An optional list of messages providing debug information about the processing performed by the server. It may be null or empty if no debug messages should be included.
        Returns:
        The matching entry count response control that was created.
      • createUpperBoundResponse

        @NotNull
        public static MatchingEntryCountResponseControl createUpperBoundResponse​(int upperBound,
                                                                                 boolean searchIndexed,
                                                                                 @Nullable
                                                                                 java.lang.Boolean shortCircuited,
                                                                                 @Nullable
                                                                                 java.lang.Boolean fullyIndexed,
                                                                                 @Nullable
                                                                                 java.lang.Boolean candidatesAreInScope,
                                                                                 @Nullable
                                                                                 Filter remainingFilter,
                                                                                 @Nullable
                                                                                 java.util.Collection<java.lang.String> debugInfo)
        Creates a new matching entry count response control for the case in which the exact number of matching entries is not known, but the server was able to determine an upper bound on the number of matching entries. This upper bound count may include entries that do not match the search filter, that are outside the scope of the search, and/or that match the search criteria but would not have been returned to the client in a normal search with the same criteria.
        Parameters:
        upperBound - The upper bound on the number of entries that match the associated search criteria. It must be greater than zero.
        searchIndexed - Indicates whether the search criteria is considered at least partially indexed and could be processed more efficiently than examining all entries with a full database scan.
        shortCircuited - Indicates whether the server short-circuited during candidate set processing before evaluating all elements of the search criteria (the filter and scope). This may be null if it is not available (e.g., because extended response data was not requested).
        fullyIndexed - Indicates whether the search is considered fully indexed. Note that this may be false even if the filter is actually fully indexed if server index processing short-circuited before evaluating all components of the filter. To avoid this, issue the request control with both fast and slow short-circuit thresholds set to zero. This may be null if this is not available (e.g., because extended response data was not requested).
        candidatesAreInScope - Indicates whether all the identified candidate entries are within the scope of the search. It may be null if this is not available (e.g., because extended response data was not requested).
        remainingFilter - The portion of the filter that was either identified as unindexed or that was not evaluated because processing short-circuited in the course of building the candidate set. It may be null if there is no remaining filter or if this information is not available (e.g., because extended response data was not requested).
        debugInfo - An optional list of messages providing debug information about the processing performed by the server. It may be null or empty if no debug messages should be included.
        Returns:
        The matching entry count response control that was created.
      • createUnknownCountResponse

        @NotNull
        public static MatchingEntryCountResponseControl createUnknownCountResponse​(@Nullable
                                                                                   java.util.Collection<java.lang.String> debugInfo)
        Creates a new matching entry count response control for the case in which the server was unable to make any meaningful determination about the number of entries matching the search criteria.
        Parameters:
        debugInfo - An optional list of messages providing debug information about the processing performed by the server. It may be null or empty if no debug messages should be included.
        Returns:
        The matching entry count response control that was created.
      • getCountValue

        public int getCountValue()
        Retrieves the matching entry count value for the response control. For a count type of EXAMINED_COUNT or UNEXAMINED_COUNT, this is the exact number of matching entries. For a count type of UPPER_BOUND, this is the maximum number of entries that may match the search criteria, but it may also include entries that do not match the criteria. For a count type of UNKNOWN, this will always be -1.
        Returns:
        The exact count or upper bound of the number of entries in the server that may match the search criteria, or -1 if the server could not determine the number of matching entries.
      • searchIndexed

        public boolean searchIndexed()
        Indicates whether the server considers the search criteria to be indexed and therefore it could be processed more efficiently than examining all entries with a full database scan.
        Returns:
        true if the server considers the search criteria to be indexed, or false if not.
      • getShortCircuited

        @Nullable
        public java.lang.Boolean getShortCircuited()
        Indicates whether the server short-circuited during candidate set processing before evaluating all elements of the search criteria (the filter and scope).
        Returns:
        Boolean.TRUE if the server did short-circuit during candidate set processing before evaluating all elements of the search criteria, Boolean.FALSE if the server evaluated all elements of the search criteria, or null if this information is not available (e.g., because extended response data was not requested).
      • getFullyIndexed

        @Nullable
        public java.lang.Boolean getFullyIndexed()
        Indicates whether the server considers the search criteria to be fully indexed. Note that if the server short-circuited during candidate set processing before evaluating all search criteria (the filter and scope), this may be Boolean.FALSE even if the search is actually completely indexed.
        Returns:
        Boolean.TRUE if the server considers the search criteria to be fully indexed, Boolean.FALSE if the search criteria is not known to be fully indexed, or null if this information is not available (e.g., because extended response data was not requested).
      • getCandidatesAreInScope

        @Nullable
        public java.lang.Boolean getCandidatesAreInScope()
        Indicates whether the server can determine that all the identified candidates are within the scope of the search. Note that even if the server returns Boolean.FALSE, it does not necessarily mean that not all the candidates are within the scope of the search, but just that the server is not certain that is the case.
        Returns:
        Boolean.TRUE if the server can determine that all the identified candidates are within the scope of the search, Boolean.FALSE if the server cannot determine that all the identified candidates are within the scope of the search, or null if this information is not available (e.g., because extended response data was not requested).
      • getRemainingFilter

        @Nullable
        public Filter getRemainingFilter()
        Retrieves the portion of the filter that was either identified as not indexed or that was not evaluated during candidate processing (e.g., because the server short-circuited processing before examining all filter components).
        Returns:
        The portion of the filter that was either identified as not indexed or that was not evaluated during candidate processing, or null if there was no remaining filter or if this information is not available (e.g., because extended response data was not requested).
      • getDebugInfo

        @NotNull
        public java.util.List<java.lang.String> getDebugInfo()
        Retrieves a list of messages with debug information about the processing performed by the server in the course of obtaining the matching entry count. These messages are intended to be human-readable rather than machine-parsable.
        Returns:
        A list of messages with debug information about the processing performed by the server in the course of obtaining the matching entry count, or an empty list if no debug messages were provided.
      • get

        @Nullable
        public static MatchingEntryCountResponseControl get​(@NotNull
                                                            SearchResult result)
                                                     throws LDAPException
        Extracts a matching entry count response control from the provided search result.
        Parameters:
        result - The search result from which to retrieve the matching entry count response control.
        Returns:
        The matching entry count response control contained in the provided result, or null if the result did not contain a matching entry count response control.
        Throws:
        LDAPException - If a problem is encountered while attempting to decode the matching entry count response control contained in the provided result.
      • getControlName

        @NotNull
        public java.lang.String getControlName()
        Retrieves the user-friendly name for this control, if available. If no user-friendly name has been defined, then the OID will be returned.
        Overrides:
        getControlName in class Control
        Returns:
        The user-friendly name for this control, or the OID if no user-friendly name is available.
      • toJSONControl

        @NotNull
        public JSONObject toJSONControl()
        Retrieves a representation of this matching entry count response control as a JSON object. The JSON object uses the following fields:
        • oid -- A mandatory string field whose value is the object identifier for this control. For the matching entry count response control, the OID is "1.3.6.1.4.1.30221.2.5.37".
        • control-name -- An optional string field whose value is a human-readable name for this control. This field is only intended for descriptive purposes, and when decoding a control, the oid field should be used to identify the type of control.
        • criticality -- A mandatory Boolean field used to indicate whether this control is considered critical.
        • value-base64 -- An optional string field whose value is a base64-encoded representation of the raw value for this matching entry count response control. Exactly one of the value-base64 and value-json fields must be present.
        • value-json -- An optional JSON object field whose value is a user-friendly representation of the value for this matching entry count response control. Exactly one of the value-base64 and value-json fields must be present, and if the value-json field is used, then it will use the following fields:
          • count-type -- A string field whose value indicates how accurate the count is. The value will be one of "examined-count", "unexamined-count", "upper-bound", or "unknown".
          • count-value -- An optional integer field whose value is the matching entry count estimate returned by the server. This will be absent for a count-type value of "unknown", and will be present for other count-type values.
          • search-indexed -- A Boolean field that indicates whether the server considers the search to be at least partially indexed.
          • fully-indexed -- An optional Boolean field that indicates whether the server considers the search to be fully indexed.
          • short-circuited -- An optional Boolean field that indicates whether the server short-circuited at any point in evaluating the search criteria.
          • candidates-are-in-scope -- An optional Boolean field that indicates whether the server knows that all identified candidate entries are within the scope of the search.
          • remaining-filter -- An optional string field whose value is the portion of the filter that was not evaluated during the course of coming up with the estimate.
          • debug-info -- An optional array field whose values are strings with debug information about the processing performed by the server in the course of determining the matching entry count estimate.
        Overrides:
        toJSONControl in class Control
        Returns:
        A JSON object that contains a representation of this control.
      • decodeJSONControl

        @NotNull
        public static MatchingEntryCountResponseControl decodeJSONControl​(@NotNull
                                                                          JSONObject controlObject,
                                                                          boolean strict)
                                                                   throws LDAPException
        Attempts to decode the provided object as a JSON representation of a matching entry count response control.
        Parameters:
        controlObject - The JSON object to be decoded. It must not be null.
        strict - Indicates whether to use strict mode when decoding the provided JSON object. If this is true, then this method will throw an exception if the provided JSON object contains any unrecognized fields. If this is false, then unrecognized fields will be ignored.
        Returns:
        The matching entry count response control that was decoded from the provided JSON object.
        Throws:
        LDAPException - If the provided JSON object cannot be parsed as a valid matching entry count response control.
      • toString

        public void toString​(@NotNull
                             java.lang.StringBuilder buffer)
        Appends a string representation of this LDAP control to the provided buffer.
        Overrides:
        toString in class Control
        Parameters:
        buffer - The buffer to which to append the string representation of this buffer.