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