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;
021
022
023 import java.util.Collection;
024
025 import org.apache.directory.shared.ldap.entry.Modification;
026 import org.apache.directory.shared.ldap.name.LdapDN;
027
028
029 /**
030 * Modify request protocol message used to alter the attributes and values of an
031 * existing entry. Here's what <a href="">RFC 2255</a> says about it:
032 *
033 * <pre>
034 * 4.6. Modify Operation
035 *
036 * The Modify Operation allows a client to request that a modification
037 * of an entry be performed on its behalf by a server. The Modify
038 * Request is defined as follows:
039 *
040 * ModifyRequest ::= [APPLICATION 6] SEQUENCE {
041 * object LDAPDN,
042 * modification SEQUENCE OF SEQUENCE {
043 *
044 * operation ENUMERATED {
045 * add (0),
046 * delete (1),
047 * replace (2) },
048 * modification AttributeTypeAndValues } }
049 *
050 * AttributeTypeAndValues ::= SEQUENCE {
051 * type AttributeDescription,
052 * vals SET OF AttributeValue }
053 *
054 * Parameters of the Modify Request are:
055 *
056 * - object: The object to be modified. The value of this field contains
057 * the DN of the entry to be modified. The server will not perform
058 * any alias dereferencing in determining the object to be modified.
059 *
060 * - modification: A list of modifications to be performed on the entry.
061 * The entire list of entry modifications MUST be performed
062 * in the order they are listed, as a single atomic operation. While
063 * individual modifications may violate the directory schema, the
064 * resulting entry after the entire list of modifications is performed
065 * MUST conform to the requirements of the directory schema. The
066 * values that may be taken on by the 'operation' field in each
067 * modification construct have the following semantics respectively:
068 *
069 *
070 * add: add values listed to the given attribute, creating
071 * the attribute if necessary;
072 *
073 * delete: delete values listed from the given attribute,
074 * removing the entire attribute if no values are listed, or
075 * if all current values of the attribute are listed for
076 * deletion;
077 *
078 * replace: replace all existing values of the given attribute
079 * with the new values listed, creating the attribute if it
080 * did not already exist. A replace with no value will delete
081 * the entire attribute if it exists, and is ignored if the
082 * attribute does not exist.
083 * <pre>
084 *
085 * Notice that we tried to leverage as much as we already can from the JNDI.
086 * Both the Names and ModificationItems are used here to make the API as easy
087 * as possible to understand. We do not attempt here to write a JNDI provider
088 * which losses the explicit request type usage that we are looking for. Also
089 * note that this library is both for the client side as well as the server side
090 * unlike the JNDI which is strictly for the client side. From the JNDI we
091 * borrow good ideas and familiar signatures, interfaces and classes where we
092 * can.
093 *
094 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
095 * @version $Revision: 764131 $
096 *
097 */
098 public interface InternalModifyRequest extends SingleReplyRequest, InternalAbandonableRequest
099 {
100 /** Modify request message type enumeration value */
101 MessageTypeEnum TYPE = MessageTypeEnum.MODIFY_REQUEST;
102
103 /** Modify response message type enumeration value */
104 MessageTypeEnum RESP_TYPE = InternalModifyResponse.TYPE;
105
106
107 /**
108 * Gets the distinguished name of the entry to be modified by this request.
109 * This property represents the PDU's <b>object</b> field.
110 *
111 * @return the DN of the modified entry.
112 */
113 LdapDN getName();
114
115
116 /**
117 * Sets the distinguished name of the entry to be modified by this request.
118 * This property represents the PDU's <b>object</b> field.
119 *
120 * @param name
121 * the DN of the modified entry.
122 */
123 void setName( LdapDN name );
124
125
126 /**
127 * Gets an immutable Collection of modification items representing the
128 * atomic changes to perform on the candidate entry to modify.
129 *
130 * @return an immutable Collection of Modification instances.
131 */
132 Collection<Modification> getModificationItems();
133
134
135 /**
136 * Adds a ModificationItem to the set of modifications composing this modify
137 * request.
138 *
139 * @param mod a Modification to add.
140 */
141 void addModification( Modification mod );
142
143
144 /**
145 * Removes a ModificationItem to the set of modifications composing this
146 * modify request.
147 *
148 * @param mod a Modification to remove.
149 */
150 void removeModification( Modification mod );
151 }