001/*
002 * Copyright 2010-2017 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2010-2017 UnboundID Corp.
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;
035
036import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
037import static com.unboundid.util.Validator.*;
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 Alcatel-Lucent 8661 server products support
065 * the following additional UnboundID-specific controls in conjunction with
066 * 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  // This is an ugly hack to prevent checkstyle from complaining about the
100  // imports for classes only referenced in the javadoc.  Checkstyle apparently
101  // doesn't recognize that so we just need to use it in some way in this class
102  // to placate checkstyle.
103  static
104  {
105    final DraftBeheraLDAPPasswordPolicy10RequestControl pwPolicyControl = null;
106    final StartTransactionExtendedRequest r = null;
107  }
108
109
110
111  /**
112   * Creates a new transaction specification request control with the provided
113   * transaction ID.
114   *
115   * @param  transactionID  The transaction ID for the associated transaction,
116   *                        as obtained from the start transaction extended
117   *                        operation.  It must not be {@code null}.
118   */
119  public TransactionSpecificationRequestControl(
120              final ASN1OctetString transactionID)
121  {
122    super(TRANSACTION_SPECIFICATION_REQUEST_OID, true,
123         new ASN1OctetString(transactionID.getValue()));
124
125    ensureNotNull(transactionID);
126    this.transactionID = transactionID;
127  }
128
129
130
131  /**
132   * Creates a new transaction specification request control which is decoded
133   * from the provided generic control.
134   *
135   * @param  control  The generic control to be decoded as a transaction
136   *                  specification request control.
137   *
138   * @throws  LDAPException  If the provided control cannot be decoded as a
139   *                         transaction specification request control.
140   */
141  public TransactionSpecificationRequestControl(final Control control)
142         throws LDAPException
143  {
144    super(control);
145
146    transactionID = control.getValue();
147    if (transactionID == null)
148    {
149      throw new LDAPException(ResultCode.DECODING_ERROR,
150           ERR_TXN_REQUEST_CONTROL_NO_VALUE.get());
151    }
152  }
153
154
155
156  /**
157   * Retrieves the transaction ID for the associated transaction.
158   *
159   * @return  The transaction ID for the associated transaction.
160   */
161  public ASN1OctetString getTransactionID()
162  {
163    return transactionID;
164  }
165
166
167
168  /**
169   * {@inheritDoc}
170   */
171  @Override()
172  public String getControlName()
173  {
174    return INFO_CONTROL_NAME_TXN_SPECIFICATION_REQUEST.get();
175  }
176
177
178
179  /**
180   * {@inheritDoc}
181   */
182  @Override()
183  public void toString(final StringBuilder buffer)
184  {
185    buffer.append("TransactionSpecificationRequestControl(transactionID='");
186    buffer.append(transactionID.stringValue());
187    buffer.append("')");
188  }
189}