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