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-2015 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.ByteString;
024import org.forgerock.opendj.ldap.DN;
025import org.forgerock.opendj.ldap.DecodeException;
026import org.forgerock.opendj.ldap.DecodeOptions;
027import org.forgerock.opendj.ldap.Modification;
028import org.forgerock.opendj.ldap.ModificationType;
029import org.forgerock.opendj.ldap.controls.Control;
030import org.forgerock.opendj.ldap.controls.ControlDecoder;
031import org.forgerock.opendj.ldif.ChangeRecord;
032import org.forgerock.opendj.ldif.ChangeRecordVisitor;
033
034/**
035 * The Modify operation allows a client to request that a modification of an
036 * entry be performed on its behalf by a server.
037 * <p>
038 * The following example adds a member to a static group entry.
039 *
040 * <pre>
041 * Connection connection = ...;
042 * String groupDN = ...;
043 * String memberDN = ...;
044 *
045 * ModifyRequest addMember = Requests.newModifyRequest(groupDN)
046 *         .addModification(ModificationType.ADD, "member", memberDN);
047 * connection.modify(addMember);
048 * </pre>
049 */
050public interface ModifyRequest extends Request, ChangeRecord {
051
052    @Override
053    <R, P> R accept(ChangeRecordVisitor<R, P> v, P p);
054
055    @Override
056    ModifyRequest addControl(Control control);
057
058    /**
059     * Appends the provided modification to the list of modifications included
060     * with this modify request.
061     *
062     * @param modification
063     *            The modification to be performed.
064     * @return This modify request.
065     * @throws UnsupportedOperationException
066     *             If this modify request does not permit modifications to be
067     *             added.
068     * @throws NullPointerException
069     *             If {@code modification} was {@code null}.
070     */
071    ModifyRequest addModification(Modification modification);
072
073    /**
074     * Appends the provided modification to the list of modifications included
075     * with this modify request.
076     * <p>
077     * If the attribute value is not an instance of {@code ByteString} then it
078     * will be converted using the {@link ByteString#valueOfObject(Object)} method.
079     *
080     * @param type
081     *            The type of modification to be performed.
082     * @param attributeDescription
083     *            The name of the attribute to be modified.
084     * @param values
085     *            The attribute values to be modified.
086     * @return This modify request.
087     * @throws LocalizedIllegalArgumentException
088     *             If {@code attributeDescription} could not be decoded using
089     *             the default schema.
090     * @throws UnsupportedOperationException
091     *             If this modify request does not permit modifications to be
092     *             added.
093     * @throws NullPointerException
094     *             If {@code type}, {@code attributeDescription}, or
095     *             {@code value} was {@code null}.
096     */
097    ModifyRequest addModification(ModificationType type, String attributeDescription,
098            Object... values);
099
100    @Override
101    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
102            throws DecodeException;
103
104    @Override
105    List<Control> getControls();
106
107    /**
108     * Returns a {@code List} containing the modifications included with this
109     * modify request. The returned {@code List} may be modified if permitted by
110     * this modify request.
111     *
112     * @return A {@code List} containing the modifications.
113     */
114    List<Modification> getModifications();
115
116    /**
117     * Returns the distinguished name of the entry to be modified. The server
118     * shall not perform any alias dereferencing in determining the object to be
119     * modified.
120     *
121     * @return The distinguished name of the entry to be modified.
122     */
123    @Override
124    DN getName();
125
126    /**
127     * Sets the distinguished name of the entry to be modified. The server shall
128     * not perform any alias dereferencing in determining the object to be
129     * modified.
130     *
131     * @param dn
132     *            The the distinguished name of the entry to be modified.
133     * @return This modify request.
134     * @throws UnsupportedOperationException
135     *             If this modify request does not permit the distinguished name
136     *             to be set.
137     * @throws NullPointerException
138     *             If {@code dn} was {@code null}.
139     */
140    ModifyRequest setName(DN dn);
141
142    /**
143     * Sets the distinguished name of the entry to be modified. The server shall
144     * not perform any alias dereferencing in determining the object to be
145     * modified.
146     *
147     * @param dn
148     *            The the distinguished name of the entry to be modified.
149     * @return This modify request.
150     * @throws LocalizedIllegalArgumentException
151     *             If {@code dn} could not be decoded using the default schema.
152     * @throws UnsupportedOperationException
153     *             If this modify request does not permit the distinguished name
154     *             to be set.
155     * @throws NullPointerException
156     *             If {@code dn} was {@code null}.
157     */
158    ModifyRequest setName(String dn);
159
160}