001/*
002 * Copyright 2007-2018 Ping Identity Corporation
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2015-2018 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.unboundidds.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.controls.AssertionRequestControl;
030import com.unboundid.ldap.sdk.controls.ManageDsaITRequestControl;
031import com.unboundid.ldap.sdk.controls.PostReadRequestControl;
032import com.unboundid.ldap.sdk.controls.PreReadRequestControl;
033import com.unboundid.ldap.sdk.controls.ProxiedAuthorizationV1RequestControl;
034import com.unboundid.ldap.sdk.controls.ProxiedAuthorizationV2RequestControl;
035import com.unboundid.ldap.sdk.controls.SubtreeDeleteRequestControl;
036import com.unboundid.ldap.sdk.unboundidds.extensions.
037            StartBatchedTransactionExtendedRequest;
038import com.unboundid.util.NotMutable;
039import com.unboundid.util.ThreadSafety;
040import com.unboundid.util.ThreadSafetyLevel;
041
042import static com.unboundid.ldap.sdk.unboundidds.controls.ControlMessages.*;
043import static com.unboundid.util.Validator.*;
044
045
046
047/**
048 * This class provides an implementation of the batched transaction
049 * specification request control, which may be used to indicate that the
050 * associated add, delete, modify, modify DN, or password modify operation is
051 * part of a batched transaction.  The transaction should be created with the
052 * start batched transaction extended operation, which will obtain a transaction
053 * ID, and the transaction may be committed or aborted using the end batched
054 * transaction extended operation.
055 * <BR>
056 * <BLOCKQUOTE>
057 *   <B>NOTE:</B>  This class, and other classes within the
058 *   {@code com.unboundid.ldap.sdk.unboundidds} package structure, are only
059 *   supported for use against Ping Identity, UnboundID, and Alcatel-Lucent 8661
060 *   server products.  These classes provide support for proprietary
061 *   functionality or for external specifications that are not considered stable
062 *   or mature enough to be guaranteed to work in an interoperable way with
063 *   other types of LDAP servers.
064 * </BLOCKQUOTE>
065 * <BR>
066 * Note that directory servers may limit the set of controls that are available
067 * for use in requests that are part of a transaction.  RFC 5805 section 4
068 * indicates that the following controls may be used in conjunction with the
069 * transaction specification request control:  {@link AssertionRequestControl},
070 * {@link ManageDsaITRequestControl}, {@link PreReadRequestControl}, and
071 * {@link PostReadRequestControl}.  The
072 * {@link ProxiedAuthorizationV1RequestControl} and
073 * {@link ProxiedAuthorizationV2RequestControl} controls cannot be included in
074 * requests that are part of a transaction, but you can include them in the
075 * {@link StartBatchedTransactionExtendedRequest} to indicate that all
076 * operations within the transaction should be processed with the specified
077 * authorization identity.
078 * <BR><BR>
079 * The Ping Identity, UnboundID, and Alcatel-Lucent 8661 server products support
080 * the following additional UnboundID-specific controls in conjunction with
081 * operations included in a transaction:  {@link AccountUsableRequestControl},
082 * {@link HardDeleteRequestControl}, {@link IntermediateClientRequestControl},
083 * {@link PasswordPolicyRequestControl},
084 * {@link ReplicationRepairRequestControl}, {@link SoftDeleteRequestControl},
085 * {@link SoftDeletedEntryAccessRequestControl},
086 * {@link SubtreeDeleteRequestControl}, and {@link UndeleteRequestControl}.
087 * <BR><BR>
088 * See the documentation for the {@link StartBatchedTransactionExtendedRequest}
089 * class for an example of processing a batched transaction.
090 */
091@NotMutable()
092@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
093public final class BatchedTransactionSpecificationRequestControl
094       extends Control
095{
096  /**
097   * The OID (1.3.6.1.4.1.30221.2.5.1) for the batched transaction specification
098   * request control.
099   */
100  public static final String BATCHED_TRANSACTION_SPECIFICATION_REQUEST_OID =
101       "1.3.6.1.4.1.30221.2.5.1";
102
103
104
105  /**
106   * The serial version UID for this serializable class.
107   */
108  private static final long serialVersionUID = -6817702055586260189L;
109
110
111
112  // The transaction ID for the associated transaction.
113  private final ASN1OctetString transactionID;
114
115
116
117  // This is an ugly hack to prevent checkstyle from complaining about the
118  // imports for classes only referenced in the javadoc.  Checkstyle apparently
119  // doesn't recognize that so we just need to use it in some way in this class
120  // to placate checkstyle.
121  static
122  {
123    final AssertionRequestControl assertionControl = null;
124    final ManageDsaITRequestControl manageDsaITControl = null;
125    final PreReadRequestControl preReadControl = null;
126    final PostReadRequestControl postReadControl = null;
127    final ProxiedAuthorizationV1RequestControl proxiedAuthV1Control = null;
128    final ProxiedAuthorizationV2RequestControl proxiedAuthV2Control = null;
129    final SubtreeDeleteRequestControl subtreeDeleteControl = null;
130    final StartBatchedTransactionExtendedRequest startBatchedTxnRequest = null;
131  }
132
133
134
135  /**
136   * Creates a new batched transaction specification request control with the
137   * provided transaction ID.
138   *
139   * @param  transactionID  The transaction ID for the associated transaction,
140   *                        as obtained from the start batched transaction
141   *                        extended operation.  It must not be {@code null}.
142   */
143  public BatchedTransactionSpecificationRequestControl(
144              final ASN1OctetString transactionID)
145  {
146    super(BATCHED_TRANSACTION_SPECIFICATION_REQUEST_OID, true,
147         new ASN1OctetString(transactionID.getValue()));
148
149    this.transactionID = transactionID;
150  }
151
152
153
154  /**
155   * Creates a new batched transaction specification request control which is
156   * decoded from the provided generic control.
157   *
158   * @param  control  The generic control to be decoded as a batched transaction
159   *                  specification request control.
160   *
161   * @throws  LDAPException  If the provided control cannot be decoded as a
162   *                         batched transaction specification request control.
163   */
164  public BatchedTransactionSpecificationRequestControl(final Control control)
165         throws LDAPException
166  {
167    super(control);
168
169    transactionID = control.getValue();
170    if (transactionID == null)
171    {
172      throw new LDAPException(ResultCode.DECODING_ERROR,
173                              ERR_TXN_REQUEST_CONTROL_NO_VALUE.get());
174    }
175  }
176
177
178
179  /**
180   * Retrieves the transaction ID for the associated transaction.
181   *
182   * @return  The transaction ID for the associated transaction.
183   */
184  public ASN1OctetString getTransactionID()
185  {
186    return transactionID;
187  }
188
189
190
191  /**
192   * {@inheritDoc}
193   */
194  @Override()
195  public String getControlName()
196  {
197    return INFO_CONTROL_NAME_BATCHED_TXN_REQUEST.get();
198  }
199
200
201
202  /**
203   * {@inheritDoc}
204   */
205  @Override()
206  public void toString(final StringBuilder buffer)
207  {
208    buffer.append("BatchedTransactionSpecificationRequestControl(" +
209                  "transactionID='");
210    buffer.append(transactionID.stringValue());
211    buffer.append("')");
212  }
213}