com.unboundid.ldap.sdk.unboundidds.controls
Class MatchingEntryCountResponseControl

java.lang.Object
  extended by com.unboundid.ldap.sdk.Control
      extended by com.unboundid.ldap.sdk.unboundidds.controls.MatchingEntryCountResponseControl
All Implemented Interfaces:
DecodeableControl, java.io.Serializable

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class MatchingEntryCountResponseControl
extends Control
implements DecodeableControl

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

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,
        ... }
 

See Also:
MatchingEntryCountRequestControl, Serialized Form

Field Summary
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
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
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.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 get(SearchResult result)
          Extracts a matching entry count response control from the provided search result.
 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.
 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.
 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

MATCHING_ENTRY_COUNT_RESPONSE_OID

public static final 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.

See Also:
Constant Field Values
Constructor Detail

MatchingEntryCountResponseControl

public MatchingEntryCountResponseControl(java.lang.String oid,
                                         boolean isCritical,
                                         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

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

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

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

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.

createUpperBoundResponse

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

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

createUnknownCountResponse

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

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.

getCountType

public MatchingEntryCountType getCountType()
Retrieves the matching entry count type for the response control.

Returns:
The matching entry count type for the response control.

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.

getDebugInfo

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.

decodeControl

public MatchingEntryCountResponseControl decodeControl(java.lang.String oid,
                                                       boolean isCritical,
                                                       ASN1OctetString value)
                                                throws LDAPException
Creates a new instance of this decodeable control from the provided information.

Specified by:
decodeControl in interface DecodeableControl
Parameters:
oid - 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.
Returns:
The decoded representation of this control.
Throws:
LDAPException - If the provided information cannot be decoded as a valid instance of this decodeable control.

get

public static MatchingEntryCountResponseControl get(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

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.

toString

public void toString(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.