1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 * 19 */ 20 package org.apache.directory.api.ldap.model.message; 21 22 23 import java.util.Collection; 24 25 import org.apache.directory.api.ldap.model.entry.Attribute; 26 import org.apache.directory.api.ldap.model.entry.Modification; 27 import org.apache.directory.api.ldap.model.entry.ModificationOperation; 28 import org.apache.directory.api.ldap.model.name.Dn; 29 30 31 /** 32 * Modify request protocol message used to alter the attributes and values of an 33 * existing entry. Here's what <a href="">RFC 2255</a> says about it: 34 * 35 * <pre> 36 * 4.6. Modify Operation 37 * 38 * The Modify Operation allows a client to request that a modification 39 * of an entry be performed on its behalf by a server. The Modify 40 * Request is defined as follows: 41 * 42 * ModifyRequest ::= [APPLICATION 6] SEQUENCE { 43 * object LDAPDN, 44 * modification SEQUENCE OF SEQUENCE { 45 * 46 * operation ENUMERATED { 47 * add (0), 48 * delete (1), 49 * replace (2) }, 50 * modification AttributeTypeAndValues } } 51 * 52 * AttributeTypeAndValues ::= SEQUENCE { 53 * type AttributeDescription, 54 * vals SET OF AttributeValue } 55 * 56 * Parameters of the Modify Request are: 57 * 58 * - object: The object to be modified. The value of this field contains 59 * the Dn of the entry to be modified. The server will not perform 60 * any alias dereferencing in determining the object to be modified. 61 * 62 * - modification: A list of modifications to be performed on the entry. 63 * The entire list of entry modifications MUST be performed 64 * in the order they are listed, as a single atomic operation. While 65 * individual modifications may violate the directory schema, the 66 * resulting entry after the entire list of modifications is performed 67 * MUST conform to the requirements of the directory schema. The 68 * values that may be taken on by the 'operation' field in each 69 * modification construct have the following semantics respectively: 70 * 71 * 72 * add: add values listed to the given attribute, creating 73 * the attribute if necessary; 74 * 75 * delete: delete values listed from the given attribute, 76 * removing the entire attribute if no values are listed, or 77 * if all current values of the attribute are listed for 78 * deletion; 79 * 80 * replace: replace all existing values of the given attribute 81 * with the new values listed, creating the attribute if it 82 * did not already exist. A replace with no value will delete 83 * the entire attribute if it exists, and is ignored if the 84 * attribute does not exist. 85 * </pre> 86 * 87 * Notice that we tried to leverage as much as we already can from the JNDI. 88 * Both the Names and ModificationItems are used here to make the API as easy 89 * as possible to understand. We do not attempt here to write a JNDI provider 90 * which losses the explicit request type usage that we are looking for. Also 91 * note that this library is both for the client side as well as the server side 92 * unlike the JNDI which is strictly for the client side. From the JNDI we 93 * borrow good ideas and familiar signatures, interfaces and classes where we 94 * can. 95 * 96 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 97 * 98 */ 99 public interface ModifyRequest extends SingleReplyRequest, AbandonableRequest 100 { 101 /** 102 * Gets the distinguished name of the entry to be modified by this request. 103 * This property represents the PDU's <b>object</b> field. 104 * 105 * @return the Dn of the modified entry. 106 */ 107 Dn getName(); 108 109 110 /** 111 * Sets the distinguished name of the entry to be modified by this request. 112 * This property represents the PDU's <b>object</b> field. 113 * 114 * @param name the Dn of the modified entry. 115 * @return The ModifyRequest instance 116 */ 117 ModifyRequest setName( Dn name ); 118 119 120 /** 121 * Gets an immutable Collection of modification items representing the 122 * atomic changes to perform on the candidate entry to modify. 123 * 124 * @return an immutable Collection of Modification instances. 125 */ 126 Collection<Modification> getModifications(); 127 128 129 /** 130 * Adds a ModificationItem to the set of modifications composing this modify 131 * request. 132 * 133 * @param mod a Modification to add. 134 * @return The ModifyRequest instance 135 */ 136 ModifyRequest addModification( Modification mod ); 137 138 139 /** 140 * Removes a ModificationItem to the set of modifications composing this 141 * modify request. 142 * 143 * @param mod a Modification to remove. 144 * @return The ModifyRequest instance 145 */ 146 ModifyRequest removeModification( Modification mod ); 147 148 149 /** 150 * 151 * marks a given attribute for removal with the given 152 * values from the target entry. 153 * 154 * @param attributeName name of the attribute to be added 155 * @param attributeValue values of the attribute 156 * @return The ModifyRequest instance 157 */ 158 ModifyRequest remove( String attributeName, String... attributeValue ); 159 160 161 /** 162 * @see #remove(String, String...) 163 */ 164 ModifyRequest remove( String attributeName, byte[]... attributeValue ); 165 166 167 /** 168 * 169 * marks a given attribute for removal from the target entry. 170 * 171 * @param attr the attribute to be added 172 * @return The ModifyRequest instance 173 */ 174 ModifyRequest remove( Attribute attr ); 175 176 177 /** 178 * Add a modification 179 * @param attr The attribute to be modified 180 * @param modOp The operation 181 * @return The ModifyRequest instance 182 */ 183 ModifyRequest addModification( Attribute attr, ModificationOperation modOp ); 184 185 186 /** 187 * marks a given attribute for addition in the target entry with the 188 * given values. 189 * 190 * @param attributeName name of the attribute to be added 191 * @param attributeValue values of the attribute 192 * @return The ModifyRequest instance 193 */ 194 ModifyRequest add( String attributeName, String... attributeValue ); 195 196 197 /** 198 * @see #add(String, String...) 199 */ 200 ModifyRequest add( String attributeName, byte[]... attributeValue ); 201 202 203 /** 204 * marks a given attribute for addition in the target entry. 205 * 206 * @param attr the attribute to be added 207 * @return The ModifyRequest instance 208 */ 209 ModifyRequest add( Attribute attr ); 210 211 212 /** 213 * @see #replace(String, String...) 214 */ 215 ModifyRequest replace( String attributeName ); 216 217 218 /** 219 * marks a given attribute for replacement with the given 220 * values in the target entry. 221 * 222 * @param attributeName name of the attribute to be added 223 * @param attributeValue values of the attribute 224 * @return The ModifyRequest instance 225 */ 226 ModifyRequest replace( String attributeName, String... attributeValue ); 227 228 229 /** 230 * @see #replace(String, String...) 231 */ 232 ModifyRequest replace( String attributeName, byte[]... attributeValue ); 233 234 235 /** 236 * marks a given attribute for replacement in the target entry. 237 * 238 * @param attr the attribute to be added 239 * @return The ModifyRequest instance 240 */ 241 ModifyRequest replace( Attribute attr ); 242 243 244 /** 245 * {@inheritDoc} 246 */ 247 ModifyRequest setMessageId( int messageId ); 248 249 250 /** 251 * {@inheritDoc} 252 */ 253 ModifyRequest addControl( Control control ); 254 255 256 /** 257 * {@inheritDoc} 258 */ 259 ModifyRequest addAllControls( Control[] controls ); 260 261 262 /** 263 * {@inheritDoc} 264 */ 265 ModifyRequest removeControl( Control control ); 266 }