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 010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2006-2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.types.operation; 028 import org.opends.messages.Message; 029 030 031 032 import java.util.List; 033 034 import org.opends.server.types.Control; 035 import org.opends.server.types.DirectoryException; 036 import org.opends.server.types.DN; 037 import org.opends.server.types.ResultCode; 038 039 import org.opends.messages.MessageBuilder; 040 041 042 /** 043 * This class defines a set of methods that are available for use by 044 * plugins for operations that are currently in the middle of their 045 * "core" processing (e.g., for examining search result entries or 046 * references before they are sent to the client). Note that this 047 * interface is intended only to define an API for use by plugins and 048 * is not intended to be implemented by any custom classes. 049 */ 050 @org.opends.server.types.PublicAPI( 051 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED, 052 mayInstantiate=false, 053 mayExtend=false, 054 mayInvoke=true) 055 public interface InProgressOperation 056 extends PluginOperation 057 { 058 /** 059 * Adds the provided control to the set of controls to include in 060 * the response to the client. 061 * 062 * @param control The control to add to the set of controls to 063 * include in the response to the client. 064 */ 065 public void addResponseControl(Control control); 066 067 068 069 /** 070 * Removes the provided control from the set of controls to include 071 * in the response to the client. 072 * 073 * @param control The control to remove from the set of controls 074 * to include in the response to the client. 075 */ 076 public void removeResponseControl(Control control); 077 078 079 080 /** 081 * Retrieves the result code for this operation. 082 * 083 * @return The result code associated for this operation, or 084 * <CODE>UNDEFINED</CODE> if the operation has not yet 085 * completed. 086 */ 087 public ResultCode getResultCode(); 088 089 090 091 /** 092 * Specifies the result code for this operation. 093 * 094 * @param resultCode The result code for this operation. 095 */ 096 public void setResultCode(ResultCode resultCode); 097 098 099 100 /** 101 * Retrieves the error message for this operation. Its contents may 102 * be altered by the caller. 103 * 104 * @return The error message for this operation. 105 */ 106 public MessageBuilder getErrorMessage(); 107 108 109 110 /** 111 * Specifies the error message for this operation. 112 * 113 * @param errorMessage The error message for this operation. 114 */ 115 public void setErrorMessage(MessageBuilder errorMessage); 116 117 118 119 /** 120 * Appends the provided message to the error message buffer. If the 121 * buffer has not yet been created, then this will create it first 122 * and then add the provided message. 123 * 124 * @param message The message to append to the error message 125 */ 126 public void appendErrorMessage(Message message); 127 128 129 130 /** 131 * Retrieves the additional log message for this operation, which 132 * should be written to the log but not included in the response to 133 * the client. The contents of this buffer may be altered by the 134 * caller. 135 * 136 * @return The additional log message for this operation. 137 */ 138 public MessageBuilder getAdditionalLogMessage(); 139 140 141 142 /** 143 * Specifies the additional log message for this operation, which 144 * should be written to the log but not included in the response to 145 * the client. 146 * 147 * @param additionalLogMessage The additional log message for this 148 * operation. 149 */ 150 public void setAdditionalLogMessage( 151 MessageBuilder additionalLogMessage); 152 153 154 155 /** 156 * Appends the provided message to the additional log information 157 * for this operation. 158 * 159 * @param message The message that should be appended to the 160 * additional log information for this operation. 161 */ 162 public void appendAdditionalLogMessage(Message message); 163 164 165 166 /** 167 * Retrieves the matched DN for this operation. 168 * 169 * @return The matched DN for this operation, or <CODE>null</CODE> 170 * if the operation has not yet completed or does not have 171 * a matched DN. 172 */ 173 public DN getMatchedDN(); 174 175 176 177 /** 178 * Specifies the matched DN for this operation. 179 * 180 * @param matchedDN The matched DN for this operation. 181 */ 182 public void setMatchedDN(DN matchedDN); 183 184 185 186 /** 187 * Retrieves the set of referral URLs for this operation. Its 188 * contents must not be altered by the caller. 189 * 190 * @return The set of referral URLs for this operation, or 191 * <CODE>null</CODE> if the operation is not yet complete 192 * or does not have a set of referral URLs. 193 */ 194 public List<String> getReferralURLs(); 195 196 197 198 /** 199 * Specifies the set of referral URLs for this operation. 200 * 201 * @param referralURLs The set of referral URLs for this 202 * operation. 203 */ 204 public void setReferralURLs(List<String> referralURLs); 205 206 207 208 /** 209 * Sets the response elements for this operation based on the 210 * information contained in the provided 211 * <CODE>DirectoryException</CODE> object. 212 * 213 * @param directoryException The exception containing the 214 * information to use for the response 215 * elements. 216 */ 217 public void setResponseData(DirectoryException directoryException); 218 219 220 221 /** 222 * Retrieves the authorization DN for this operation. In many 223 * cases, it will be the same as the DN of the authenticated user 224 * for the underlying connection, or the null DN if no 225 * authentication has been performed on that connection. However, 226 * it may be some other value if special processing has been 227 * requested (e.g., the operation included a proxied authorization 228 * control). 229 * 230 * @return The authorization DN for this operation. 231 */ 232 public DN getAuthorizationDN(); 233 } 234