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