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