001/*
002 * Copyright 2010-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2010-2014 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.extensions.StartTransactionExtendedRequest;
030import com.unboundid.util.NotMutable;
031import com.unboundid.util.ThreadSafety;
032import com.unboundid.util.ThreadSafetyLevel;
033
034import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
035import static com.unboundid.util.Validator.*;
036
037
038
039/**
040 * This class provides an implementation of the transaction specification
041 * request control as defined in
042 * <A HREF="http://www.ietf.org/rfc/rfc5805.txt">RFC 5805</A>.  It may be used
043 * to indicate that the associated add, delete, modify, modify DN, or password
044 * modify operation is part of an LDAP transaction.  The transaction should be
045 * created with the start transaction extended operation, which will obtain a
046 * transaction ID, and the transaction may be committed or aborted using the end
047 * transaction extended operation.
048 * <BR><BR>
049 * See the documentation for the {@link StartTransactionExtendedRequest} class
050 * for an example of processing an LDAP transaction.
051 */
052@NotMutable()
053@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
054public final class TransactionSpecificationRequestControl
055       extends Control
056{
057  /**
058   * The OID (1.3.6.1.1.21.2) for the transaction specification request control.
059   */
060  public static final String TRANSACTION_SPECIFICATION_REQUEST_OID =
061       "1.3.6.1.1.21.2";
062
063
064
065  /**
066   * The serial version UID for this serializable class.
067   */
068  private static final long serialVersionUID = 6489819774149849092L;
069
070
071
072  // The transaction ID for the associated transaction.
073  private final ASN1OctetString transactionID;
074
075
076  // This is an ugly hack to prevent checkstyle from complaining about the
077  // import for the StartTransactionExtendedRequest class.  It is used
078  // by the @link element in the javadoc, but checkstyle apparently doesn't
079  // recognize that so we just need to use it in some way in this class to
080  // placate checkstyle.
081  static
082  {
083    final StartTransactionExtendedRequest r = null;
084  }
085
086
087
088  /**
089   * Creates a new transaction specification request control with the provided
090   * transaction ID.
091   *
092   * @param  transactionID  The transaction ID for the associated transaction,
093   *                        as obtained from the start transaction extended
094   *                        operation.  It must not be {@code null}.
095   */
096  public TransactionSpecificationRequestControl(
097              final ASN1OctetString transactionID)
098  {
099    super(TRANSACTION_SPECIFICATION_REQUEST_OID, true,
100         new ASN1OctetString(transactionID.getValue()));
101
102    ensureNotNull(transactionID);
103    this.transactionID = transactionID;
104  }
105
106
107
108  /**
109   * Creates a new transaction specification request control which is decoded
110   * from the provided generic control.
111   *
112   * @param  control  The generic control to be decoded as a transaction
113   *                  specification request control.
114   *
115   * @throws  LDAPException  If the provided control cannot be decoded as a
116   *                         transaction specification request control.
117   */
118  public TransactionSpecificationRequestControl(final Control control)
119         throws LDAPException
120  {
121    super(control);
122
123    transactionID = control.getValue();
124    if (transactionID == null)
125    {
126      throw new LDAPException(ResultCode.DECODING_ERROR,
127           ERR_TXN_REQUEST_CONTROL_NO_VALUE.get());
128    }
129  }
130
131
132
133  /**
134   * Retrieves the transaction ID for the associated transaction.
135   *
136   * @return  The transaction ID for the associated transaction.
137   */
138  public ASN1OctetString getTransactionID()
139  {
140    return transactionID;
141  }
142
143
144
145  /**
146   * {@inheritDoc}
147   */
148  @Override()
149  public String getControlName()
150  {
151    return INFO_CONTROL_NAME_TXN_SPECIFICATION_REQUEST.get();
152  }
153
154
155
156  /**
157   * {@inheritDoc}
158   */
159  @Override()
160  public void toString(final StringBuilder buffer)
161  {
162    buffer.append("TransactionSpecificationRequestControl(transactionID='");
163    buffer.append(transactionID.stringValue());
164    buffer.append("')");
165  }
166}