@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class MatchingEntryCountResponseControl extends Control implements DecodeableControl
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.
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,
... }
MatchingEntryCountRequestControl,
Serialized Form| Modifier and Type | Field and 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 and 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.
|
| Modifier and Type | Method and 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.
|
decode, decode, decodeControls, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toString, writeTo@NotNull public static final java.lang.String MATCHING_ENTRY_COUNT_RESPONSE_OID
public MatchingEntryCountResponseControl(@NotNull java.lang.String oid, boolean isCritical, @Nullable ASN1OctetString value) throws LDAPException
oid - The OID for the control.isCritical - Indicates whether this control should be marked
critical.value - The encoded value for the control.LDAPException - If a problem occurs while attempting to decode the
generic control as a matching entry count response
control.@NotNull public static MatchingEntryCountResponseControl createExactCountResponse(int count, boolean examined, @Nullable java.util.Collection<java.lang.String> debugInfo)
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.@NotNull public static MatchingEntryCountResponseControl createExactCountResponse(int count, boolean examined, boolean searchIndexed, @Nullable java.util.Collection<java.lang.String> debugInfo)
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.@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)
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.@NotNull public static MatchingEntryCountResponseControl createUpperBoundResponse(int upperBound, @Nullable java.util.Collection<java.lang.String> debugInfo)
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.@NotNull public static MatchingEntryCountResponseControl createUpperBoundResponse(int upperBound, boolean searchIndexed, @Nullable java.util.Collection<java.lang.String> debugInfo)
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.@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)
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.@NotNull public static MatchingEntryCountResponseControl createUnknownCountResponse(@Nullable java.util.Collection<java.lang.String> debugInfo)
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.@NotNull public MatchingEntryCountType getCountType()
public int getCountValue()
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.public boolean searchIndexed()
true if the server considers the search criteria to be
indexed, or false if not.@Nullable public java.lang.Boolean getShortCircuited()
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).@Nullable public java.lang.Boolean getFullyIndexed()
Boolean.FALSE even if the search is actually completely
indexed.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).@Nullable public java.lang.Boolean getCandidatesAreInScope()
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.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).@Nullable public Filter getRemainingFilter()
null if there was no remaining filter or if this
information is not available (e.g., because extended response data
was not requested).@NotNull public java.util.List<java.lang.String> getDebugInfo()
@NotNull public MatchingEntryCountResponseControl decodeControl(@NotNull java.lang.String oid, boolean isCritical, @Nullable ASN1OctetString value) throws LDAPException
decodeControl in interface DecodeableControloid - The OID for the control.isCritical - Indicates whether the control should be marked
critical.value - The encoded value for the control. This may be
null if no value was provided.LDAPException - If the provided information cannot be decoded as a
valid instance of this decodeable control.@Nullable public static MatchingEntryCountResponseControl get(@NotNull SearchResult result) throws LDAPException
result - The search result from which to retrieve the matching entry
count response control.null if the result did not contain a
matching entry count response control.LDAPException - If a problem is encountered while attempting to
decode the matching entry count response control
contained in the provided result.@NotNull public java.lang.String getControlName()
getControlName in class Control@NotNull public JSONObject toJSONControl()
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.
toJSONControl in class Control@NotNull public static MatchingEntryCountResponseControl decodeJSONControl(@NotNull JSONObject controlObject, boolean strict) throws LDAPException
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.LDAPException - If the provided JSON object cannot be parsed as a
valid matching entry count response control.