001/* 002 * Copyright 2007-2018 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2018 Ping Identity Corporation 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 @Override() 201 public PostReadResponseControl 202 decodeControl(final String oid, final boolean isCritical, 203 final ASN1OctetString value) 204 throws LDAPException 205 { 206 return new PostReadResponseControl(oid, isCritical, value); 207 } 208 209 210 211 /** 212 * Extracts a post-read response control from the provided result. 213 * 214 * @param result The result from which to retrieve the post-read response 215 * control. 216 * 217 * @return The post-read response control contained in the provided result, 218 * or {@code null} if the result did not contain a post-read response 219 * control. 220 * 221 * @throws LDAPException If a problem is encountered while attempting to 222 * decode the post-read response control contained in 223 * the provided result. 224 */ 225 public static PostReadResponseControl get(final LDAPResult result) 226 throws LDAPException 227 { 228 final Control c = result.getResponseControl(POST_READ_RESPONSE_OID); 229 if (c == null) 230 { 231 return null; 232 } 233 234 if (c instanceof PostReadResponseControl) 235 { 236 return (PostReadResponseControl) c; 237 } 238 else 239 { 240 return new PostReadResponseControl(c.getOID(), c.isCritical(), 241 c.getValue()); 242 } 243 } 244 245 246 247 /** 248 * Encodes the provided information into an octet string that can be used as 249 * the value for this control. 250 * 251 * @param entry The entry to include in this post-read response control. It 252 * must not be {@code null}. 253 * 254 * @return An ASN.1 octet string that can be used as the value for this 255 * control. 256 */ 257 private static ASN1OctetString encodeValue(final ReadOnlyEntry entry) 258 { 259 ensureNotNull(entry); 260 261 final Collection<Attribute> attrs = entry.getAttributes(); 262 final ArrayList<ASN1Element> attrElements = 263 new ArrayList<ASN1Element>(attrs.size()); 264 for (final Attribute a : attrs) 265 { 266 attrElements.add(a.encode()); 267 } 268 269 final ASN1Element[] entryElements = 270 { 271 new ASN1OctetString(entry.getDN()), 272 new ASN1Sequence(attrElements) 273 }; 274 275 return new ASN1OctetString(new ASN1Sequence(entryElements).encode()); 276 } 277 278 279 280 /** 281 * Retrieves a read-only copy of the entry returned by this post-read response 282 * control. 283 * 284 * @return A read-only copy of the entry returned by this post-read response 285 * control. 286 */ 287 public ReadOnlyEntry getEntry() 288 { 289 return entry; 290 } 291 292 293 294 /** 295 * {@inheritDoc} 296 */ 297 @Override() 298 public String getControlName() 299 { 300 return INFO_CONTROL_NAME_POST_READ_RESPONSE.get(); 301 } 302 303 304 305 /** 306 * {@inheritDoc} 307 */ 308 @Override() 309 public void toString(final StringBuilder buffer) 310 { 311 buffer.append("PostReadResponseControl(entry="); 312 entry.toString(buffer); 313 buffer.append(", isCritical="); 314 buffer.append(isCritical()); 315 buffer.append(')'); 316 } 317}