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 * <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 * @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 }