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 */
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 }