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