001/* 002 * Copyright 2010-2020 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2010-2020 Ping Identity Corporation 007 * 008 * Licensed under the Apache License, Version 2.0 (the "License"); 009 * you may not use this file except in compliance with the License. 010 * You may obtain a copy of the License at 011 * 012 * http://www.apache.org/licenses/LICENSE-2.0 013 * 014 * Unless required by applicable law or agreed to in writing, software 015 * distributed under the License is distributed on an "AS IS" BASIS, 016 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 017 * See the License for the specific language governing permissions and 018 * limitations under the License. 019 */ 020/* 021 * Copyright (C) 2010-2020 Ping Identity Corporation 022 * 023 * This program is free software; you can redistribute it and/or modify 024 * it under the terms of the GNU General Public License (GPLv2 only) 025 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 026 * as published by the Free Software Foundation. 027 * 028 * This program is distributed in the hope that it will be useful, 029 * but WITHOUT ANY WARRANTY; without even the implied warranty of 030 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 031 * GNU General Public License for more details. 032 * 033 * You should have received a copy of the GNU General Public License 034 * along with this program; if not, see <http://www.gnu.org/licenses>. 035 */ 036package com.unboundid.ldap.sdk.controls; 037 038 039 040import com.unboundid.asn1.ASN1OctetString; 041import com.unboundid.ldap.sdk.Control; 042import com.unboundid.ldap.sdk.LDAPException; 043import com.unboundid.ldap.sdk.ResultCode; 044import com.unboundid.ldap.sdk.experimental. 045 DraftBeheraLDAPPasswordPolicy10RequestControl; 046import com.unboundid.ldap.sdk.extensions.StartTransactionExtendedRequest; 047import com.unboundid.util.NotMutable; 048import com.unboundid.util.ThreadSafety; 049import com.unboundid.util.ThreadSafetyLevel; 050import com.unboundid.util.Validator; 051 052import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 053 054 055 056/** 057 * This class provides an implementation of the transaction specification 058 * request control as defined in 059 * <A HREF="http://www.ietf.org/rfc/rfc5805.txt">RFC 5805</A>. It may be used 060 * to indicate that the associated add, delete, modify, modify DN, or password 061 * modify operation is part of an LDAP transaction. The transaction should be 062 * created with the start transaction extended operation, which will obtain a 063 * transaction ID, and the transaction may be committed or aborted using the end 064 * transaction extended operation. 065 * <BR><BR> 066 * Note that directory servers may limit the set of controls that are available 067 * for use in requests that are part of a transaction. RFC 5805 section 4 068 * indicates that the following controls may be used in conjunction with the 069 * transaction specification request control: {@link AssertionRequestControl}, 070 * {@link ManageDsaITRequestControl}, {@link PreReadRequestControl}, and 071 * {@link PostReadRequestControl}. The 072 * {@link ProxiedAuthorizationV1RequestControl} and 073 * {@link ProxiedAuthorizationV2RequestControl} controls cannot be included in 074 * requests that are part of a transaction, but you can include them in the 075 * {@link StartTransactionExtendedRequest} to indicate that all operations 076 * within the transaction should be processed with the specified authorization 077 * identity. 078 * <BR><BR> 079 * The Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products 080 * support the following additional UnboundID-specific controls in conjunction 081 * with operations included in a transaction: account usable request control, 082 * {@link DraftBeheraLDAPPasswordPolicy10RequestControl}, hard delete request 083 * control, intermediate client request control, replication repair request 084 * control, soft delete request control, soft deleted entry access request 085 * control, {@link SubtreeDeleteRequestControl}, and undelete request control. 086 * <BR><BR> 087 * See the documentation for the {@link StartTransactionExtendedRequest} class 088 * for an example of processing an LDAP transaction. 089 */ 090@NotMutable() 091@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 092public final class TransactionSpecificationRequestControl 093 extends Control 094{ 095 /** 096 * The OID (1.3.6.1.1.21.2) for the transaction specification request control. 097 */ 098 public static final String TRANSACTION_SPECIFICATION_REQUEST_OID = 099 "1.3.6.1.1.21.2"; 100 101 102 103 /** 104 * The serial version UID for this serializable class. 105 */ 106 private static final long serialVersionUID = 6489819774149849092L; 107 108 109 110 // The transaction ID for the associated transaction. 111 private final ASN1OctetString transactionID; 112 113 114 115 /** 116 * Creates a new transaction specification request control with the provided 117 * transaction ID. 118 * 119 * @param transactionID The transaction ID for the associated transaction, 120 * as obtained from the start transaction extended 121 * operation. It must not be {@code null}. 122 */ 123 public TransactionSpecificationRequestControl( 124 final ASN1OctetString transactionID) 125 { 126 super(TRANSACTION_SPECIFICATION_REQUEST_OID, true, 127 new ASN1OctetString(transactionID.getValue())); 128 129 Validator.ensureNotNull(transactionID); 130 this.transactionID = transactionID; 131 } 132 133 134 135 /** 136 * Creates a new transaction specification request control which is decoded 137 * from the provided generic control. 138 * 139 * @param control The generic control to be decoded as a transaction 140 * specification request control. 141 * 142 * @throws LDAPException If the provided control cannot be decoded as a 143 * transaction specification request control. 144 */ 145 public TransactionSpecificationRequestControl(final Control control) 146 throws LDAPException 147 { 148 super(control); 149 150 transactionID = control.getValue(); 151 if (transactionID == null) 152 { 153 throw new LDAPException(ResultCode.DECODING_ERROR, 154 ERR_TXN_REQUEST_CONTROL_NO_VALUE.get()); 155 } 156 } 157 158 159 160 /** 161 * Retrieves the transaction ID for the associated transaction. 162 * 163 * @return The transaction ID for the associated transaction. 164 */ 165 public ASN1OctetString getTransactionID() 166 { 167 return transactionID; 168 } 169 170 171 172 /** 173 * {@inheritDoc} 174 */ 175 @Override() 176 public String getControlName() 177 { 178 return INFO_CONTROL_NAME_TXN_SPECIFICATION_REQUEST.get(); 179 } 180 181 182 183 /** 184 * {@inheritDoc} 185 */ 186 @Override() 187 public void toString(final StringBuilder buffer) 188 { 189 buffer.append("TransactionSpecificationRequestControl(transactionID='"); 190 buffer.append(transactionID.stringValue()); 191 buffer.append("')"); 192 } 193}