001/*
002 * Copyright 2010-2019 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2010-2019 Ping Identity Corporation
007 *
008 * This program is free software; you can redistribute it and/or modify
009 * it under the terms of the GNU General Public License (GPLv2 only)
010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011 * as published by the Free Software Foundation.
012 *
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Public License for more details.
017 *
018 * You should have received a copy of the GNU General Public License
019 * along with this program; if not, see <http://www.gnu.org/licenses>.
020 */
021package com.unboundid.ldap.sdk.controls;
022
023
024
025import com.unboundid.asn1.ASN1OctetString;
026import com.unboundid.ldap.sdk.Control;
027import com.unboundid.ldap.sdk.LDAPException;
028import com.unboundid.ldap.sdk.ResultCode;
029import com.unboundid.ldap.sdk.experimental.
030            DraftBeheraLDAPPasswordPolicy10RequestControl;
031import com.unboundid.ldap.sdk.extensions.StartTransactionExtendedRequest;
032import com.unboundid.util.NotMutable;
033import com.unboundid.util.ThreadSafety;
034import com.unboundid.util.ThreadSafetyLevel;
035import com.unboundid.util.Validator;
036
037import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
038
039
040
041/**
042 * This class provides an implementation of the transaction specification
043 * request control as defined in
044 * <A HREF="http://www.ietf.org/rfc/rfc5805.txt">RFC 5805</A>.  It may be used
045 * to indicate that the associated add, delete, modify, modify DN, or password
046 * modify operation is part of an LDAP transaction.  The transaction should be
047 * created with the start transaction extended operation, which will obtain a
048 * transaction ID, and the transaction may be committed or aborted using the end
049 * transaction extended operation.
050 * <BR><BR>
051 * Note that directory servers may limit the set of controls that are available
052 * for use in requests that are part of a transaction.  RFC 5805 section 4
053 * indicates that the following controls may be used in conjunction with the
054 * transaction specification request control:  {@link AssertionRequestControl},
055 * {@link ManageDsaITRequestControl}, {@link PreReadRequestControl}, and
056 * {@link PostReadRequestControl}.  The
057 * {@link ProxiedAuthorizationV1RequestControl} and
058 * {@link ProxiedAuthorizationV2RequestControl} controls cannot be included in
059 * requests that are part of a transaction, but you can include them in the
060 * {@link StartTransactionExtendedRequest} to indicate that all operations
061 * within the transaction should be processed with the specified authorization
062 * identity.
063 * <BR><BR>
064 * The Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products
065 * support the following additional UnboundID-specific controls in conjunction
066 * with operations included in a transaction:  account usable request control,
067 * {@link DraftBeheraLDAPPasswordPolicy10RequestControl}, hard delete request
068 * control, intermediate client request control, replication repair request
069 * control, soft delete request control, soft deleted entry access request
070 * control, {@link SubtreeDeleteRequestControl}, and undelete request control.
071 * <BR><BR>
072 * See the documentation for the {@link StartTransactionExtendedRequest} class
073 * for an example of processing an LDAP transaction.
074 */
075@NotMutable()
076@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
077public final class TransactionSpecificationRequestControl
078       extends Control
079{
080  /**
081   * The OID (1.3.6.1.1.21.2) for the transaction specification request control.
082   */
083  public static final String TRANSACTION_SPECIFICATION_REQUEST_OID =
084       "1.3.6.1.1.21.2";
085
086
087
088  /**
089   * The serial version UID for this serializable class.
090   */
091  private static final long serialVersionUID = 6489819774149849092L;
092
093
094
095  // The transaction ID for the associated transaction.
096  private final ASN1OctetString transactionID;
097
098
099
100  /**
101   * Creates a new transaction specification request control with the provided
102   * transaction ID.
103   *
104   * @param  transactionID  The transaction ID for the associated transaction,
105   *                        as obtained from the start transaction extended
106   *                        operation.  It must not be {@code null}.
107   */
108  public TransactionSpecificationRequestControl(
109              final ASN1OctetString transactionID)
110  {
111    super(TRANSACTION_SPECIFICATION_REQUEST_OID, true,
112         new ASN1OctetString(transactionID.getValue()));
113
114    Validator.ensureNotNull(transactionID);
115    this.transactionID = transactionID;
116  }
117
118
119
120  /**
121   * Creates a new transaction specification request control which is decoded
122   * from the provided generic control.
123   *
124   * @param  control  The generic control to be decoded as a transaction
125   *                  specification request control.
126   *
127   * @throws  LDAPException  If the provided control cannot be decoded as a
128   *                         transaction specification request control.
129   */
130  public TransactionSpecificationRequestControl(final Control control)
131         throws LDAPException
132  {
133    super(control);
134
135    transactionID = control.getValue();
136    if (transactionID == null)
137    {
138      throw new LDAPException(ResultCode.DECODING_ERROR,
139           ERR_TXN_REQUEST_CONTROL_NO_VALUE.get());
140    }
141  }
142
143
144
145  /**
146   * Retrieves the transaction ID for the associated transaction.
147   *
148   * @return  The transaction ID for the associated transaction.
149   */
150  public ASN1OctetString getTransactionID()
151  {
152    return transactionID;
153  }
154
155
156
157  /**
158   * {@inheritDoc}
159   */
160  @Override()
161  public String getControlName()
162  {
163    return INFO_CONTROL_NAME_TXN_SPECIFICATION_REQUEST.get();
164  }
165
166
167
168  /**
169   * {@inheritDoc}
170   */
171  @Override()
172  public void toString(final StringBuilder buffer)
173  {
174    buffer.append("TransactionSpecificationRequestControl(transactionID='");
175    buffer.append(transactionID.stringValue());
176    buffer.append("')");
177  }
178}