|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.unboundid.ldap.sdk.Control
com.unboundid.ldap.sdk.unboundidds.controls.MatchingEntryCountRequestControl
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class MatchingEntryCountRequestControl
NOTE: This class is part of the Commercial Edition of the UnboundID LDAP SDK for Java. It is not available for use in applications that include only the Standard Edition of the LDAP SDK, and is not supported for use in conjunction with non-UnboundID products.This class provides a request control which may be included in a search request to indicate that the server should provide the number of entries that match the search criteria. The count will be included in the search result done message, and all search result entries will be suppressed.
true
or false
. It must include a value with the following
encoding:
MatchingEntryCountRequest ::= SEQUENCE { maxCandidatesToExamine [0] INTEGER (0 .. MAX) DEFAULT 0, alwaysExamineCandidates [1] BOOLEAN DEFAULT FALSE, processSearchIfUnindexed [2] BOOLEAN DEFAULT FALSE, includeDebugInfo [3] BOOLEAN DEFAULT FALSE, ... }
MatchingEntryCountResponseControl
,
Serialized FormField Summary | |
---|---|
static java.lang.String |
MATCHING_ENTRY_COUNT_REQUEST_OID
The OID (1.3.6.1.4.1.30221.2.5.36) for the matching entry count request control. |
Constructor Summary | |
---|---|
MatchingEntryCountRequestControl()
Creates a new matching entry count request control with the default settings. |
|
MatchingEntryCountRequestControl(boolean isCritical,
int maxCandidatesToExamine,
boolean alwaysExamineCandidates,
boolean processSearchIfUnindexed,
boolean includeDebugInfo)
Creates a new matching entry count request control with the provided information. |
|
MatchingEntryCountRequestControl(Control control)
Creates a new matching entry count request control that is decoded from the provided generic control. |
Method Summary | |
---|---|
boolean |
alwaysExamineCandidates()
Indicates whether the server should always examine candidate entries in fully-indexed searches to determine whether they would actually be returned to the client in a normal search with the same criteria. |
java.lang.String |
getControlName()
Retrieves the user-friendly name for this control, if available. |
int |
getMaxCandidatesToExamine()
Retrieves the maximum number of candidate entries that should be examined in order to determine accurate count of the number of matching entries. |
boolean |
includeDebugInfo()
Indicates whether the server should include debug information in the response control that provides additional information about how the server arrived at the result. |
boolean |
processSearchIfUnindexed()
Indicates whether the server should internally retrieve and examine all entries within the search scope in order to obtain an exact matching entry count for an unindexed search. |
void |
toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP control to the provided buffer. |
Methods inherited from class com.unboundid.ldap.sdk.Control |
---|
decode, decode, decodeControls, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, toString, writeTo |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String MATCHING_ENTRY_COUNT_REQUEST_OID
Constructor Detail |
---|
public MatchingEntryCountRequestControl()
public MatchingEntryCountRequestControl(boolean isCritical, int maxCandidatesToExamine, boolean alwaysExamineCandidates, boolean processSearchIfUnindexed, boolean includeDebugInfo)
isCritical
- Indicates whether this control should be
critical.maxCandidatesToExamine
- The maximum number of candidate entries
that the server should retrieve and
examine to determine whether they
actually match the search criteria. If
the search is partially indexed and the
total number of candidate entries is less
than or equal to this value, then these
candidate entries will be examined to
determine which of them match the search
criteria so that an accurate count can
be determined. If the search is fully
indexed such that the all candidate
entries are known to match the search
criteria, then the server may still
examine each of these entries if the
number of candidates is less than
maxCandidatesToExamine
and
alwaysExamineCandidates
is true
in order to allow the entry count that
is returned to be restricted to only
those entries that would actually be
returned to the client. This will be
ignored for searches that are completely
unindexed.
Integer.MAX_VALUE
may be specified.alwaysExamineCandidates
- Indicates whether the server should
always examine candidate entries to
determine whether they would actually
be returned to the client in a normal
search. This will only be used for
fully-indexed searches in which the
set of matching entries is known. If the
value is true
and the number of
candidates is smaller than
maxCandidatesToExamine
, then each
matching entry will be internally
retrieved and examined to determine
whether it would be returned to the
client based on the details of the search
request (e.g., whether the requester has
permission to access the entry, whether
it's an LDAP subentry, replication
conflict entry, soft-deleted entry, or
other type of entry that is normally
hidden) so that an exact count can be
returned. If this is false
or
the number of candidates exceeds
maxCandidatesToExamine
, then the
server will only be able to return an
unexamined count which may include
entries that match the search criteria
but that would not normally be returned
to the requester.processSearchIfUnindexed
- Indicates whether the server should
attempt to determine the number of
matching entries if the search criteria
is completely unindexed. If this is
true
and the requester has the
unindexed-search privilege, then the
server will iterate through all entries
in the scope (which may take a very long
time to complete) in order to to
determine which of them match the search
criteria so that it can return an
accurate count. If this is
false
or the requester does not
have the unindexed-search privilege, then
the server will not spend any time
attempting to determine the number of
matching entries and will instead return
a matching entry count response control
indicating that the entry count is
unknown.includeDebugInfo
- Indicates whether the server should
include debug information in the response
that may help better understand how it
arrived at the result. If any debug
information is returned, it will be in
the form of human-readable text that is
not intended to be machine-parsable.public MatchingEntryCountRequestControl(Control control) throws LDAPException
control
- The control to decode as a matching entry count request
control.
LDAPException
- If the provided control cannot be decoded as a
matching entry count request control.Method Detail |
---|
public int getMaxCandidatesToExamine()
alwaysExamineCandidates
is true. If the number of candidate
entries identified is less than the maximum number of candidates to
examine, then the server will return an EXAMINED_COUNT
result that
indicates the number of entries matching the criteria that would actually
be returned in a normal search with the same criteria. If the number of
candidate entries exceeds the maximum number of candidates to examine, then
the server will return an UNEXAMINED_COUNT
result that indicates
the number of entries matching the search criteria but that may include
entries that would not actually be returned to the client.
EXAMINED_COUNT
result with that count. If the upper bound on the
number of candidates is greater than the maximum number of candidates to
examine, then the server will return an UPPER_BOUND
result to
indicate that the exact count is not known but an upper bound is available.
public boolean alwaysExamineCandidates()
true
if the server should attempt to internally retrieve
and examine matching entries to determine whether they would
normally be returned to the client (i.e.., that the client has
permission to access the entry and that it is not a
normally-hidden entry like an LDAP subentry, a replication
conflict entry, or a soft-deleted entry), or false
if the
server should return an unverified count.public boolean processSearchIfUnindexed()
true
if the server should internally retrieve and examine
all entries within the search scope in order to obtain an exact
matching entry count for an unindexed search, or false
if
not.public boolean includeDebugInfo()
true
if the server should include debug information in
the response control, or false
if not.public java.lang.String getControlName()
getControlName
in class Control
public void toString(java.lang.StringBuilder buffer)
toString
in class Control
buffer
- The buffer to which to append the string representation of
this buffer.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |