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