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 2014 ForgeRock AS. 016 */ 017package org.opends.server.types.operation; 018 019import java.util.List; 020import java.util.Map; 021 022import org.forgerock.i18n.LocalizableMessage; 023import org.opends.server.api.ClientConnection; 024import org.opends.server.controls.ControlDecoder; 025import org.opends.server.types.CanceledOperationException; 026import org.opends.server.types.Control; 027import org.opends.server.types.DirectoryException; 028import org.opends.server.types.DisconnectReason; 029import org.opends.server.types.OperationType; 030 031/** 032 * This class defines a set of methods that are available for use by 033 * all types of plugins involved in operation processing (pre-parse, 034 * pre-operation, post-operation, post-response, search result entry, 035 * search result reference, and intermediate response). Note that 036 * this interface is intended only to define an API for use by plugins 037 * and is not intended to be implemented by any custom classes. 038 */ 039@org.opends.server.types.PublicAPI( 040 stability=org.opends.server.types.StabilityLevel.UNCOMMITTED, 041 mayInstantiate=false, 042 mayExtend=false, 043 mayInvoke=true) 044public interface PluginOperation 045{ 046 /** 047 * Retrieves the operation type for this operation. 048 * 049 * @return The operation type for this operation. 050 */ 051 OperationType getOperationType(); 052 053 054 055 /** 056 * Retrieves the client connection with which this operation is 057 * associated. 058 * 059 * @return The client connection with which this operation is 060 * associated. 061 */ 062 ClientConnection getClientConnection(); 063 064 065 066 /** 067 * Terminates the client connection being used to process this 068 * operation. The plugin must return a result indicating that the 069 * client connection has been terminated. 070 * 071 * @param disconnectReason The disconnect reason that provides the 072 * generic cause for the disconnect. 073 * @param sendNotification Indicates whether to try to provide 074 * notification to the client that the 075 * connection will be closed. 076 * @param message The message to send to the client. It 077 * may be <CODE>null</CODE> if no 078 * notification is to be sent. 079 */ 080 void disconnectClient(DisconnectReason disconnectReason, boolean sendNotification, LocalizableMessage message); 081 082 083 084 /** 085 * Retrieves the unique identifier that is assigned to the client 086 * connection that submitted this operation. 087 * 088 * @return The unique identifier that is assigned to the client 089 * connection that submitted this operation. 090 */ 091 long getConnectionID(); 092 093 094 095 /** 096 * Retrieves the operation ID for this operation. 097 * 098 * @return The operation ID for this operation. 099 */ 100 long getOperationID(); 101 102 103 104 /** 105 * Retrieves the message ID assigned to this operation. 106 * 107 * @return The message ID assigned to this operation. 108 */ 109 int getMessageID(); 110 111 112 113 /** 114 * Retrieves the set of controls included in the request from the 115 * client. The contents of this list must not be altered. 116 * 117 * @return The set of controls included in the request from the 118 * client. 119 */ 120 List<Control> getRequestControls(); 121 122 123 124 /** 125 * Retrieves a control included in the request from the client. 126 * 127 * @param <T> 128 * The type of control requested. 129 * @param d 130 * The requested control's decoder. 131 * @return The decoded form of the requested control included in the 132 * request from the client or <code>null</code> if the 133 * control was not found. 134 * @throws DirectoryException 135 * if an error occurs while decoding the control. 136 */ 137 <T extends Control> T getRequestControl(ControlDecoder<T> d) throws DirectoryException; 138 139 140 141 /** 142 * Retrieves the set of controls to include in the response to the 143 * client. The contents of this list must not be altered. 144 * 145 * @return The set of controls to include in the response to the 146 * client. 147 */ 148 List<Control> getResponseControls(); 149 150 151 152 /** 153 * Indicates whether this is an internal operation rather than one 154 * that was requested by an external client. 155 * 156 * @return <CODE>true</CODE> if this is an internal operation, or 157 * <CODE>false</CODE> if it is not. 158 */ 159 boolean isInternalOperation(); 160 161 162 163 /** 164 * Indicates whether this is a synchronization operation rather than 165 * one that was requested by an external client. 166 * 167 * @return <CODE>true</CODE> if this is a data synchronization 168 * operation, or <CODE>false</CODE> if it is not. 169 */ 170 boolean isSynchronizationOperation(); 171 172 173 174 /** 175 * Retrieves the set of attachments defined for this operation, as a 176 * mapping between the attachment name and the associated object. 177 * 178 * @return The set of attachments defined for this operation. 179 */ 180 Map<String,Object> getAttachments(); 181 182 183 184 /** 185 * Retrieves the attachment with the specified name. 186 * 187 * @param <T> the type of the attached object 188 * @param name The name for the attachment to retrieve. It will 189 * be treated in a case-sensitive manner. 190 * 191 * @return The requested attachment object, or <CODE>null</CODE> if 192 * it does not exist. 193 */ 194 <T> T getAttachment(String name); 195 196 197 198 /** 199 * Removes the attachment with the specified name. 200 * 201 * @param <T> the type of the attached object 202 * @param name The name for the attachment to remove. It will be 203 * treated in a case-sensitive manner. 204 * 205 * @return The attachment that was removed, or <CODE>null</CODE> if 206 * it does not exist. 207 */ 208 <T> T removeAttachment(String name); 209 210 211 212 /** 213 * Sets the value of the specified attachment. If an attachment 214 * already exists with the same name, it will be replaced. 215 * Otherwise, a new attachment will be added. 216 * 217 * @param <T> the type of the attached object 218 * @param name The name to use for the attachment. 219 * @param value The value to use for the attachment. 220 * 221 * @return The former value held by the attachment with the given 222 * name, or <CODE>null</CODE> if there was previously no 223 * such attachment. 224 */ 225 <T> T setAttachment(String name, Object value); 226 227 228 229 /** 230 * Retrieves the time that processing started for this operation. 231 * 232 * @return The time that processing started for this operation. 233 */ 234 long getProcessingStartTime(); 235 236 237 238 /** 239 * Retrieves a string representation of this operation. 240 * 241 * @return A string representation of this operation. 242 */ 243 @Override 244 String toString(); 245 246 247 248 /** 249 * Appends a string representation of this operation to the provided 250 * buffer. 251 * 252 * @param buffer The buffer into which a string representation of 253 * this operation should be appended. 254 */ 255 void toString(StringBuilder buffer); 256 257 258 259 /** 260 * Checks to see if this operation requested to cancel in which case 261 * CanceledOperationException will be thrown. 262 * 263 * @param signalTooLate <code>true</code> to signal that any further 264 * cancel requests will be too late after 265 * return from this call or <code>false</code> 266 * otherwise. 267 * 268 * @throws CanceledOperationException if this operation should 269 * be cancelled. 270 */ 271 void checkIfCanceled(boolean signalTooLate) throws CanceledOperationException; 272} 273