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 */ 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.extensions.StartTransactionExtendedRequest; 030import com.unboundid.util.NotMutable; 031import com.unboundid.util.ThreadSafety; 032import com.unboundid.util.ThreadSafetyLevel; 033 034import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 035import 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) 054public 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}