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 import java.util.Map; 034 035 import org.opends.server.api.ClientConnection; 036 import org.opends.server.types.*; 037 038 039 /** 040 * This class defines a set of methods that are available for use by 041 * all types of plugins involved in operation processing (pre-parse, 042 * pre-operation, post-operation, post-response, search result entry, 043 * search result reference, and intermediate response). Note that 044 * this interface is intended only to define an API for use by plugins 045 * and 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) 052 public interface PluginOperation 053 { 054 /** 055 * Retrieves the operation type for this operation. 056 * 057 * @return The operation type for this operation. 058 */ 059 public OperationType getOperationType(); 060 061 062 063 /** 064 * Retrieves the client connection with which this operation is 065 * associated. 066 * 067 * @return The client connection with which this operation is 068 * associated. 069 */ 070 public ClientConnection getClientConnection(); 071 072 073 074 /** 075 * Terminates the client connection being used to process this 076 * operation. The plugin must return a result indicating that the 077 * client connection has been teriminated. 078 * 079 * @param disconnectReason The disconnect reason that provides the 080 * generic cause for the disconnect. 081 * @param sendNotification Indicates whether to try to provide 082 * notification to the client that the 083 * connection will be closed. 084 * @param message The message to send to the client. It 085 * may be <CODE>null</CODE> if no 086 * notification is to be sent. 087 */ 088 public void disconnectClient(DisconnectReason disconnectReason, 089 boolean sendNotification, 090 Message 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 public 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 public 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 public 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 public List<Control> getRequestControls(); 131 132 133 134 /** 135 * Retrieves the set of controls to include in the response to the 136 * client. The contents of this list must not be altered. 137 * 138 * @return The set of controls to include in the response to the 139 * client. 140 */ 141 public List<Control> getResponseControls(); 142 143 144 145 /** 146 * Indicates whether this is an internal operation rather than one 147 * that was requested by an external client. 148 * 149 * @return <CODE>true</CODE> if this is an internal operation, or 150 * <CODE>false</CODE> if it is not. 151 */ 152 public boolean isInternalOperation(); 153 154 155 156 /** 157 * Indicates whether this is a synchronization operation rather than 158 * one that was requested by an external client. 159 * 160 * @return <CODE>true</CODE> if this is a data synchronization 161 * operation, or <CODE>false</CODE> if it is not. 162 */ 163 public boolean isSynchronizationOperation(); 164 165 166 167 /** 168 * Retrieves the set of attachments defined for this operation, as a 169 * mapping between the attachment name and the associated object. 170 * 171 * @return The set of attachments defined for this operation. 172 */ 173 public Map<String,Object> getAttachments(); 174 175 176 177 /** 178 * Retrieves the attachment with the specified name. 179 * 180 * @param name The name for the attachment to retrieve. It will 181 * be treated in a case-sensitive manner. 182 * 183 * @return The requested attachment object, or <CODE>null</CODE> if 184 * it does not exist. 185 */ 186 public Object getAttachment(String name); 187 188 189 190 /** 191 * Removes the attachment with the specified name. 192 * 193 * @param name The name for the attachment to remove. It will be 194 * treated in a case-sensitive manner. 195 * 196 * @return The attachment that was removed, or <CODE>null</CODE> if 197 * it does not exist. 198 */ 199 public Object removeAttachment(String name); 200 201 202 203 /** 204 * Sets the value of the specified attachment. If an attachment 205 * already exists with the same name, it will be replaced. 206 * Otherwise, a new attachment will be added. 207 * 208 * @param name The name to use for the attachment. 209 * @param value The value to use for the attachment. 210 * 211 * @return The former value held by the attachment with the given 212 * name, or <CODE>null</CODE> if there was previously no 213 * such attachment. 214 */ 215 public Object setAttachment(String name, Object value); 216 217 218 219 /** 220 * Retrieves the time that processing started for this operation. 221 * 222 * @return The time that processing started for this operation. 223 */ 224 public long getProcessingStartTime(); 225 226 227 228 /** 229 * Retrieves a string representation of this operation. 230 * 231 * @return A string representation of this operation. 232 */ 233 public String toString(); 234 235 236 237 /** 238 * Appends a string representation of this operation to the provided 239 * buffer. 240 * 241 * @param buffer The buffer into which a string representation of 242 * this operation should be appended. 243 */ 244 public void toString(StringBuilder buffer); 245 246 247 248 /** 249 * Checks to see if this operation requested to cancel in which case 250 * CanceledOperationException will be thrown. 251 * 252 * @param signalTooLate <code>true</code> to signal that any further 253 * cancel requests will be too late after 254 * return from this call or <code>false</code> 255 * otherwise. 256 * 257 * @throws CanceledOperationException if this operation should 258 * be cancelled. 259 */ 260 public void checkIfCanceled(boolean signalTooLate) 261 throws CanceledOperationException; 262 } 263