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="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 * 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 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 }