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.controls.Control;
037import org.forgerock.opendj.ldap.controls.ControlDecoder;
038import org.forgerock.opendj.ldif.ChangeRecord;
039import org.forgerock.opendj.ldif.ChangeRecordVisitor;
040
041/**
042 * The Delete operation allows a client to request the removal of an entry from
043 * the Directory.
044 * <p>
045 * Only leaf entries (those with no subordinate entries) can be deleted with
046 * this operation. However, addition of the {@code SubtreeDeleteControl} permits
047 * whole sub-trees to be deleted using a single Delete request.
048 *
049 * <pre>
050 * Connection connection = ...;
051 * String baseDN = ...;
052 *
053 * DeleteRequest request =
054 *         Requests.newDeleteRequest(baseDN)
055 *             .addControl(SubtreeDeleteRequestControl.newControl(true));
056 * connection.delete(request);
057 * </pre>
058 */
059public interface DeleteRequest extends Request, ChangeRecord {
060
061    @Override
062    <R, P> R accept(ChangeRecordVisitor<R, P> v, P p);
063
064    @Override
065    DeleteRequest addControl(Control control);
066
067    @Override
068    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
069            throws DecodeException;
070
071    @Override
072    List<Control> getControls();
073
074    /**
075     * Returns the distinguished name of the entry to be deleted. The server
076     * shall not dereference any aliases in locating the entry to be deleted.
077     *
078     * @return The distinguished name of the entry.
079     */
080    @Override
081    DN getName();
082
083    /**
084     * Sets the distinguished name of the entry to be deleted. The server shall
085     * not dereference any aliases in locating the entry to be deleted.
086     *
087     * @param dn
088     *            The distinguished name of the entry to be deleted.
089     * @return This delete request.
090     * @throws UnsupportedOperationException
091     *             If this delete request does not permit the distinguished name
092     *             to be set.
093     * @throws NullPointerException
094     *             If {@code dn} was {@code null}.
095     */
096    DeleteRequest setName(DN dn);
097
098    /**
099     * Sets the distinguished name of the entry to be deleted. The server shall
100     * not dereference any aliases in locating the entry to be deleted.
101     *
102     * @param dn
103     *            The distinguished name of the entry to be deleted.
104     * @return This delete request.
105     * @throws LocalizedIllegalArgumentException
106     *             If {@code dn} could not be decoded using the default schema.
107     * @throws UnsupportedOperationException
108     *             If this delete request does not permit the distinguished name
109     *             to be set.
110     * @throws NullPointerException
111     *             If {@code dn} was {@code null}.
112     */
113    DeleteRequest setName(String dn);
114
115}