001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009 Sun Microsystems, Inc.
025 *      Portions copyright 2012 ForgeRock AS.
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.List;
031
032import org.forgerock.i18n.LocalizedIllegalArgumentException;
033import org.forgerock.opendj.ldap.DN;
034import org.forgerock.opendj.ldap.DecodeException;
035import org.forgerock.opendj.ldap.DecodeOptions;
036import org.forgerock.opendj.ldap.RDN;
037import org.forgerock.opendj.ldap.controls.Control;
038import org.forgerock.opendj.ldap.controls.ControlDecoder;
039import org.forgerock.opendj.ldif.ChangeRecord;
040import org.forgerock.opendj.ldif.ChangeRecordVisitor;
041
042/**
043 * The Modify DN operation allows a client to change the Relative Distinguished
044 * Name (RDN) of an entry in the Directory and/or to move a subtree of entries
045 * to a new location in the Directory.
046 */
047public interface ModifyDNRequest extends Request, ChangeRecord {
048
049    @Override
050    <R, P> R accept(ChangeRecordVisitor<R, P> v, P p);
051
052    @Override
053    ModifyDNRequest addControl(Control control);
054
055    @Override
056    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
057            throws DecodeException;
058
059    @Override
060    List<Control> getControls();
061
062    /**
063     * Returns the distinguished name of the entry to be renamed. This entry may
064     * or may not have subordinate entries. The server shall not dereference any
065     * aliases in locating the entry to be renamed.
066     *
067     * @return The distinguished name of the entry.
068     */
069    @Override
070    DN getName();
071
072    /**
073     * Returns the new RDN of the entry to be renamed. The value of the old RDN
074     * is supplied when moving the entry to a new superior without changing its
075     * RDN. Attribute values of the new RDN not matching any attribute value of
076     * the entry are added to the entry, and an appropriate error is returned if
077     * this fails.
078     *
079     * @return The new RDN of the entry.
080     */
081    RDN getNewRDN();
082
083    /**
084     * Returns the distinguished name of an existing entry that will become the
085     * immediate superior (parent) of the entry to be renamed. The server shall
086     * not dereference any aliases in locating the new superior entry. The
087     * default value is {@code null}, indicating that the entry is to remain
088     * under the same parent entry.
089     *
090     * @return The distinguished name of the new superior entry, or {@code null}
091     *         if the entry is to remain under the same parent entry.
092     */
093    DN getNewSuperior();
094
095    /**
096     * Indicates whether the old RDN attribute values are to be retained as
097     * attributes of the entry or deleted from the entry. The default value is
098     * {@code false}.
099     *
100     * @return {@code true} if the old RDN attribute values are to be deleted
101     *         from the entry, or {@code false} if they are to be retained.
102     */
103    boolean isDeleteOldRDN();
104
105    /**
106     * Specifies whether the old RDN attribute values are to be retained as
107     * attributes of the entry or deleted from the entry. The default value is
108     * {@code false}.
109     *
110     * @param deleteOldRDN
111     *            {@code true} if the old RDN attribute values are to be deleted
112     *            from the entry, or {@code false} if they are to be retained.
113     * @return This modify DN request.
114     * @throws UnsupportedOperationException
115     *             If this modify DN request does not permit the delete old RDN
116     *             parameter to be set.
117     */
118    ModifyDNRequest setDeleteOldRDN(boolean deleteOldRDN);
119
120    /**
121     * Sets the distinguished name of the entry to be renamed. This entry may or
122     * may not have subordinate entries. The server shall not dereference any
123     * aliases in locating the entry to be renamed.
124     *
125     * @param dn
126     *            The distinguished name of the entry to be renamed.
127     * @return This modify DN request.
128     * @throws UnsupportedOperationException
129     *             If this modify DN request does not permit the distinguished
130     *             name to be set.
131     * @throws NullPointerException
132     *             If {@code dn} was {@code null}.
133     */
134    ModifyDNRequest setName(DN dn);
135
136    /**
137     * Sets the distinguished name of the entry to be renamed. This entry may or
138     * may not have subordinate entries. The server shall not dereference any
139     * aliases in locating the entry to be renamed.
140     *
141     * @param dn
142     *            The distinguished name of the entry to be renamed.
143     * @return This modify DN request.
144     * @throws LocalizedIllegalArgumentException
145     *             If {@code dn} could not be decoded using the default schema.
146     * @throws UnsupportedOperationException
147     *             If this modify DN request does not permit the distinguished
148     *             name to be set.
149     * @throws NullPointerException
150     *             If {@code dn} was {@code null}.
151     */
152    ModifyDNRequest setName(String dn);
153
154    /**
155     * Sets the new RDN of the entry to be renamed. The value of the old RDN is
156     * supplied when moving the entry to a new superior without changing its
157     * RDN. Attribute values of the new RDN not matching any attribute value of
158     * the entry are added to the entry, and an appropriate error is returned if
159     * this fails.
160     *
161     * @param rdn
162     *            The new RDN of the entry to be renamed.
163     * @return This modify DN request.
164     * @throws UnsupportedOperationException
165     *             If this modify DN request does not permit the new RDN to be
166     *             set.
167     * @throws NullPointerException
168     *             If {@code rdn} was {@code null}.
169     */
170    ModifyDNRequest setNewRDN(RDN rdn);
171
172    /**
173     * Sets the new RDN of the entry to be renamed. The value of the old RDN is
174     * supplied when moving the entry to a new superior without changing its
175     * RDN. Attribute values of the new RDN not matching any attribute value of
176     * the entry are added to the entry, and an appropriate error is returned if
177     * this fails.
178     *
179     * @param rdn
180     *            The new RDN of the entry to be renamed.
181     * @return This modify DN request.
182     * @throws LocalizedIllegalArgumentException
183     *             If {@code rdn} could not be decoded using the default schema.
184     * @throws UnsupportedOperationException
185     *             If this modify DN request does not permit the new RDN to be
186     *             set.
187     * @throws NullPointerException
188     *             If {@code rdn} was {@code null}.
189     */
190    ModifyDNRequest setNewRDN(String rdn);
191
192    /**
193     * Sets the distinguished name of an existing entry that will become the
194     * immediate superior (parent) of the entry to be renamed. The server shall
195     * not dereference any aliases in locating the new superior entry. The
196     * default value is {@code null}, indicating that the entry is to remain
197     * under the same parent entry.
198     *
199     * @param dn
200     *            The distinguished name of an existing entry that will become
201     *            the immediate superior (parent) of the entry to be renamed,
202     *            may be {@code null}.
203     * @return This modify DN request.
204     * @throws UnsupportedOperationException
205     *             If this modify DN request does not permit the new superior to
206     *             be set.
207     */
208    ModifyDNRequest setNewSuperior(DN dn);
209
210    /**
211     * Sets the distinguished name of an existing entry that will become the
212     * immediate superior (parent) of the entry to be renamed. The server shall
213     * not dereference any aliases in locating the new superior entry. The
214     * default value is {@code null}, indicating that the entry is to remain
215     * under the same parent entry.
216     *
217     * @param dn
218     *            The distinguished name of an existing entry that will become
219     *            the immediate superior (parent) of the entry to be renamed,
220     *            may be {@code null}.
221     * @return This modify DN request.
222     * @throws LocalizedIllegalArgumentException
223     *             If {@code dn} could not be decoded using the default schema.
224     * @throws UnsupportedOperationException
225     *             If this modify DN request does not permit the new superior to
226     *             be set.
227     */
228    ModifyDNRequest setNewSuperior(String dn);
229
230}