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 org.apache.directory.api.ldap.model.name.Dn;
024import org.apache.directory.api.ldap.model.name.Rdn;
025
026
027/**
028 * Modify Dn request protocol message used to rename or move an existing entry
029 * in the directory. Here's what <a
030 * href="http://www.faqs.org/rfcs/rfc2251.html">RFC 2251</a> has to say about
031 * it:
032 * 
033 * <pre>
034 *  4.9. Modify Dn Operation
035 * 
036 *   The Modify Dn Operation allows a client to change the leftmost (least
037 *   significant) component of the name of an entry in the directory, or
038 *   to move a subtree of entries to a new location in the directory.  The
039 *   Modify Dn Request is defined as follows:
040 * 
041 *        ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
042 *                entry           LDAPDN,
043 *                newrdn          RelativeLDAPDN,
044 *                deleteoldrdn    BOOLEAN,
045 *                newSuperior     [0] LDAPDN OPTIONAL }
046 * 
047 *   Parameters of the Modify Dn Request are:
048 * 
049 *   - entry: the Distinguished Name of the entry to be changed.  This
050 *     entry may or may not have subordinate entries.
051 * 
052 *   - newrdn: the Rdn that will form the leftmost component of the new
053 *     name of the entry.
054 * 
055 *   - deleteoldrdn: a boolean parameter that controls whether the old Rdn
056 *     attribute values are to be retained as attributes of the entry, or
057 *     deleted from the entry.
058 * 
059 *   - newSuperior: if present, this is the Distinguished Name of the entry
060 *     which becomes the immediate superior of the existing entry.
061 * </pre>
062 * 
063 * Note that this operation can move an entry and change its Rdn at the same
064 * time in fact it might have no choice to comply with name forms.
065 * 
066 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
067 */
068public interface ModifyDnRequest extends SingleReplyRequest<ModifyDnResponse>, AbandonableRequest
069{
070    /** Modify Dn request message type enumeration value */
071    MessageTypeEnum TYPE = MessageTypeEnum.MODIFYDN_REQUEST;
072
073    /** Modify Dn response message type enumeration value */
074    MessageTypeEnum RESP_TYPE = ModifyDnResponse.TYPE;
075
076
077    /**
078     * Gets the entry's distinguished name representing the <b>entry</b> PDU
079     * field.
080     * 
081     * @return the distinguished name of the entry.
082     */
083    Dn getName();
084
085
086    /**
087     * Sets the entry's distinguished name representing the <b>entry</b> PDU
088     * field.
089     * 
090     * @param name the distinguished name of the entry.
091     * @return The ModifyDnRequest instance
092     */
093    ModifyDnRequest setName( Dn name );
094
095
096    /**
097     * Gets the new relative distinguished name for the entry which represents
098     * the PDU's <b>newrdn</b> field.
099     * 
100     * @return the relative dn with one component
101     */
102    Rdn getNewRdn();
103
104
105    /**
106     * Sets the new relative distinguished name for the entry which represents
107     * the PDU's <b>newrdn</b> field.
108     * 
109     * @param newRdn the relative dn with one component
110     * @return The ModifyDnRequest instance
111     */
112    ModifyDnRequest setNewRdn( Rdn newRdn );
113
114
115    /**
116     * Gets the flag which determines if the old Rdn attribute is to be removed
117     * from the entry when the new Rdn is used in its stead. This property
118     * corresponds to the <b>deleteoldrdn</b>.
119     * 
120     * @return true if the old rdn is to be deleted, false if it is not
121     */
122    boolean getDeleteOldRdn();
123
124
125    /**
126     * Sets the flag which determines if the old Rdn attribute is to be removed
127     * from the entry when the new Rdn is used in its stead. This property
128     * corresponds to the <b>deleteoldrdn</b>.
129     * 
130     * @param deleteOldRdn true if the old rdn is to be deleted, false if it is not
131     * @return The ModifyDnRequest instance
132     */
133    ModifyDnRequest setDeleteOldRdn( boolean deleteOldRdn );
134
135
136    /**
137     * Gets the optional distinguished name of the new superior entry where the
138     * candidate entry is to be moved. This property corresponds to the PDU's
139     * <b>newSuperior</b> field. May be null representing a simple Rdn change
140     * rather than a move operation.
141     * 
142     * @return the dn of the superior entry the candidate entry is moved under.
143     */
144    Dn getNewSuperior();
145
146
147    /**
148     * Sets the optional distinguished name of the new superior entry where the
149     * candidate entry is to be moved. This property corresponds to the PDU's
150     * <b>newSuperior</b> field. May be null representing a simple Rdn change
151     * rather than a move operation. Setting this property to a non-null value
152     * toggles the move flag obtained via the <code>isMove</code> method.
153     * 
154     * @param newSuperior the dn of the superior entry the candidate entry for Dn
155     * modification is moved under.
156     * @return The ModifyDnRequest instance
157     */
158    ModifyDnRequest setNewSuperior( Dn newSuperior );
159
160
161    /**
162     * Gets whether or not this request is a Dn change resulting in a move
163     * operation. Setting the newSuperior property to a non-null name, toggles
164     * this flag.
165     * 
166     * @return true if the newSuperior property is <b>NOT</b> null, false
167     * otherwise.
168     */
169    boolean isMove();
170
171
172    /**
173     * {@inheritDoc}
174     */
175    ModifyDnRequest setMessageId( int messageId );
176
177
178    /**
179     * {@inheritDoc}
180     */
181    ModifyDnRequest addControl( Control control );
182
183
184    /**
185     * {@inheritDoc}
186     */
187    ModifyDnRequest addAllControls( Control[] controls );
188
189
190    /**
191     * {@inheritDoc}
192     */
193    ModifyDnRequest removeControl( Control control );
194}