001/* 002 * Copyright 2007-2014 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-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 java.util.ArrayList; 026import java.util.Collection; 027 028import com.unboundid.asn1.ASN1Element; 029import com.unboundid.asn1.ASN1Exception; 030import com.unboundid.asn1.ASN1OctetString; 031import com.unboundid.asn1.ASN1Sequence; 032import com.unboundid.ldap.sdk.Attribute; 033import com.unboundid.ldap.sdk.Control; 034import com.unboundid.ldap.sdk.DecodeableControl; 035import com.unboundid.ldap.sdk.LDAPException; 036import com.unboundid.ldap.sdk.LDAPResult; 037import com.unboundid.ldap.sdk.ReadOnlyEntry; 038import com.unboundid.ldap.sdk.ResultCode; 039import com.unboundid.util.NotMutable; 040import com.unboundid.util.ThreadSafety; 041import com.unboundid.util.ThreadSafetyLevel; 042 043import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 044import static com.unboundid.util.Debug.*; 045import static com.unboundid.util.Validator.*; 046 047 048 049/** 050 * This class provides an implementation of the LDAP post-read response control 051 * as defined in <A HREF="http://www.ietf.org/rfc/rfc4527.txt">RFC 4527</A>. It 052 * may be used to return a copy of the target entry immediately after processing 053 * an add, modify, or modify DN operation. 054 * <BR><BR> 055 * If the corresponding add, modify, or modify DN request included the 056 * {@link PostReadRequestControl} and the operation was successful, then the 057 * response for that operation should include the post-read response control 058 * with a read-only copy of the entry as it appeared immediately after 059 * processing the request. If the operation was not successful, then the 060 * post-read response control will not be returned. 061 */ 062@NotMutable() 063@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 064public final class PostReadResponseControl 065 extends Control 066 implements DecodeableControl 067{ 068 /** 069 * The OID (1.3.6.1.1.13.2) for the post-read response control. 070 */ 071 public static final String POST_READ_RESPONSE_OID = "1.3.6.1.1.13.2"; 072 073 074 075 /** 076 * The serial version UID for this serializable class. 077 */ 078 private static final long serialVersionUID = -6918729231330354924L; 079 080 081 082 // The entry returned in the response control. 083 private final ReadOnlyEntry entry; 084 085 086 087 /** 088 * Creates a new empty control instance that is intended to be used only for 089 * decoding controls via the {@code DecodeableControl} interface. 090 */ 091 PostReadResponseControl() 092 { 093 entry = null; 094 } 095 096 097 098 /** 099 * Creates a new post-read response control including the provided entry. 100 * 101 * @param entry The entry to include in this post-read response control. It 102 * must not be {@code null}. 103 */ 104 public PostReadResponseControl(final ReadOnlyEntry entry) 105 { 106 super(POST_READ_RESPONSE_OID, false, encodeValue(entry)); 107 108 this.entry = entry; 109 } 110 111 112 113 /** 114 * Creates a new post-read response control with the provided information. 115 * 116 * @param oid The OID for the control. 117 * @param isCritical Indicates whether the control should be marked 118 * critical. 119 * @param value The encoded value for the control. This may be 120 * {@code null} if no value was provided. 121 * 122 * @throws LDAPException If the provided control cannot be decoded as a 123 * post-read response control. 124 */ 125 public PostReadResponseControl(final String oid, final boolean isCritical, 126 final ASN1OctetString value) 127 throws LDAPException 128 { 129 super(oid, isCritical, value); 130 131 if (value == null) 132 { 133 throw new LDAPException(ResultCode.DECODING_ERROR, 134 ERR_POST_READ_RESPONSE_NO_VALUE.get()); 135 } 136 137 final ASN1Sequence entrySequence; 138 try 139 { 140 final ASN1Element entryElement = ASN1Element.decode(value.getValue()); 141 entrySequence = ASN1Sequence.decodeAsSequence(entryElement); 142 } 143 catch (final ASN1Exception ae) 144 { 145 debugException(ae); 146 throw new LDAPException(ResultCode.DECODING_ERROR, 147 ERR_POST_READ_RESPONSE_VALUE_NOT_SEQUENCE.get(ae), 148 ae); 149 } 150 151 final ASN1Element[] entryElements = entrySequence.elements(); 152 if (entryElements.length != 2) 153 { 154 throw new LDAPException(ResultCode.DECODING_ERROR, 155 ERR_POST_READ_RESPONSE_INVALID_ELEMENT_COUNT.get( 156 entryElements.length)); 157 } 158 159 final String dn = 160 ASN1OctetString.decodeAsOctetString(entryElements[0]).stringValue(); 161 162 final ASN1Sequence attrSequence; 163 try 164 { 165 attrSequence = ASN1Sequence.decodeAsSequence(entryElements[1]); 166 } 167 catch (final ASN1Exception ae) 168 { 169 debugException(ae); 170 throw new LDAPException(ResultCode.DECODING_ERROR, 171 ERR_POST_READ_RESPONSE_ATTRIBUTES_NOT_SEQUENCE.get(ae), 172 ae); 173 } 174 175 final ASN1Element[] attrElements = attrSequence.elements(); 176 final Attribute[] attrs = new Attribute[attrElements.length]; 177 for (int i=0; i < attrElements.length; i++) 178 { 179 try 180 { 181 attrs[i] = 182 Attribute.decode(ASN1Sequence.decodeAsSequence(attrElements[i])); 183 } 184 catch (final ASN1Exception ae) 185 { 186 debugException(ae); 187 throw new LDAPException(ResultCode.DECODING_ERROR, 188 ERR_POST_READ_RESPONSE_ATTR_NOT_SEQUENCE.get(ae), ae); 189 } 190 } 191 192 entry = new ReadOnlyEntry(dn, attrs); 193 } 194 195 196 197 /** 198 * {@inheritDoc} 199 */ 200 public PostReadResponseControl 201 decodeControl(final String oid, final boolean isCritical, 202 final ASN1OctetString value) 203 throws LDAPException 204 { 205 return new PostReadResponseControl(oid, isCritical, value); 206 } 207 208 209 210 /** 211 * Extracts a post-read response control from the provided result. 212 * 213 * @param result The result from which to retrieve the post-read response 214 * control. 215 * 216 * @return The post-read response control contained in the provided result, 217 * or {@code null} if the result did not contain a post-read response 218 * control. 219 * 220 * @throws LDAPException If a problem is encountered while attempting to 221 * decode the post-read response control contained in 222 * the provided result. 223 */ 224 public static PostReadResponseControl get(final LDAPResult result) 225 throws LDAPException 226 { 227 final Control c = result.getResponseControl(POST_READ_RESPONSE_OID); 228 if (c == null) 229 { 230 return null; 231 } 232 233 if (c instanceof PostReadResponseControl) 234 { 235 return (PostReadResponseControl) c; 236 } 237 else 238 { 239 return new PostReadResponseControl(c.getOID(), c.isCritical(), 240 c.getValue()); 241 } 242 } 243 244 245 246 /** 247 * Encodes the provided information into an octet string that can be used as 248 * the value for this control. 249 * 250 * @param entry The entry to include in this post-read response control. It 251 * must not be {@code null}. 252 * 253 * @return An ASN.1 octet string that can be used as the value for this 254 * control. 255 */ 256 private static ASN1OctetString encodeValue(final ReadOnlyEntry entry) 257 { 258 ensureNotNull(entry); 259 260 final Collection<Attribute> attrs = entry.getAttributes(); 261 final ArrayList<ASN1Element> attrElements = 262 new ArrayList<ASN1Element>(attrs.size()); 263 for (final Attribute a : attrs) 264 { 265 attrElements.add(a.encode()); 266 } 267 268 final ASN1Element[] entryElements = 269 { 270 new ASN1OctetString(entry.getDN()), 271 new ASN1Sequence(attrElements) 272 }; 273 274 return new ASN1OctetString(new ASN1Sequence(entryElements).encode()); 275 } 276 277 278 279 /** 280 * Retrieves a read-only copy of the entry returned by this post-read response 281 * control. 282 * 283 * @return A read-only copy of the entry returned by this post-read response 284 * control. 285 */ 286 public ReadOnlyEntry getEntry() 287 { 288 return entry; 289 } 290 291 292 293 /** 294 * {@inheritDoc} 295 */ 296 @Override() 297 public String getControlName() 298 { 299 return INFO_CONTROL_NAME_POST_READ_RESPONSE.get(); 300 } 301 302 303 304 /** 305 * {@inheritDoc} 306 */ 307 @Override() 308 public void toString(final StringBuilder buffer) 309 { 310 buffer.append("PostReadResponseControl(entry="); 311 entry.toString(buffer); 312 buffer.append(", isCritical="); 313 buffer.append(isCritical()); 314 buffer.append(')'); 315 } 316}