001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * https://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.directory.api.ldap.model.message; 021 022 023import java.util.Collection; 024 025import org.apache.directory.api.ldap.model.entry.Attribute; 026import org.apache.directory.api.ldap.model.entry.Modification; 027import org.apache.directory.api.ldap.model.entry.ModificationOperation; 028import org.apache.directory.api.ldap.model.name.Dn; 029 030 031/** 032 * Modify request protocol message used to alter the attributes and values of an 033 * existing entry. Here's what <a href="https://www.ietf.org/rfc/rfc2255.txt">RFC 2255</a> says about it: 034 * 035 * <pre> 036 * 4.6. Modify Operation 037 * 038 * The Modify Operation allows a client to request that a modification 039 * of an entry be performed on its behalf by a server. The Modify 040 * Request is defined as follows: 041 * 042 * ModifyRequest ::= [APPLICATION 6] SEQUENCE { 043 * object LDAPDN, 044 * modification SEQUENCE OF SEQUENCE { 045 * 046 * operation ENUMERATED { 047 * add (0), 048 * delete (1), 049 * replace (2), 050 * ... }, 051 * modification AttributeTypeAndValues } } 052 * 053 * AttributeTypeAndValues ::= SEQUENCE { 054 * type AttributeDescription, 055 * vals SET OF AttributeValue } 056 * 057 * Parameters of the Modify Request are: 058 * 059 * - object: The object to be modified. The value of this field contains 060 * the Dn of the entry to be modified. The server will not perform 061 * any alias dereferencing in determining the object to be modified. 062 * 063 * - modification: A list of modifications to be performed on the entry. 064 * The entire list of entry modifications MUST be performed 065 * in the order they are listed, as a single atomic operation. While 066 * individual modifications may violate the directory schema, the 067 * resulting entry after the entire list of modifications is performed 068 * MUST conform to the requirements of the directory schema. The 069 * values that may be taken on by the 'operation' field in each 070 * modification construct have the following semantics respectively: 071 * 072 * 073 * add: add values listed to the given attribute, creating 074 * the attribute if necessary; 075 * 076 * delete: delete values listed from the given attribute, 077 * removing the entire attribute if no values are listed, or 078 * if all current values of the attribute are listed for 079 * deletion; 080 * 081 * replace: replace all existing values of the given attribute 082 * with the new values listed, creating the attribute if it 083 * did not already exist. A replace with no value will delete 084 * the entire attribute if it exists, and is ignored if the 085 * attribute does not exist. 086 * </pre> 087 * 088 * Notice that we tried to leverage as much as we already can from the JNDI. 089 * Both the Names and ModificationItems are used here to make the API as easy 090 * as possible to understand. We do not attempt here to write a JNDI provider 091 * which losses the explicit request type usage that we are looking for. Also 092 * note that this library is both for the client side as well as the server side 093 * unlike the JNDI which is strictly for the client side. From the JNDI we 094 * borrow good ideas and familiar signatures, interfaces and classes where we 095 * can. 096 * 097 * RFC 4525 suggest to add an operation in the enumeration: 098 * 099 * <pre> 100 * ModifyRequest ::= [APPLICATION 6] SEQUENCE { 101 * object LDAPDN, 102 * modification SEQUENCE OF SEQUENCE { 103 * 104 * operation ENUMERATED { 105 * add (0), 106 * delete (1), 107 * replace (2), 108 * increment (3), 109 * ... }, 110 * </pre> 111 * 112 * 113 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 114 * 115 */ 116public interface ModifyRequest extends SingleReplyRequest, AbandonableRequest 117{ 118 /** 119 * Gets the distinguished name of the entry to be modified by this request. 120 * This property represents the PDU's <b>object</b> field. 121 * 122 * @return the Dn of the modified entry. 123 */ 124 Dn getName(); 125 126 127 /** 128 * Sets the distinguished name of the entry to be modified by this request. 129 * This property represents the PDU's <b>object</b> field. 130 * 131 * @param name the Dn of the modified entry. 132 * @return The ModifyRequest instance 133 */ 134 ModifyRequest setName( Dn name ); 135 136 137 /** 138 * Gets an immutable Collection of modification items representing the 139 * atomic changes to perform on the candidate entry to modify. 140 * 141 * @return an immutable Collection of Modification instances. 142 */ 143 Collection<Modification> getModifications(); 144 145 146 /** 147 * Adds a ModificationItem to the set of modifications composing this modify 148 * request. 149 * 150 * @param mod a Modification to add. 151 * @return The ModifyRequest instance 152 */ 153 ModifyRequest addModification( Modification mod ); 154 155 156 /** 157 * Removes a ModificationItem to the set of modifications composing this 158 * modify request. 159 * 160 * @param mod a Modification to remove. 161 * @return The ModifyRequest instance 162 */ 163 ModifyRequest removeModification( Modification mod ); 164 165 166 /** 167 * 168 * marks a given attribute for removal with the given 169 * values from the target entry. 170 * 171 * @param attributeName name of the attribute to be removed 172 * @param attributeValue values of the attribute 173 * @return The ModifyRequest instance 174 */ 175 ModifyRequest remove( String attributeName, String... attributeValue ); 176 177 178 /** 179 * @see #remove(String, String...) 180 * 181 * @param attributeName name of the attribute to be added 182 * @param attributeValue values of the attribute 183 * @return The ModifyRequest instance 184 */ 185 ModifyRequest remove( String attributeName, byte[]... attributeValue ); 186 187 188 /** 189 * 190 * marks a given attribute for removal from the target entry. 191 * 192 * @param attr the attribute to be removed 193 * @return The ModifyRequest instance 194 */ 195 ModifyRequest remove( Attribute attr ); 196 197 198 /** 199 * 200 * marks a given attribute name for removal from the target entry. 201 * 202 * @param attributeName the attribute to be removed 203 * @return The ModifyRequest instance 204 */ 205 ModifyRequest remove( String attributeName ); 206 207 208 /** 209 * Add a modification 210 * @param attr The attribute to be modified 211 * @param modOp The operation 212 * @return The ModifyRequest instance 213 */ 214 ModifyRequest addModification( Attribute attr, ModificationOperation modOp ); 215 216 217 /** 218 * marks a given attribute for addition in the target entry with the 219 * given values. 220 * 221 * @param attributeName name of the attribute to be added 222 * @param attributeValue values of the attribute 223 * @return The ModifyRequest instance 224 */ 225 ModifyRequest add( String attributeName, String... attributeValue ); 226 227 228 /** 229 * @see #add(String, String...) 230 * 231 * @param attributeName name of the attribute to be added 232 * @param attributeValue values of the attribute 233 * @return The ModifyRequest instance 234 */ 235 ModifyRequest add( String attributeName, byte[]... attributeValue ); 236 237 238 /** 239 * marks a given attribute for addition in the target entry. 240 * 241 * @param attr the attribute to be added 242 * @return The ModifyRequest instance 243 */ 244 ModifyRequest add( Attribute attr ); 245 246 247 /** 248 * @see #replace(String, String...) 249 * 250 * @param attributeName name of the attribute to be added 251 * @return The ModifyRequest instance 252 */ 253 ModifyRequest replace( String attributeName ); 254 255 256 /** 257 * marks a given attribute for replacement with the given 258 * values in the target entry. 259 * 260 * @param attributeName name of the attribute to be added 261 * @param attributeValue values of the attribute 262 * @return The ModifyRequest instance 263 */ 264 ModifyRequest replace( String attributeName, String... attributeValue ); 265 266 267 /** 268 * @see #replace(String, String...) 269 * 270 * @param attributeName name of the attribute to be added 271 * @param attributeValue values of the attribute 272 * @return The ModifyRequest instance 273 */ 274 ModifyRequest replace( String attributeName, byte[]... attributeValue ); 275 276 277 /** 278 * marks a given attribute for replacement in the target entry. 279 * 280 * @param attr the attribute to be added 281 * @return The ModifyRequest instance 282 */ 283 ModifyRequest replace( Attribute attr ); 284 285 286 /** 287 * marks a given attribute for increment by 1 in the target entry. 288 * 289 * @param attributeName the attribute to be incremented 290 * @return The ModifyRequest instance 291 */ 292 ModifyRequest increment( String attributeName ); 293 294 295 /** 296 * marks a given attribute for increment in the target entry. 297 * 298 * @param attributeName the attribute to be incremented 299 * @param increment The increment value (>=1) 300 * @return The ModifyRequest instance 301 */ 302 ModifyRequest increment( String attributeName, int increment ); 303 304 305 /** 306 * marks a given attribute for increment by 1 in the target entry. 307 * 308 * @param attr the attribute to be incremented 309 * @return The ModifyRequest instance 310 */ 311 ModifyRequest increment( Attribute attr ); 312 313 314 /** 315 * marks a given attribute for increment in the target entry. 316 * 317 * @param attr the attribute to be incremented 318 * @param increment The increment value (>=1) 319 * @return The ModifyRequest instance 320 */ 321 ModifyRequest increment( Attribute attr, int increment ); 322 323 324 /** 325 * {@inheritDoc} 326 */ 327 @Override 328 ModifyRequest setMessageId( int messageId ); 329 330 331 /** 332 * {@inheritDoc} 333 */ 334 @Override 335 ModifyRequest addControl( Control control ); 336 337 338 /** 339 * {@inheritDoc} 340 */ 341 @Override 342 ModifyRequest addAllControls( Control[] controls ); 343 344 345 /** 346 * {@inheritDoc} 347 */ 348 @Override 349 ModifyRequest removeControl( Control control ); 350}