@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class UniquenessRequestControl extends Control
ResultCode.ASSERTION_FAILED
and a UniquenessResponseControl
for each uniqueness constraint that was not satisfied.
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.
UniquenessMultipleAttributeBehavior
enum. If both a set of attribute
types and a filter are provided, then only entries matching both sets of
criteria will be considered a conflict.
true
or false
, and a value with the following
encoding:
UniquenessRequestValue ::= SEQUENCE { uniquenessID [0] OCTET STRING, attributeTypes [1] SET OF OCTET STRING OPTIONAL, multipleAttributeBehavior [2] ENUMERATED { uniqueWithinEachAttribute (0), uniqueAcrossAllAttributesIncludingInSameEntry (1), uniqueAcrossAllAttributesExceptInSameEntry (2), uniqueInCombination (3), ... } DEFAULT uniqueWithinEachAttribute, baseDN [3] LDAPDN OPTIONAL, filter [4] Filter OPTIONAL, preventConflictsWithSoftDeletedEntries [5] BOOLEAN DEFAULT FALSE, preCommitValidationLevel [6] ENUMERATED { none (0), allSubtreeViews (1), allBackendSets (2), allAvailableBackendServers (3), ... } DEFAULT allSubtreeViews, postCommitValidationLevel [7] ENUMERATED { none (0), allSubtreeViews (1), allBackendSets (2), allAvailableBackendServers (3), ... } DEFAULT allSubtreeViews, alertOnPostCommitConflictDetection [8] BOOLEAN DEFAULT TRUE, createConflictPreventionDetailsEntry [9] BOOLEAN DEFAULT FALSE, ... }
// Create the properties to build a uniqueness request control that // will try to prevent an add operation from creating a new entry // that has the same uid as an existing entry in the server. During // pre-commit processing (which happens before the server actually // processes the add), the server will check at least one server in // each entry-balancing backend set (or just one server in a // non-entry-balanced deployment). During post-commit processing // (which happens if the add succeeds), the server will double-check // that no conflicting entry was added on any available server in the // topology. Also ensure that the server will not allow conflicts // with soft-deleted entries. final UniquenessRequestControlProperties uniquenessProperties = new UniquenessRequestControlProperties("uid"); uniquenessProperties.setPreCommitValidationLevel( UniquenessValidationLevel.ALL_BACKEND_SETS); uniquenessProperties.setPostCommitValidationLevel( UniquenessValidationLevel.ALL_AVAILABLE_BACKEND_SERVERS); uniquenessProperties.setPreventConflictsWithSoftDeletedEntries(true); // Create the request control. It will be critical so that the // server will not attempt to process the add if it can't honor the // uniqueness request. final boolean isCritical = true; final String uniquenessID = "uid-uniqueness"; final UniquenessRequestControl uniquenessRequestControl = new UniquenessRequestControl(isCritical, uniquenessID, uniquenessProperties); // Attach the control to an add request. addRequest.addControl(uniquenessRequestControl); // Send the add request to the server and read the result. try { final LDAPResult addResult = connection.add(addRequest); // The add operation succeeded, so the entry should have been // created, but there is still the possibility that a post-commit // conflict was discovered, indicating that another request // processed at about the same time as our add introduced a // conflicting entry. final Map<String,UniquenessResponseControl> uniquenessResponses; try { uniquenessResponses = UniquenessResponseControl.get(addResult); } catch (final LDAPException e) { throw new RuntimeException( "The add succeeded, but an error occurred while trying " + "to decode a uniqueness response control in add " + "result " + addResult + ": " + StaticUtils.getExceptionMessage(e), e); } final UniquenessResponseControl uniquenessResponseControl = uniquenessResponses.get(uniquenessID); if ((uniquenessResponseControl != null) && uniquenessResponseControl.uniquenessConflictFound()) { throw new RuntimeException( "The add succeeded, but a uniqueness conflict was found " + "Uniqueness validation message: " + uniquenessResponseControl.getValidationMessage()); } } catch (final LDAPException e) { // The add attempt failed. It might have been because of a // uniqueness problem, or it could have been for some other reason. // To figure out which it was, look to see if there is an // appropriate uniqueness response control. final Map<String, UniquenessResponseControl> uniquenessResponses; try { uniquenessResponses = UniquenessResponseControl.get(e.toLDAPResult()); } catch (final LDAPException e2) { throw new LDAPException(e.getResultCode(), "The add attempt failed with result " + e.toLDAPResult() + ", and an error occurred while trying to decode a " + "uniqueness response control in the result: " + StaticUtils.getExceptionMessage(e2), e); } final UniquenessResponseControl uniquenessResponseControl = uniquenessResponses.get(uniquenessID); if (uniquenessResponseControl == null) { // The add result didn't include a uniqueness response control, // indicating that the failure was not because of a uniqueness // conflict. throw e; } if (uniquenessResponseControl.uniquenessConflictFound()) { // The add failed, and the uniqueness response control indicates // that the failure was because of a uniqueness conflict. final UniquenessValidationResult preCommitResult = uniquenessResponseControl.getPreCommitValidationResult(); final UniquenessValidationResult postCommitResult = uniquenessResponseControl.getPreCommitValidationResult(); final String validationMessage = uniquenessResponseControl.getValidationMessage(); throw e; } else { // The add failed, but the uniqueness response control indicates // that the failure was not because of a uniqueness conflict. throw e; } }
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
UNIQUENESS_REQUEST_OID
The OID (1.3.6.1.4.1.30221.2.5.52) for the uniqueness request control.
|
Constructor and Description |
---|
UniquenessRequestControl(boolean isCritical,
java.lang.String uniquenessID,
UniquenessRequestControlProperties properties)
Creates a new uniqueness request control with the provided information.
|
UniquenessRequestControl(Control control)
Creates a new uniqueness request control that is decoded from the provided
generic control.
|
Modifier and Type | Method and Description |
---|---|
boolean |
alertOnPostCommitConflictDetection()
Indicates whether the server should raise an administrative alert if a
conflict is detected during post-commit validation processing.
|
boolean |
createConflictPreventionDetailsEntry()
Indicates whether the server should create a temporary conflict prevention
details entry before beginning pre-commit validation to provide better
support for preventing conflicts.
|
java.util.Set<java.lang.String> |
getAttributeTypes()
Retrieves the set of attribute types that the server will check for
uniqueness conflicts.
|
java.lang.String |
getBaseDN()
Retrieves the base DN that will be used for searches used to identify
uniqueness conflicts, if defined.
|
java.lang.String |
getControlName()
Retrieves the user-friendly name for this control, if available.
|
Filter |
getFilter()
Retrieves a filter that will be used to identify uniqueness conflicts, if
defined.
|
UniquenessMultipleAttributeBehavior |
getMultipleAttributeBehavior()
Retrieves the behavior that the server should exhibit if multiple attribute
types are configured.
|
UniquenessValidationLevel |
getPostCommitValidationLevel()
Retrieves the post-commit validation level, which will be used to identify
any conflicts that were introduced by the request with which the control is
associated, or by some other concurrent changed processed in the server.
|
UniquenessValidationLevel |
getPreCommitValidationLevel()
Retrieves the pre-commit validation level, which will be used to identify
any conflicts before the associated request is processed.
|
java.lang.String |
getUniquenessID()
Retrieves the uniqueness identifier for this control, which may be used to
identify the response control that corresponds to this request control.
|
boolean |
preventConflictsWithSoftDeletedEntries()
Indicates whether the server should attempt to identify conflicts with
soft-deleted entries.
|
void |
toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP control to the provided
buffer.
|
decode, decode, decodeControls, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toString, writeTo
@NotNull public static final java.lang.String UNIQUENESS_REQUEST_OID
public UniquenessRequestControl(boolean isCritical, @Nullable java.lang.String uniquenessID, @NotNull UniquenessRequestControlProperties properties) throws LDAPException
isCritical
- Indicates whether the control should be considered
critical.uniquenessID
- A value that will be used to correlate this request
control with its corresponding response control. If
this is null
, then a unique identifier will
be automatically generated.properties
- The set of properties for this control. It must not
be null
.LDAPException
- If the provided properties cannot be used to create
a valid uniqueness request control.public UniquenessRequestControl(@NotNull Control control) throws LDAPException
control
- The control to be decoded as a uniqueness request control.
It must not be null
.LDAPException
- If the provided control cannot be decoded as a
valid uniqueness request control.@NotNull public java.lang.String getUniquenessID()
@NotNull public java.util.Set<java.lang.String> getAttributeTypes()
@NotNull public UniquenessMultipleAttributeBehavior getMultipleAttributeBehavior()
@Nullable public java.lang.String getBaseDN()
null
if the server should search
below all public naming contexts.@Nullable public Filter getFilter()
null
if no filter has been defined.public boolean preventConflictsWithSoftDeletedEntries()
true
if the server should identify conflicts with both
regular entries and soft-deleted entries, or false
if the
server should only identify conflicts with regular entries.@NotNull public UniquenessValidationLevel getPreCommitValidationLevel()
@NotNull public UniquenessValidationLevel getPostCommitValidationLevel()
public boolean alertOnPostCommitConflictDetection()
true
if the server should raise an administrative alert if
a conflict is detected during post-commit validation processing,
or false
if not.public boolean createConflictPreventionDetailsEntry()
true
if the server should create a temporary conflict
prevention details entry before beginning pre-commit validation,
or false
if not.@NotNull public java.lang.String getControlName()
getControlName
in class Control