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 * http://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 * modification AttributeTypeAndValues } } 051 * 052 * AttributeTypeAndValues ::= SEQUENCE { 053 * type AttributeDescription, 054 * vals SET OF AttributeValue } 055 * 056 * Parameters of the Modify Request are: 057 * 058 * - object: The object to be modified. The value of this field contains 059 * the Dn of the entry to be modified. The server will not perform 060 * any alias dereferencing in determining the object to be modified. 061 * 062 * - modification: A list of modifications to be performed on the entry. 063 * The entire list of entry modifications MUST be performed 064 * in the order they are listed, as a single atomic operation. While 065 * individual modifications may violate the directory schema, the 066 * resulting entry after the entire list of modifications is performed 067 * MUST conform to the requirements of the directory schema. The 068 * values that may be taken on by the 'operation' field in each 069 * modification construct have the following semantics respectively: 070 * 071 * 072 * add: add values listed to the given attribute, creating 073 * the attribute if necessary; 074 * 075 * delete: delete values listed from the given attribute, 076 * removing the entire attribute if no values are listed, or 077 * if all current values of the attribute are listed for 078 * deletion; 079 * 080 * replace: replace all existing values of the given attribute 081 * with the new values listed, creating the attribute if it 082 * did not already exist. A replace with no value will delete 083 * the entire attribute if it exists, and is ignored if the 084 * attribute does not exist. 085 * </pre> 086 * 087 * Notice that we tried to leverage as much as we already can from the JNDI. 088 * Both the Names and ModificationItems are used here to make the API as easy 089 * as possible to understand. We do not attempt here to write a JNDI provider 090 * which losses the explicit request type usage that we are looking for. Also 091 * note that this library is both for the client side as well as the server side 092 * unlike the JNDI which is strictly for the client side. From the JNDI we 093 * borrow good ideas and familiar signatures, interfaces and classes where we 094 * can. 095 * 096 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 097 * 098 */ 099public 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 removed 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 * @param attributeName name of the attribute to be added 165 * @param attributeValue values of the attribute 166 * @return The ModifyRequest instance 167 */ 168 ModifyRequest remove( String attributeName, byte[]... attributeValue ); 169 170 171 /** 172 * 173 * marks a given attribute for removal from the target entry. 174 * 175 * @param attr the attribute to be removed 176 * @return The ModifyRequest instance 177 */ 178 ModifyRequest remove( Attribute attr ); 179 180 181 /** 182 * 183 * marks a given attribute name for removal from the target entry. 184 * 185 * @param attributeName the attribute to be removed 186 * @return The ModifyRequest instance 187 */ 188 ModifyRequest remove( String attributeName ); 189 190 191 /** 192 * Add a modification 193 * @param attr The attribute to be modified 194 * @param modOp The operation 195 * @return The ModifyRequest instance 196 */ 197 ModifyRequest addModification( Attribute attr, ModificationOperation modOp ); 198 199 200 /** 201 * marks a given attribute for addition in the target entry with the 202 * given values. 203 * 204 * @param attributeName name of the attribute to be added 205 * @param attributeValue values of the attribute 206 * @return The ModifyRequest instance 207 */ 208 ModifyRequest add( String attributeName, String... attributeValue ); 209 210 211 /** 212 * @see #add(String, String...) 213 * 214 * @param attributeName name of the attribute to be added 215 * @param attributeValue values of the attribute 216 * @return The ModifyRequest instance 217 */ 218 ModifyRequest add( String attributeName, byte[]... attributeValue ); 219 220 221 /** 222 * marks a given attribute for addition in the target entry. 223 * 224 * @param attr the attribute to be added 225 * @return The ModifyRequest instance 226 */ 227 ModifyRequest add( Attribute attr ); 228 229 230 /** 231 * @see #replace(String, String...) 232 * 233 * @param attributeName name of the attribute to be added 234 * @return The ModifyRequest instance 235 */ 236 ModifyRequest replace( String attributeName ); 237 238 239 /** 240 * marks a given attribute for replacement with the given 241 * values in the target entry. 242 * 243 * @param attributeName name of the attribute to be added 244 * @param attributeValue values of the attribute 245 * @return The ModifyRequest instance 246 */ 247 ModifyRequest replace( String attributeName, String... attributeValue ); 248 249 250 /** 251 * @see #replace(String, String...) 252 * 253 * @param attributeName name of the attribute to be added 254 * @param attributeValue values of the attribute 255 * @return The ModifyRequest instance 256 */ 257 ModifyRequest replace( String attributeName, byte[]... attributeValue ); 258 259 260 /** 261 * marks a given attribute for replacement in the target entry. 262 * 263 * @param attr the attribute to be added 264 * @return The ModifyRequest instance 265 */ 266 ModifyRequest replace( Attribute attr ); 267 268 269 /** 270 * {@inheritDoc} 271 */ 272 @Override 273 ModifyRequest setMessageId( int messageId ); 274 275 276 /** 277 * {@inheritDoc} 278 */ 279 @Override 280 ModifyRequest addControl( Control control ); 281 282 283 /** 284 * {@inheritDoc} 285 */ 286 @Override 287 ModifyRequest addAllControls( Control[] controls ); 288 289 290 /** 291 * {@inheritDoc} 292 */ 293 @Override 294 ModifyRequest removeControl( Control control ); 295}