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     */
020    package org.apache.directory.shared.ldap.message.internal;
021    
022    
023    import java.util.Collection;
024    
025    import org.apache.directory.shared.ldap.codec.MessageTypeEnum;
026    import org.apache.directory.shared.ldap.entry.Modification;
027    import org.apache.directory.shared.ldap.message.SingleReplyRequest;
028    import org.apache.directory.shared.ldap.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     *  &lt;pre&gt;
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     *  @version $Revision: 918756 $
098     * 
099     */
100    public interface InternalModifyRequest extends SingleReplyRequest, InternalAbandonableRequest
101    {
102        /** Modify request message type enumeration value */
103        MessageTypeEnum TYPE = MessageTypeEnum.MODIFY_REQUEST;
104    
105        /** Modify response message type enumeration value */
106        MessageTypeEnum RESP_TYPE = InternalModifyResponse.TYPE;
107    
108    
109        /**
110         * Gets the distinguished name of the entry to be modified by this request.
111         * This property represents the PDU's <b>object</b> field.
112         * 
113         * @return the DN of the modified entry.
114         */
115        DN getName();
116    
117    
118        /**
119         * Sets 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         * @param name
123         *            the DN of the modified entry.
124         */
125        void setName( DN name );
126    
127    
128        /**
129         * Gets an immutable Collection of modification items representing the
130         * atomic changes to perform on the candidate entry to modify.
131         * 
132         * @return an immutable Collection of Modification instances.
133         */
134        Collection<Modification> getModificationItems();
135    
136    
137        /**
138         * Adds a ModificationItem to the set of modifications composing this modify
139         * request.
140         * 
141         * @param mod a Modification to add.
142         */
143        void addModification( Modification mod );
144    
145    
146        /**
147         * Removes a ModificationItem to the set of modifications composing this
148         * modify request.
149         * 
150         * @param mod a Modification to remove.
151         */
152        void removeModification( Modification mod );
153    }