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 }