001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2009 Sun Microsystems, Inc.
015 * Portions copyright 2012 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import java.util.List;
021
022import org.forgerock.i18n.LocalizedIllegalArgumentException;
023import org.forgerock.opendj.ldap.DN;
024import org.forgerock.opendj.ldap.DecodeException;
025import org.forgerock.opendj.ldap.DecodeOptions;
026import org.forgerock.opendj.ldap.controls.Control;
027import org.forgerock.opendj.ldap.controls.ControlDecoder;
028import org.forgerock.opendj.ldif.ChangeRecord;
029import org.forgerock.opendj.ldif.ChangeRecordVisitor;
030
031/**
032 * The Delete operation allows a client to request the removal of an entry from
033 * the Directory.
034 * <p>
035 * Only leaf entries (those with no subordinate entries) can be deleted with
036 * this operation. However, addition of the {@code SubtreeDeleteControl} permits
037 * whole sub-trees to be deleted using a single Delete request.
038 *
039 * <pre>
040 * Connection connection = ...;
041 * String baseDN = ...;
042 *
043 * DeleteRequest request =
044 *         Requests.newDeleteRequest(baseDN)
045 *             .addControl(SubtreeDeleteRequestControl.newControl(true));
046 * connection.delete(request);
047 * </pre>
048 */
049public interface DeleteRequest extends Request, ChangeRecord {
050
051    @Override
052    <R, P> R accept(ChangeRecordVisitor<R, P> v, P p);
053
054    @Override
055    DeleteRequest addControl(Control control);
056
057    @Override
058    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
059            throws DecodeException;
060
061    @Override
062    List<Control> getControls();
063
064    /**
065     * Returns the distinguished name of the entry to be deleted. The server
066     * shall not dereference any aliases in locating the entry to be deleted.
067     *
068     * @return The distinguished name of the entry.
069     */
070    @Override
071    DN getName();
072
073    /**
074     * Sets the distinguished name of the entry to be deleted. The server shall
075     * not dereference any aliases in locating the entry to be deleted.
076     *
077     * @param dn
078     *            The distinguished name of the entry to be deleted.
079     * @return This delete request.
080     * @throws UnsupportedOperationException
081     *             If this delete request does not permit the distinguished name
082     *             to be set.
083     * @throws NullPointerException
084     *             If {@code dn} was {@code null}.
085     */
086    DeleteRequest setName(DN dn);
087
088    /**
089     * Sets the distinguished name of the entry to be deleted. The server shall
090     * not dereference any aliases in locating the entry to be deleted.
091     *
092     * @param dn
093     *            The distinguished name of the entry to be deleted.
094     * @return This delete request.
095     * @throws LocalizedIllegalArgumentException
096     *             If {@code dn} could not be decoded using the default schema.
097     * @throws UnsupportedOperationException
098     *             If this delete request does not permit the distinguished name
099     *             to be set.
100     * @throws NullPointerException
101     *             If {@code dn} was {@code null}.
102     */
103    DeleteRequest setName(String dn);
104
105}