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 * https://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="https://www.ietf.org/rfc/rfc2255.txt">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 * ... },
51 * modification AttributeTypeAndValues } }
52 *
53 * AttributeTypeAndValues ::= SEQUENCE {
54 * type AttributeDescription,
55 * vals SET OF AttributeValue }
56 *
57 * Parameters of the Modify Request are:
58 *
59 * - object: The object to be modified. The value of this field contains
60 * the Dn of the entry to be modified. The server will not perform
61 * any alias dereferencing in determining the object to be modified.
62 *
63 * - modification: A list of modifications to be performed on the entry.
64 * The entire list of entry modifications MUST be performed
65 * in the order they are listed, as a single atomic operation. While
66 * individual modifications may violate the directory schema, the
67 * resulting entry after the entire list of modifications is performed
68 * MUST conform to the requirements of the directory schema. The
69 * values that may be taken on by the 'operation' field in each
70 * modification construct have the following semantics respectively:
71 *
72 *
73 * add: add values listed to the given attribute, creating
74 * the attribute if necessary;
75 *
76 * delete: delete values listed from the given attribute,
77 * removing the entire attribute if no values are listed, or
78 * if all current values of the attribute are listed for
79 * deletion;
80 *
81 * replace: replace all existing values of the given attribute
82 * with the new values listed, creating the attribute if it
83 * did not already exist. A replace with no value will delete
84 * the entire attribute if it exists, and is ignored if the
85 * attribute does not exist.
86 * </pre>
87 *
88 * Notice that we tried to leverage as much as we already can from the JNDI.
89 * Both the Names and ModificationItems are used here to make the API as easy
90 * as possible to understand. We do not attempt here to write a JNDI provider
91 * which losses the explicit request type usage that we are looking for. Also
92 * note that this library is both for the client side as well as the server side
93 * unlike the JNDI which is strictly for the client side. From the JNDI we
94 * borrow good ideas and familiar signatures, interfaces and classes where we
95 * can.
96 *
97 * RFC 4525 suggest to add an operation in the enumeration:
98 *
99 * <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 */
116 public 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 }