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}