001    /*
002     * Copyright 2010-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2010-2015 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     */
021    package com.unboundid.ldap.sdk.controls;
022    
023    
024    
025    import com.unboundid.asn1.ASN1OctetString;
026    import com.unboundid.ldap.sdk.Control;
027    import com.unboundid.ldap.sdk.LDAPException;
028    import com.unboundid.ldap.sdk.ResultCode;
029    import com.unboundid.ldap.sdk.extensions.StartTransactionExtendedRequest;
030    import com.unboundid.util.NotMutable;
031    import com.unboundid.util.ThreadSafety;
032    import com.unboundid.util.ThreadSafetyLevel;
033    
034    import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
035    import 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)
054    public 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    }