Control (UnboundID LDAP SDK for Java 7.0.1)

java.lang.Object
- com.unboundid.ldap.sdk.Control

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

AccessLogFieldRequestControl, AccountUsableRequestControl, AccountUsableResponseControl, ActiveDirectoryDirSyncControl, AdministrativeOperationRequestControl, AffinityRequestControl, AssertionRequestControl, AssuredReplicationRequestControl, AssuredReplicationResponseControl, AuthorizationIdentityRequestControl, AuthorizationIdentityResponseControl, BatchedTransactionSpecificationRequestControl, ChangeSequenceNumberRequestControl, ChangeSequenceNumberResponseControl, ContentSyncDoneControl, ContentSyncRequestControl, ContentSyncStateControl, DontUseCopyRequestControl, DraftBeheraLDAPPasswordPolicy10RequestControl, DraftBeheraLDAPPasswordPolicy10ResponseControl, DraftLDUPSubentriesRequestControl, DraftZeilengaLDAPNoOp12RequestControl, DraftZeilengaLDAPRelaxRules03RequestControl, EntryChangeNotificationControl, ExcludeBranchRequestControl, ExtendedSchemaInfoRequestControl, GenerateAccessTokenRequestControl, GenerateAccessTokenResponseControl, GeneratePasswordRequestControl, GeneratePasswordResponseControl, GetAuthorizationEntryRequestControl, GetAuthorizationEntryResponseControl, GetBackendSetIDRequestControl, GetBackendSetIDResponseControl, GetEffectiveRightsRequestControl, GetPasswordPolicyStateIssuesRequestControl, GetPasswordPolicyStateIssuesResponseControl, GetRecentLoginHistoryRequestControl, GetRecentLoginHistoryResponseControl, GetServerIDRequestControl, GetServerIDResponseControl, GetUserResourceLimitsRequestControl, GetUserResourceLimitsResponseControl, HardDeleteRequestControl, IgnoreNoUserModificationRequestControl, IntermediateClientRequestControl, IntermediateClientResponseControl, JoinRequestControl, JoinResultControl, JSONFormattedRequestControl, JSONFormattedResponseControl, ManageDsaITRequestControl, MatchedValuesRequestControl, MatchingEntryCountRequestControl, MatchingEntryCountResponseControl, NameWithEntryUUIDRequestControl, NoOpRequestControl, OperationPurposeRequestControl, OverrideSearchLimitsRequestControl, PasswordExpiredControl, PasswordExpiringControl, PasswordPolicyRequestControl, PasswordPolicyResponseControl, PasswordUpdateBehaviorRequestControl, PasswordValidationDetailsRequestControl, PasswordValidationDetailsResponseControl, PermissiveModifyRequestControl, PermitUnindexedSearchRequestControl, PersistentSearchRequestControl, PostReadRequestControl, PostReadResponseControl, PreReadRequestControl, PreReadResponseControl, ProxiedAuthorizationV1RequestControl, ProxiedAuthorizationV2RequestControl, PurgePasswordRequestControl, RealAttributesOnlyRequestControl, RejectUnindexedSearchRequestControl, ReplicationRepairRequestControl, ReplicationRepairRequestControl, RetainIdentityRequestControl, RetirePasswordRequestControl, ReturnConflictEntriesRequestControl, RFC3672SubentriesRequestControl, RouteToBackendSetRequestControl, RouteToServerRequestControl, ServerSideSortRequestControl, ServerSideSortResponseControl, SimplePagedResultsControl, SoftDeletedEntryAccessRequestControl, SoftDeleteRequestControl, SoftDeleteResponseControl, SubentriesRequestControl, SubtreeDeleteRequestControl, SuppressOperationalAttributeUpdateRequestControl, SuppressReferentialIntegrityUpdatesRequestControl, TransactionIDRequestControl, TransactionSettingsRequestControl, TransactionSettingsResponseControl, TransactionSpecificationRequestControl, UndeleteRequestControl, UniquenessRequestControl, UniquenessResponseControl, UnsolicitedCancelResponseControl, VirtualAttributesOnlyRequestControl, VirtualListViewRequestControl, VirtualListViewResponseControl
```
@Extensible
 @NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public class Control
extends java.lang.Object
implements java.io.Serializable
```
This class provides a data structure that represents an LDAP control. A control is an element that may be attached to an LDAP request or response to provide additional information about the processing that should be (or has been) performed. This class may be overridden to provide additional processing for specific types of controls.

A control includes the following elements:
- An object identifier (OID), which identifies the type of control.
- A criticality flag, which indicates whether the control should be considered critical to the processing of the operation. If a control is marked critical but the server either does not support that control or it is not appropriate for the associated request, then the server will reject the request. If a control is not marked critical and the server either does not support it or it is not appropriate for the associated request, then the server will simply ignore that control and process the request as if it were not present.
- An optional value, which provides additional information for the control. Some controls do not take values, and the value encoding for controls which do take values varies based on the type of control.
Controls may be included in a request from the client to the server, as well as responses from the server to the client (including intermediate response, search result entry, and search result references, in addition to the final response message for an operation). When using request controls, they may be included in the request object at the time it is created, or may be added after the fact for UpdatableLDAPRequest objects. When using response controls, each response control class includes a get method that can be used to extract the appropriate control from an appropriate result (e.g., LDAPResult, SearchResultEntry, or SearchResultReference).
See Also:

Serialized Form

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Control()` Creates a new empty control instance that is intended to be used only for decoding controls via the `DecodeableControl` interface.
`protected`	`Control(Control control)` Creates a new control whose fields are initialized from the contents of the provided control.
	`Control(java.lang.String oid)` Creates a new control with the provided OID.
	`Control(java.lang.String oid, boolean isCritical)` Creates a new control with the provided OID and criticality.
	`Control(java.lang.String oid, boolean isCritical, ASN1OctetString value)` Creates a new control with the provided information.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Control`	`decode(ASN1Sequence controlSequence)` Decodes the provided ASN.1 sequence as an LDAP control.
`static Control`	`decode(java.lang.String oid, boolean isCritical, ASN1OctetString value)` Attempts to create the most appropriate control instance from the provided information.
`static Control[]`	`decodeControls(ASN1Sequence controlSequence)` Decodes the contents of the provided sequence as a set of controls.
`static Control`	`decodeJSONControl(JSONObject controlObject, boolean strict, boolean isRequestControl)` Attempts to decode the provided object as a JSON representation of a control.
`static void`	`deregisterDecodeableControl(java.lang.String oid)` Deregisters the decodeable control class associated with the provided OID.
`ASN1Sequence`	`encode()` Encodes this control to an ASN.1 sequence suitable for use in an LDAP message.
`static ASN1Sequence`	`encodeControls(Control[] controls)` Encodes the provided set of controls to an ASN.1 sequence suitable for inclusion in an LDAP message.
`boolean`	`equals(java.lang.Object o)` Indicates whether the provided object may be considered equal to this control.
`java.lang.String`	`getControlName()` Retrieves the user-friendly name for this control, if available.
`java.lang.String`	`getOID()` Retrieves the OID for this control.
`ASN1OctetString`	`getValue()` Retrieves the encoded value for this control.
`int`	`hashCode()` Retrieves a hash code for this control.
`boolean`	`hasValue()` Indicates whether this control has a value.
`boolean`	`isCritical()` Indicates whether this control should be considered critical.
`static Control`	`readFrom(ASN1StreamReader reader)` Reads an LDAP control from the provided ASN.1 stream reader.
`static void`	`registerDecodeableControl(java.lang.String oid, DecodeableControl controlInstance)` Registers the provided class to be used in an attempt to decode controls with the specified OID.
`static void`	`registerDecodeableControl(java.lang.String oid, java.lang.String className)` Registers the specified class to be used in an attempt to decode controls with the specified OID.
`JSONObject`	`toJSONControl()` Retrieves a representation of this control as a JSON object.
`java.lang.String`	`toString()` Retrieves a string representation of this LDAP control.
`void`	`toString(java.lang.StringBuilder buffer)` Appends a string representation of this LDAP control to the provided buffer.
`void`	`writeTo(ASN1Buffer writer)` Writes an ASN.1-encoded representation of this control to the provided ASN.1 stream writer.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Control
```
protected Control()
```
    Creates a new empty control instance that is intended to be used only for decoding controls via the DecodeableControl interface. All DecodeableControl objects must provide a default constructor that can be used to create an instance suitable for invoking the decodeControl method.
  - Control
```
protected Control(@NotNull
                  Control control)
```
    Creates a new control whose fields are initialized from the contents of the provided control.
    
    Parameters:
    
    control - The control whose information should be used to create this new control.
  - Control
```
public Control(@NotNull
               java.lang.String oid)
```
    Creates a new control with the provided OID. It will not be critical, and it will not have a value.
    
    Parameters:
    
    oid - The OID for this control. It must not be null.
  - Control
```
public Control(@NotNull
               java.lang.String oid,
               boolean isCritical)
```
    Creates a new control with the provided OID and criticality. It will not have a value.
    
    Parameters:
    
    oid - The OID for this control. It must not be null.
    
    isCritical - Indicates whether this control should be considered critical.
  - Control
```
public Control(@NotNull
               java.lang.String oid,
               boolean isCritical,
               @Nullable
               ASN1OctetString value)
```
    Creates a new control with the provided information.
    
    Parameters:
    
    oid - The OID for this control. It must not be null.
    
    isCritical - Indicates whether this control should be considered critical.
    
    value - The value for this control. It may be null if there is no value.
- Method Detail
  - getOID
```
@NotNull
public final java.lang.String getOID()
```
    Retrieves the OID for this control.
    
    Returns:
    
    The OID for this control.
  - isCritical
```
public final boolean isCritical()
```
    Indicates whether this control should be considered critical.
    
    Returns:
    
    true if this control should be considered critical, or false if not.
  - hasValue
```
public final boolean hasValue()
```
    Indicates whether this control has a value.
    
    Returns:
    
    true if this control has a value, or false if not.
  - getValue
```
@Nullable
public final ASN1OctetString getValue()
```
    Retrieves the encoded value for this control.
    
    Returns:
    
    The encoded value for this control, or null if there is no value.
  - writeTo
```
public final void writeTo(@NotNull
                          ASN1Buffer writer)
```
    Writes an ASN.1-encoded representation of this control to the provided ASN.1 stream writer.
    
    Parameters:
    
    writer - The ASN.1 stream writer to which the encoded representation should be written.
  - encode
```
@NotNull
public final ASN1Sequence encode()
```
    Encodes this control to an ASN.1 sequence suitable for use in an LDAP message.
    
    Returns:
    
    The encoded representation of this control.
  - readFrom
```
@NotNull
public static Control readFrom(@NotNull
                                        ASN1StreamReader reader)
                                 throws LDAPException
```
    Reads an LDAP control from the provided ASN.1 stream reader.
    
    Parameters:
    
    reader - The ASN.1 stream reader from which to read the control.
    
    Returns:
    
    The decoded control.
    
    Throws:
    
    LDAPException - If a problem occurs while attempting to read or parse the control.
  - decode
```
@NotNull
public static Control decode(@NotNull
                                      ASN1Sequence controlSequence)
                               throws LDAPException
```
    Decodes the provided ASN.1 sequence as an LDAP control.
    
    Parameters:
    
    controlSequence - The ASN.1 sequence to be decoded.
    
    Returns:
    
    The decoded control.
    
    Throws:
    
    LDAPException - If a problem occurs while attempting to decode the provided ASN.1 sequence as an LDAP control.
  - decode
```
@NotNull
public static Control decode(@NotNull
                                      java.lang.String oid,
                                      boolean isCritical,
                                      @Nullable
                                      ASN1OctetString value)
                               throws LDAPException
```
    Attempts to create the most appropriate control instance from the provided information. If a DecodeableControl instance has been registered for the specified OID, then this method will attempt to use that instance to construct a control. If that fails, or if no appropriate DecodeableControl is registered, then a generic control will be returned.
    
    Parameters:
    
    oid - The OID for the control. It must not be null.
    
    isCritical - Indicates whether the control should be considered critical.
    
    value - The value for the control. It may be null if there is no value.
    
    Returns:
    
    The decoded control.
    
    Throws:
    
    LDAPException - If a problem occurs while attempting to decode the provided ASN.1 sequence as an LDAP control.
  - encodeControls
```
@NotNull
public static ASN1Sequence encodeControls(@NotNull
                                                   Control[] controls)
```
    Encodes the provided set of controls to an ASN.1 sequence suitable for inclusion in an LDAP message.
    
    Parameters:
    
    controls - The set of controls to be encoded.
    
    Returns:
    
    An ASN.1 sequence containing the encoded set of controls.
  - decodeControls
```
@NotNull
public static Control[] decodeControls(@NotNull
                                                ASN1Sequence controlSequence)
                                         throws LDAPException
```
    Decodes the contents of the provided sequence as a set of controls.
    
    Parameters:
    
    controlSequence - The ASN.1 sequence containing the encoded set of controls.
    
    Returns:
    
    The decoded set of controls.
    
    Throws:
    
    LDAPException - If a problem occurs while attempting to decode any of the controls.
  - registerDecodeableControl
```
public static void registerDecodeableControl(@NotNull
                                             java.lang.String oid,
                                             @NotNull
                                             java.lang.String className)
```
    Registers the specified class to be used in an attempt to decode controls with the specified OID.
    
    Parameters:
    
    oid - The response control OID for which the provided class will be registered.
    
    className - The fully-qualified name for the Java class that provides the decodeable control implementation to use for the provided OID.
  - registerDecodeableControl
```
public static void registerDecodeableControl(@NotNull
                                             java.lang.String oid,
                                             @NotNull
                                             DecodeableControl controlInstance)
```
    Registers the provided class to be used in an attempt to decode controls with the specified OID.
    
    Parameters:
    
    oid - The response control OID for which the provided class will be registered.
    
    controlInstance - The control instance that should be used to decode controls with the provided OID.
  - deregisterDecodeableControl
```
public static void deregisterDecodeableControl(@NotNull
                                               java.lang.String oid)
```
    Deregisters the decodeable control class associated with the provided OID.
    
    Parameters:
    
    oid - The response control OID for which to deregister the decodeable control class.
  - hashCode
```
public final int hashCode()
```
    Retrieves a hash code for this control.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    A hash code for this control.
  - equals
```
public final boolean equals(@Nullable
                            java.lang.Object o)
```
    Indicates whether the provided object may be considered equal to this control.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    o - The object for which to make the determination.
    
    Returns:
    
    true if the provided object may be considered equal to this control, or false if not.
  - 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.
    
    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 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.
    - 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 control. At most one of the value-base64 and value-json fields may be present, and both fields will be absent for controls that do not have a value.
    - value-json -- An optional JSON object field whose value is a user-friendly, control-specific representation of the value for this control. This representation of the value is only available for certain types of controls, and subclasses will override this method to provide an appropriate representation of that value, and their Javadoc documentation will describe the fields that may be present in the value. At most one of the value-base64 and value-json fields may be present, and both fields will be absent for controls that do not have a value.
    Returns:
    
    A JSON object that contains a representation of this control.
  - decodeJSONControl
```
@NotNull
public static Control decodeJSONControl(@NotNull
                                                 JSONObject controlObject,
                                                 boolean strict,
                                                 boolean isRequestControl)
                                          throws LDAPException
```
    Attempts to decode the provided object as a JSON representation of a control. If the OID extracted from the provided JSON object matches the OID for a control with a known-supported encoding, then control-specific decoding will be used to allow for a more user-friendly version of the object (for example, with a value formatted as a JSON object rather than raw base64-encoded data). If no specific support is available for the specified control, then a more generic decoding will be used, and only base64-encoded values will be supported.
    
    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, and potentially if any other constraints are violated. If this is false, then unrecognized fields will be ignored, and potentially other lenient parsing will be used.
    
    isRequestControl - Indicates whether the provided JSON object represents a request control (if true) rather than a response control (if false). This will be used in cases where both a request and response control of the same type share the same OID.
    
    Returns:
    
    The control that was decoded from the provided JSON object.
    
    Throws:
    
    LDAPException - If the provided JSON object cannot be parsed as a valid control.
  - toString
```
@NotNull
public java.lang.String toString()
```
    Retrieves a string representation of this LDAP control.
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    A string representation of this LDAP control.
  - toString
```
public void toString(@NotNull
                     java.lang.StringBuilder buffer)
```
    Appends a string representation of this LDAP control to the provided buffer.
    
    Parameters:
    
    buffer - The buffer to which to append the string representation of this buffer.

Class Control

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Control

Control

Control

Control

Control

Method Detail

getOID

isCritical

hasValue

getValue

writeTo

encode

readFrom

decode

decode

encodeControls

decodeControls

registerDecodeableControl

registerDecodeableControl

deregisterDecodeableControl

hashCode

equals

getControlName

toJSONControl

decodeJSONControl

toString

toString