001/* 002 * Copyright 2007-2022 Ping Identity Corporation 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright 2007-2022 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) 2007-2022 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.ASN1Element; 041import com.unboundid.asn1.ASN1OctetString; 042import com.unboundid.asn1.ASN1Sequence; 043import com.unboundid.ldap.sdk.Control; 044import com.unboundid.ldap.sdk.LDAPException; 045import com.unboundid.ldap.sdk.ResultCode; 046import com.unboundid.util.Debug; 047import com.unboundid.util.NotMutable; 048import com.unboundid.util.NotNull; 049import com.unboundid.util.Nullable; 050import com.unboundid.util.StaticUtils; 051import com.unboundid.util.ThreadSafety; 052import com.unboundid.util.ThreadSafetyLevel; 053 054import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 055 056 057 058/** 059 * This class provides an implementation of the LDAP pre-read request control 060 * as defined in <A HREF="http://www.ietf.org/rfc/rfc4527.txt">RFC 4527</A>. It 061 * may be used to request that the server retrieve a copy of the target entry as 062 * it appeared immediately before processing a delete, modify, or modify DN 063 * operation. 064 * <BR><BR> 065 * If this control is included in a delete, modify, or modify DN request, then 066 * the corresponding response may include a {@link PreReadResponseControl} 067 * containing a version of the entry as it before after applying that change. 068 * Note that this response control will only be included if the operation was 069 * successful, so it will not be provided if the operation failed for some 070 * reason (e.g., if the change would have violated the server schema, or if the 071 * requester did not have sufficient permission to perform that operation). 072 * <BR><BR> 073 * The value of this control should contain a set of requested attributes to 074 * include in the entry that is returned. The server should treat this set of 075 * requested attributes exactly as it treats the requested attributes from a 076 * {@link com.unboundid.ldap.sdk.SearchRequest}. As is the case with a search 077 * request, if no attributes are specified, then all user attributes will be 078 * included. 079 * <BR><BR> 080 * The use of the LDAP pre-read request control is virtually identical to the 081 * use of the LDAP post-read request control. See the documentation for the 082 * {@link PostReadRequestControl} for an example that illustrates its use. 083 */ 084@NotMutable() 085@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 086public final class PreReadRequestControl 087 extends Control 088{ 089 /** 090 * The OID (1.3.6.1.1.13.1) for the pre-read request control. 091 */ 092 @NotNull public static final String PRE_READ_REQUEST_OID = "1.3.6.1.1.13.1"; 093 094 095 096 /** 097 * The set of requested attributes that will be used if none are provided. 098 */ 099 @NotNull private static final String[] NO_ATTRIBUTES = StaticUtils.NO_STRINGS; 100 101 102 103 /** 104 * The serial version UID for this serializable class. 105 */ 106 private static final long serialVersionUID = 1205235290978028739L; 107 108 109 110 // The set of requested attributes to retrieve from the target entry. 111 @NotNull private final String[] attributes; 112 113 114 115 /** 116 * Creates a new pre-read request control that will retrieve the specified set 117 * of attributes from the target entry. It will be marked critical. 118 * 119 * @param attributes The set of attributes to retrieve from the target 120 * entry. It behaves in the same way as the set of 121 * requested attributes for a search operation. If this 122 * is empty or {@code null}, then all user attributes 123 * will be returned. 124 */ 125 public PreReadRequestControl(@Nullable final String... attributes) 126 { 127 this(true, attributes); 128 } 129 130 131 132 /** 133 * Creates a new pre-read request control that will retrieve the specified set 134 * of attributes from the target entry. 135 * 136 * @param isCritical Indicates whether this control should be marked 137 * critical. 138 * @param attributes The set of attributes to retrieve from the target 139 * entry. It behaves in the same way as the set of 140 * requested attributes for a search operation. If this 141 * is empty or {@code null}, then all user attributes 142 * will be returned. 143 */ 144 public PreReadRequestControl(final boolean isCritical, 145 @Nullable final String... attributes) 146 { 147 super(PRE_READ_REQUEST_OID, isCritical, encodeValue(attributes)); 148 149 if (attributes == null) 150 { 151 this.attributes = NO_ATTRIBUTES; 152 } 153 else 154 { 155 this.attributes = attributes; 156 } 157 } 158 159 160 161 /** 162 * Creates a new pre-read request control which is decoded from the provided 163 * generic control. 164 * 165 * @param control The generic control to be decoded as a pre-read request 166 * control. 167 * 168 * @throws LDAPException If the provided control cannot be decoded as a 169 * pre-read request control. 170 */ 171 public PreReadRequestControl(@NotNull final Control control) 172 throws LDAPException 173 { 174 super(control); 175 176 final ASN1OctetString value = control.getValue(); 177 if (value == null) 178 { 179 throw new LDAPException(ResultCode.DECODING_ERROR, 180 ERR_PRE_READ_REQUEST_NO_VALUE.get()); 181 } 182 183 try 184 { 185 final ASN1Element valueElement = ASN1Element.decode(value.getValue()); 186 final ASN1Element[] attrElements = 187 ASN1Sequence.decodeAsSequence(valueElement).elements(); 188 attributes = new String[attrElements.length]; 189 for (int i=0; i < attrElements.length; i++) 190 { 191 attributes[i] = 192 ASN1OctetString.decodeAsOctetString(attrElements[i]).stringValue(); 193 } 194 } 195 catch (final Exception e) 196 { 197 Debug.debugException(e); 198 throw new LDAPException(ResultCode.DECODING_ERROR, 199 ERR_PRE_READ_REQUEST_CANNOT_DECODE.get(e), e); 200 } 201 } 202 203 204 205 /** 206 * Encodes the provided information into an octet string that can be used as 207 * the value for this control. 208 * 209 * @param attributes The set of attributes to retrieve from the target 210 * entry. It behaves in the same way as the set of 211 * requested attributes for a search operation. If this 212 * is empty or {@code null}, then all user attributes 213 * will be returned. 214 * 215 * @return An ASN.1 octet string that can be used as the value for this 216 * control. 217 */ 218 @NotNull() 219 private static ASN1OctetString encodeValue( 220 @Nullable final String[] attributes) 221 { 222 if ((attributes == null) || (attributes.length == 0)) 223 { 224 return new ASN1OctetString(new ASN1Sequence().encode()); 225 } 226 227 final ASN1OctetString[] elements = new ASN1OctetString[attributes.length]; 228 for (int i=0; i < attributes.length; i++) 229 { 230 elements[i] = new ASN1OctetString(attributes[i]); 231 } 232 233 return new ASN1OctetString(new ASN1Sequence(elements).encode()); 234 } 235 236 237 238 /** 239 * Retrieves the set of attributes that will be requested for inclusion in the 240 * entry returned in the response control. 241 * 242 * @return The set of attributes that will be requested for inclusion in the 243 * entry returned in the response control, or an empty array if all 244 * user attributes should be returned. 245 */ 246 @NotNull() 247 public String[] getAttributes() 248 { 249 return attributes; 250 } 251 252 253 254 /** 255 * {@inheritDoc} 256 */ 257 @Override() 258 @NotNull() 259 public String getControlName() 260 { 261 return INFO_CONTROL_NAME_PRE_READ_REQUEST.get(); 262 } 263 264 265 266 /** 267 * {@inheritDoc} 268 */ 269 @Override() 270 public void toString(@NotNull final StringBuilder buffer) 271 { 272 buffer.append("PreReadRequestControl(attributes={"); 273 for (int i=0; i < attributes.length; i++) 274 { 275 if (i > 0) 276 { 277 buffer.append(", "); 278 } 279 buffer.append('\''); 280 buffer.append(attributes[i]); 281 buffer.append('\''); 282 } 283 buffer.append("}, isCritical="); 284 buffer.append(isCritical()); 285 buffer.append(')'); 286 } 287}