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}