Package com.unboundid.ldap.sdk
Class Control
- java.lang.Object
-
- com.unboundid.ldap.sdk.Control
-
- All Implemented Interfaces:
java.io.Serializable
- Direct Known Subclasses:
AccountUsableRequestControl
,AccountUsableResponseControl
,ActiveDirectoryDirSyncControl
,AdministrativeOperationRequestControl
,AssertionRequestControl
,AssuredReplicationRequestControl
,AssuredReplicationResponseControl
,AuthorizationIdentityRequestControl
,AuthorizationIdentityResponseControl
,BatchedTransactionSpecificationRequestControl
,ContentSyncDoneControl
,ContentSyncRequestControl
,ContentSyncStateControl
,DontUseCopyRequestControl
,DraftBeheraLDAPPasswordPolicy10RequestControl
,DraftBeheraLDAPPasswordPolicy10ResponseControl
,DraftZeilengaLDAPNoOp12RequestControl
,EntryChangeNotificationControl
,ExcludeBranchRequestControl
,ExtendedSchemaInfoRequestControl
,GeneratePasswordRequestControl
,GeneratePasswordResponseControl
,GetAuthorizationEntryRequestControl
,GetAuthorizationEntryResponseControl
,GetBackendSetIDRequestControl
,GetBackendSetIDResponseControl
,GetEffectiveRightsRequestControl
,GetPasswordPolicyStateIssuesRequestControl
,GetPasswordPolicyStateIssuesResponseControl
,GetServerIDRequestControl
,GetServerIDResponseControl
,GetUserResourceLimitsRequestControl
,GetUserResourceLimitsResponseControl
,HardDeleteRequestControl
,IgnoreNoUserModificationRequestControl
,InteractiveTransactionSpecificationRequestControl
,InteractiveTransactionSpecificationResponseControl
,IntermediateClientRequestControl
,IntermediateClientResponseControl
,JoinRequestControl
,JoinResultControl
,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
,RetainIdentityRequestControl
,RetirePasswordRequestControl
,ReturnConflictEntriesRequestControl
,RouteToBackendSetRequestControl
,RouteToServerRequestControl
,ServerSideSortRequestControl
,ServerSideSortResponseControl
,SimplePagedResultsControl
,SoftDeletedEntryAccessRequestControl
,SoftDeleteRequestControl
,SoftDeleteResponseControl
,SubentriesRequestControl
,SubtreeDeleteRequestControl
,SuppressOperationalAttributeUpdateRequestControl
,SuppressReferentialIntegrityUpdatesRequestControl
,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.
UpdatableLDAPRequest
objects. When using response controls, each response control class includes aget
method that can be used to extract the appropriate control from an appropriate result (e.g.,LDAPResult
,SearchResultEntry
, orSearchResultReference
).- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
Control()
Creates a new empty control instance that is intended to be used only for decoding controls via theDecodeableControl
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 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 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.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.
-
-
-
Constructor Detail
-
Control
protected Control()
Creates a new empty control instance that is intended to be used only for decoding controls via theDecodeableControl
interface. AllDecodeableControl
objects must provide a default constructor that can be used to create an instance suitable for invoking thedecodeControl
method.
-
Control
protected Control(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(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 benull
.
-
Control
public Control(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 benull
.isCritical
- Indicates whether this control should be considered critical.
-
Control
public Control(java.lang.String oid, boolean isCritical, ASN1OctetString value)
Creates a new control with the provided information.- Parameters:
oid
- The OID for this control. It must not benull
.isCritical
- Indicates whether this control should be considered critical.value
- The value for this control. It may benull
if there is no value.
-
-
Method Detail
-
getOID
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, orfalse
if not.
-
hasValue
public final boolean hasValue()
Indicates whether this control has a value.- Returns:
true
if this control has a value, orfalse
if not.
-
getValue
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(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
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
public static Control readFrom(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
public static Control decode(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
public static Control decode(java.lang.String oid, boolean isCritical, ASN1OctetString value) throws LDAPException
Attempts to create the most appropriate control instance from the provided information. If aDecodeableControl
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 appropriateDecodeableControl
is registered, then a generic control will be returned.- Parameters:
oid
- The OID for the control. It must not benull
.isCritical
- Indicates whether the control should be considered critical.value
- The value for the control. It may benull
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
public static ASN1Sequence encodeControls(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
public static Control[] decodeControls(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(java.lang.String oid, 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(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 classjava.lang.Object
- Returns:
- A hash code for this control.
-
equals
public final boolean equals(java.lang.Object o)
Indicates whether the provided object may be considered equal to this control.- Overrides:
equals
in classjava.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, orfalse
if not.
-
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.- Returns:
- The user-friendly name for this control, or the OID if no user-friendly name is available.
-
toString
public java.lang.String toString()
Retrieves a string representation of this LDAP control.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representation of this LDAP control.
-
toString
public void toString(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.
-
-