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