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