001    /*
002     * Copyright 2010-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2010-2016 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.experimental.
030                DraftBeheraLDAPPasswordPolicy10RequestControl;
031    import com.unboundid.ldap.sdk.extensions.StartTransactionExtendedRequest;
032    import com.unboundid.util.NotMutable;
033    import com.unboundid.util.ThreadSafety;
034    import com.unboundid.util.ThreadSafetyLevel;
035    
036    import static com.unboundid.ldap.sdk.controls.ControlMessages.*;
037    import 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)
077    public 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    }