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 2006-2008 Sun Microsystems, Inc. 025 * Portions Copyright 2011-2015 ForgeRock AS. 026 */ 027package org.opends.server.types.operation; 028import org.forgerock.i18n.LocalizableMessage; 029 030 031 032import java.util.List; 033 034import org.opends.server.types.*; 035import org.forgerock.opendj.ldap.ResultCode; 036import org.forgerock.i18n.LocalizableMessageBuilder; 037 038 039/** 040 * This class defines a set of methods that are available for use by 041 * plugins for operations that are currently in the middle of their 042 * "core" processing (e.g., for examining search result entries or 043 * references before they are sent to the client). Note that this 044 * interface is intended only to define an API for use by plugins and 045 * is not intended to be implemented by any custom classes. 046 */ 047@org.opends.server.types.PublicAPI( 048 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED, 049 mayInstantiate=false, 050 mayExtend=false, 051 mayInvoke=true) 052public interface InProgressOperation 053 extends PluginOperation 054{ 055 /** 056 * Adds the provided control to the set of controls to include in 057 * the response to the client. 058 * 059 * @param control The control to add to the set of controls to 060 * include in the response to the client. 061 */ 062 void addResponseControl(Control control); 063 064 065 066 /** 067 * Removes the provided control from the set of controls to include 068 * in the response to the client. 069 * 070 * @param control The control to remove from the set of controls 071 * to include in the response to the client. 072 */ 073 void removeResponseControl(Control control); 074 075 076 077 /** 078 * Retrieves the result code for this operation. 079 * 080 * @return The result code associated for this operation, or 081 * <CODE>UNDEFINED</CODE> if the operation has not yet 082 * completed. 083 */ 084 ResultCode getResultCode(); 085 086 087 088 /** 089 * Specifies the result code for this operation. 090 * 091 * @param resultCode The result code for this operation. 092 */ 093 void setResultCode(ResultCode resultCode); 094 095 096 097 /** 098 * Retrieves the error message for this operation. Its contents may 099 * be altered by the caller. 100 * 101 * @return The error message for this operation. 102 */ 103 LocalizableMessageBuilder getErrorMessage(); 104 105 106 107 /** 108 * Specifies the error message for this operation. 109 * 110 * @param errorMessage The error message for this operation. 111 */ 112 void setErrorMessage(LocalizableMessageBuilder errorMessage); 113 114 115 116 /** 117 * Appends the provided message to the error message buffer. If the 118 * buffer has not yet been created, then this will create it first 119 * and then add the provided message. 120 * 121 * @param message The message to append to the error message 122 */ 123 void appendErrorMessage(LocalizableMessage message); 124 125 126 127 /** 128 * Retrieves the matched DN for this operation. 129 * 130 * @return The matched DN for this operation, or <CODE>null</CODE> 131 * if the operation has not yet completed or does not have 132 * a matched DN. 133 */ 134 DN getMatchedDN(); 135 136 137 138 /** 139 * Specifies the matched DN for this operation. 140 * 141 * @param matchedDN The matched DN for this operation. 142 */ 143 void setMatchedDN(DN matchedDN); 144 145 146 147 /** 148 * Retrieves the set of referral URLs for this operation. Its 149 * contents must not be altered by the caller. 150 * 151 * @return The set of referral URLs for this operation, or 152 * <CODE>null</CODE> if the operation is not yet complete 153 * or does not have a set of referral URLs. 154 */ 155 List<String> getReferralURLs(); 156 157 158 159 /** 160 * Specifies the set of referral URLs for this operation. 161 * 162 * @param referralURLs The set of referral URLs for this 163 * operation. 164 */ 165 void setReferralURLs(List<String> referralURLs); 166 167 168 169 /** 170 * Sets the response elements for this operation based on the 171 * information contained in the provided 172 * <CODE>DirectoryException</CODE> object. 173 * 174 * @param directoryException The exception containing the 175 * information to use for the response 176 * elements. 177 */ 178 void setResponseData(DirectoryException directoryException); 179 180 181 182 /** 183 * Retrieves the authorization DN for this operation. In many 184 * cases, it will be the same as the DN of the authenticated user 185 * for the underlying connection, or the null DN if no 186 * authentication has been performed on that connection. However, 187 * it may be some other value if special processing has been 188 * requested (e.g., the operation included a proxied authorization 189 * control). 190 * 191 * @return The authorization DN for this operation. 192 */ 193 DN getAuthorizationDN(); 194 195 196 197 /** 198 * Returns an unmodifiable list containing the additional log items for this 199 * operation, which should be written to the log but not included in the 200 * response to the client. 201 * 202 * @return An unmodifiable list containing the additional log items for this 203 * operation. 204 */ 205 List<AdditionalLogItem> getAdditionalLogItems(); 206 207 208 209 /** 210 * Adds an additional log item to this operation, which should be written to 211 * the log but not included in the response to the client. This method may not 212 * be called by post-response plugins. 213 * 214 * @param item 215 * The additional log item for this operation. 216 */ 217 void addAdditionalLogItem(AdditionalLogItem item); 218} 219