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, AbandonableRequest
069{
070    /**
071     * Gets the entry's distinguished name representing the <b>entry</b> PDU
072     * field.
073     * 
074     * @return the distinguished name of the entry.
075     */
076    Dn getName();
077
078
079    /**
080     * Sets the entry's distinguished name representing the <b>entry</b> PDU
081     * field.
082     * 
083     * @param name the distinguished name of the entry.
084     * @return The ModifyDnRequest instance
085     */
086    ModifyDnRequest setName( Dn name );
087
088
089    /**
090     * Gets the new relative distinguished name for the entry which represents
091     * the PDU's <b>newrdn</b> field.
092     * 
093     * @return the relative dn with one component
094     */
095    Rdn getNewRdn();
096
097
098    /**
099     * Sets the new relative distinguished name for the entry which represents
100     * the PDU's <b>newrdn</b> field.
101     * 
102     * @param newRdn the relative dn with one component
103     * @return The ModifyDnRequest instance
104     */
105    ModifyDnRequest setNewRdn( Rdn newRdn );
106
107
108    /**
109     * Gets the flag which determines if the old Rdn attribute is to be removed
110     * from the entry when the new Rdn is used in its stead. This property
111     * corresponds to the <b>deleteoldrdn</b>.
112     * 
113     * @return true if the old rdn is to be deleted, false if it is not
114     */
115    boolean getDeleteOldRdn();
116
117
118    /**
119     * Sets the flag which determines if the old Rdn attribute is to be removed
120     * from the entry when the new Rdn is used in its stead. This property
121     * corresponds to the <b>deleteoldrdn</b>.
122     * 
123     * @param deleteOldRdn true if the old rdn is to be deleted, false if it is not
124     * @return The ModifyDnRequest instance
125     */
126    ModifyDnRequest setDeleteOldRdn( boolean deleteOldRdn );
127
128
129    /**
130     * Gets the optional distinguished name of the new superior entry where the
131     * candidate entry is to be moved. This property corresponds to the PDU's
132     * <b>newSuperior</b> field. May be null representing a simple Rdn change
133     * rather than a move operation.
134     * 
135     * @return the dn of the superior entry the candidate entry is moved under.
136     */
137    Dn getNewSuperior();
138
139
140    /**
141     * Sets the optional distinguished name of the new superior entry where the
142     * candidate entry is to be moved. This property corresponds to the PDU's
143     * <b>newSuperior</b> field. May be null representing a simple Rdn change
144     * rather than a move operation. Setting this property to a non-null value
145     * toggles the move flag obtained via the <code>isMove</code> method.
146     * 
147     * @param newSuperior the dn of the superior entry the candidate entry for Dn
148     * modification is moved under.
149     * @return The ModifyDnRequest instance
150     */
151    ModifyDnRequest setNewSuperior( Dn newSuperior );
152
153
154    /**
155     * Gets whether or not this request is a Dn change resulting in a move
156     * operation. Setting the newSuperior property to a non-null name, toggles
157     * this flag.
158     * 
159     * @return true if the newSuperior property is <b>NOT</b> null, false
160     * otherwise.
161     */
162    boolean isMove();
163
164
165    /**
166     * {@inheritDoc}
167     */
168    @Override
169    ModifyDnRequest setMessageId( int messageId );
170
171
172    /**
173     * {@inheritDoc}
174     */
175    @Override
176    ModifyDnRequest addControl( Control control );
177
178
179    /**
180     * {@inheritDoc}
181     */
182    @Override
183    ModifyDnRequest addAllControls( Control[] controls );
184
185
186    /**
187     * {@inheritDoc}
188     */
189    @Override
190    ModifyDnRequest removeControl( Control control );
191}