com.unboundid.ldap.sdk.unboundidds.controls.InteractiveTransactionSpecificationResponseControl Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of unboundid-ldapsdk Show documentation
Show all versions of unboundid-ldapsdk Show documentation
The UnboundID LDAP SDK for Java is a fast, comprehensive, and easy-to-use
Java API for communicating with LDAP directory servers and performing
related tasks like reading and writing LDIF, encoding and decoding data
using base64 and ASN.1 BER, and performing secure communication. This
package contains the Standard Edition of the LDAP SDK, which is a
complete, general-purpose library for communicating with LDAPv3 directory
servers.
/*
* Copyright 2008-2021 Ping Identity Corporation
* All Rights Reserved.
*/
/*
* Copyright 2008-2021 Ping Identity Corporation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*
* Copyright (C) 2008-2021 Ping Identity Corporation
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License (GPLv2 only)
* or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see .
*/
package com.unboundid.ldap.sdk.unboundidds.controls;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import com.unboundid.asn1.ASN1Boolean;
import com.unboundid.asn1.ASN1Element;
import com.unboundid.asn1.ASN1OctetString;
import com.unboundid.asn1.ASN1Sequence;
import com.unboundid.ldap.sdk.Control;
import com.unboundid.ldap.sdk.DecodeableControl;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.LDAPResult;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.util.NotMutable;
import com.unboundid.util.NotNull;
import com.unboundid.util.Nullable;
import com.unboundid.util.StaticUtils;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*;
/**
*
* NOTE: The use of interactive transactions is strongly discouraged
* because it can create conditions which are prone to deadlocks between
* operations that may significantly affect performance and will result in the
* cancellation of one or both operations. It is strongly recommended that
* standard LDAP transactions (which may be started using a
* {@link com.unboundid.ldap.sdk.extensions.StartTransactionExtendedRequest})
* or a {@code MultiUpdateExtendedRequest} be used instead. Although they
* cannot include arbitrary read operations, LDAP transactions and
* multi-update operations may be used in conjunction with the
* {@link com.unboundid.ldap.sdk.controls.AssertionRequestControl},
* {@link com.unboundid.ldap.sdk.controls.PreReadRequestControl}, and
* {@link com.unboundid.ldap.sdk.controls.PostReadRequestControl} to
* incorporate some read capability into a transaction, and in conjunction
* with the {@link com.unboundid.ldap.sdk.ModificationType#INCREMENT}
* modification type to increment integer values without the need to know the
* precise value before or after the operation (although the pre-read and/or
* post-read controls may be used to determine that).
*
* This class defines an interactive transaction specification response control,
* which will be included in the server's response to an operation that included
* the {@link InteractiveTransactionSpecificationRequestControl}.
*
*
* NOTE: This class, and other classes within the
* {@code 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.
*
*
* It provides information about the state of the transaction, which may
* include:
*
* transactionValid -- Indicates whether the transaction is
* still valid in the server. This should be checked if the associated
* operation did not complete successfully.baseDNs -- This may specify the set of base DNs below
* which the client is allowed to request operations as part of this
* transaction. It may be absent if there are no restrictions on which
* base DNs may be used, or if it has not changed since the last
* response within this transaction.
* See the documentation in the
* {@code StartInteractiveTransactionExtendedRequest} class for an example of
* processing interactive transactions.
*
* @deprecated The use of interactive transactions is strongly discouraged
* because it can create conditions which are prone to deadlocks
* between operations that may significantly affect performance and
* will result in the cancellation of one or both operations.
*/
@Deprecated()
@SuppressWarnings("deprecation")
@NotMutable()
@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
public final class InteractiveTransactionSpecificationResponseControl
extends Control
implements DecodeableControl
{
/**
* The OID (1.3.6.1.4.1.30221.2.5.4) for the interactive transaction
* specification response control.
*/
@NotNull public static final String
INTERACTIVE_TRANSACTION_SPECIFICATION_RESPONSE_OID =
"1.3.6.1.4.1.30221.2.5.4";
/**
* The BER type for the {@code transactionValid} element of the control value.
*/
private static final byte TYPE_TXN_VALID = (byte) 0x80;
/**
* The BER type for the {@code baseDNs} element of the control value.
*/
private static final byte TYPE_BASE_DNS = (byte) 0xA1;
/**
* The serial version UID for this serializable class.
*/
private static final long serialVersionUID = -4323085263241417543L;
// The flag that indicates whether the associated transaction is still valid.
private final boolean transactionValid;
// The set of base DNs that may be targeted by this transaction.
@Nullable private final List baseDNs;
/**
* Creates a new empty control instance that is intended to be used only for
* decoding controls via the {@code DecodeableControl} interface.
*/
InteractiveTransactionSpecificationResponseControl()
{
transactionValid = false;
baseDNs = null;
}
/**
* Creates a new interactive transaction specification response control with
* the provided information. It will not be marked critical.
*
* @param transactionValid Indicates whether the associated transaction is
* still valid.
* @param baseDNs The set of base DNs that may be targeted over the
* course of the transaction. It may be
* {@code null} if there are no restrictions or the
* set of restrictions has not changed since the
* last response.
*/
public InteractiveTransactionSpecificationResponseControl(
final boolean transactionValid,
@Nullable final List baseDNs)
{
super(INTERACTIVE_TRANSACTION_SPECIFICATION_RESPONSE_OID, false,
encodeValue(transactionValid, baseDNs));
this.transactionValid = transactionValid;
if (baseDNs == null)
{
this.baseDNs = null;
}
else
{
this.baseDNs =
Collections.unmodifiableList(new ArrayList<>(baseDNs));
}
}
/**
* Creates a new interactive transaction specification response control with
* the provided information.
*
* @param oid The OID for the control.
* @param isCritical Indicates whether the control should be marked
* critical.
* @param value The encoded value for the control. This may be
* {@code null} if no value was provided.
*
* @throws LDAPException If the provided control cannot be decoded as an
* interactive transaction specification response
* control.
*/
public InteractiveTransactionSpecificationResponseControl(
@NotNull final String oid,
final boolean isCritical,
@Nullable final ASN1OctetString value)
throws LDAPException
{
super(oid, isCritical, value);
if (value == null)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_INT_TXN_RESPONSE_NO_VALUE.get());
}
final ASN1Element[] elements;
try
{
final ASN1Element valueElement = ASN1Element.decode(value.getValue());
elements = ASN1Sequence.decodeAsSequence(valueElement).elements();
}
catch (final Exception e)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_INT_TXN_RESPONSE_VALUE_NOT_SEQUENCE.get(
e.getMessage()), e);
}
Boolean isValid = null;
List baseDNList = null;
for (final ASN1Element element : elements)
{
switch (element.getType())
{
case TYPE_TXN_VALID:
try
{
isValid = ASN1Boolean.decodeAsBoolean(element).booleanValue();
}
catch (final Exception e)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_INT_TXN_RESPONSE_TXN_VALID_NOT_BOOLEAN.get(e.getMessage()),
e);
}
break;
case TYPE_BASE_DNS:
try
{
final ASN1Sequence s = ASN1Sequence.decodeAsSequence(element);
baseDNList = new ArrayList<>(s.elements().length);
for (final ASN1Element e : s.elements())
{
baseDNList.add(
ASN1OctetString.decodeAsOctetString(e).stringValue());
}
}
catch (final Exception e)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_INT_TXN_RESPONSE_BASE_DNS_NOT_SEQUENCE.get(e.getMessage()),
e);
}
break;
default:
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_INT_TXN_RESPONSE_INVALID_ELEMENT_TYPE.get(
StaticUtils.toHex(element.getType())));
}
}
if (isValid == null)
{
throw new LDAPException(ResultCode.DECODING_ERROR,
ERR_INT_TXN_RESPONSE_NO_TXN_VALID.get());
}
transactionValid = isValid;
if (baseDNList == null)
{
baseDNs = null;
}
else
{
baseDNs = Collections.unmodifiableList(baseDNList);
}
}
/**
* Encodes the provided information into an ASN.1 octet string suitable for
* use as the value of this control.
*
* @param transactionValid Indicates whether the associated transaction is
* still valid.
* @param baseDNs The set of base DNs that may be targeted over the
* course of the transaction. It may be
* {@code null} if there are no restrictions or the
* set of restrictions has not changed since the
* last response.
*
* @return The ASN1 octet string that may be used as the control value.
*/
@NotNull()
private static ASN1OctetString encodeValue(final boolean transactionValid,
@Nullable final List baseDNs)
{
final ASN1Element[] elements;
if (baseDNs == null)
{
elements = new ASN1Element[]
{
new ASN1Boolean(TYPE_TXN_VALID, transactionValid)
};
}
else
{
final ASN1Element[] baseDNElements = new ASN1Element[baseDNs.size()];
for (int i=0; i < baseDNElements.length; i++)
{
baseDNElements[i] = new ASN1OctetString(baseDNs.get(i));
}
elements = new ASN1Element[]
{
new ASN1Boolean(TYPE_TXN_VALID, transactionValid),
new ASN1Sequence(TYPE_BASE_DNS, baseDNElements)
};
}
return new ASN1OctetString(new ASN1Sequence(elements).encode());
}
/**
* {@inheritDoc}
*/
@Override()
@NotNull()
public InteractiveTransactionSpecificationResponseControl decodeControl(
@NotNull final String oid, final boolean isCritical,
@Nullable final ASN1OctetString value)
throws LDAPException
{
return new InteractiveTransactionSpecificationResponseControl(oid,
isCritical, value);
}
/**
* Extracts an interactive transaction specification response control from the
* provided result.
*
* @param result The result from which to retrieve the interactive
* transaction specification response control.
*
* @return The interactive transaction specification response control
* contained in the provided result, or {@code null} if the result
* did not contain an interactive transaction specification response
* control.
*
* @throws LDAPException If a problem is encountered while attempting to
* decode the interactive transaction specification
* response control contained in the provided result.
*/
@Nullable()
public static InteractiveTransactionSpecificationResponseControl get(
@NotNull final LDAPResult result)
throws LDAPException
{
final Control c = result.getResponseControl(
INTERACTIVE_TRANSACTION_SPECIFICATION_RESPONSE_OID);
if (c == null)
{
return null;
}
if (c instanceof InteractiveTransactionSpecificationResponseControl)
{
return (InteractiveTransactionSpecificationResponseControl) c;
}
else
{
return new InteractiveTransactionSpecificationResponseControl(c.getOID(),
c.isCritical(), c.getValue());
}
}
/**
* Indicates whether the associated transaction is still valid on the server.
*
* @return {@code true} if the associated transaction is still valid on the
* server and may be used for future operations, or {@code false} if
* the transaction has been aborted and may no longer be used.
*/
public boolean transactionValid()
{
return transactionValid;
}
/**
* Retrieves the set of base DNs below which operations which are part of the
* transaction may be performed.
*
* @return The set of base DNs below which operations may be performed as
* part of the transaction, or {@code null} if there are no
* restrictions or if the set of restrictions has not changed since
* the last response.
*/
@Nullable()
public List getBaseDNs()
{
return baseDNs;
}
/**
* {@inheritDoc}
*/
@Override()
@NotNull()
public String getControlName()
{
return INFO_CONTROL_NAME_INTERACTIVE_TXN_RESPONSE.get();
}
/**
* {@inheritDoc}
*/
@Override()
public void toString(@NotNull final StringBuilder buffer)
{
buffer.append("InteractiveTransactionSpecificationResponseControl(");
buffer.append("transactionValid=");
buffer.append(transactionValid);
buffer.append(", baseDNs=");
if (baseDNs == null)
{
buffer.append("null");
}
else
{
buffer.append('{');
for (int i=0; i < baseDNs.size(); i++)
{
if (i > 0)
{
buffer.append(", ");
}
buffer.append('\'');
buffer.append(baseDNs.get(i));
buffer.append('\'');
}
buffer.append('}');
}
buffer.append(", isCritical=");
buffer.append(isCritical());
buffer.append(')');
}
}