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;
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.messages.MessageBuilder;
037    
038    
039    /**
040     * This interface defines a generic operation that may be processed by
041     * the Directory Server.  Specific subclasses should implement
042     * specific functionality appropriate for the type of operation.
043     * <BR><BR>
044     * Note that this class is not intended to be subclassed by any
045     * third-party code outside of the OpenDS project.  It should only be
046     * extended by the operation types included in the
047     * {@code org.opends.server.core} package.
048     */
049    @org.opends.server.types.PublicAPI(
050         stability=org.opends.server.types.StabilityLevel.VOLATILE,
051         mayInstantiate=false,
052         mayExtend=false,
053         mayInvoke=true)
054    public interface Operation
055    {
056      /**
057       * Identifier used to get the local operation [if any] in the
058       * attachments.
059       */
060      public static final String LOCALBACKENDOPERATIONS =
061        "LocalBackendOperations";
062    
063      /**
064       * Retrieves the operation type for this operation.
065       *
066       * @return  The operation type for this operation.
067       */
068      public abstract OperationType getOperationType();
069    
070      /**
071       * Terminates the client connection being used to process this
072       * operation.  If this is called by a plugin, then that plugin must
073       * return a result indicating that the  client connection has been
074       * teriminated.
075       *
076       * @param  disconnectReason  The disconnect reason that provides the
077       *                           generic cause for the disconnect.
078       * @param  sendNotification  Indicates whether to try to provide
079       *                           notification
080       *                           to the client that the connection will
081       *                           be closed.
082       * @param  message           The message to send to the client.  It
083       *                           may be {@code null} if no notification
084       *                           is to be sent.
085       */
086      public abstract void disconnectClient(
087              DisconnectReason disconnectReason,
088              boolean sendNotification, Message message
089      );
090    
091      /**
092       * Retrieves a set of standard elements that should be logged in all
093       * requests and responses for all types of operations.  Each element
094       * in the array will itself be a two-element array in which the
095       * first element is the name of the field and the second is a string
096       * representation of the value, or {@code null} if there is no value
097       * for that field.
098       *
099       * @return  A standard set of elements that should be logged in
100       *          requests and responses for all types of operations.
101       */
102      public abstract String[][] getCommonLogElements();
103    
104      /**
105       * Retrieves a standard set of elements that should be logged in
106       * requests for this type of operation.  Each element in the array
107       * will itself be a two-element array in which the first element is
108       * the name of the field and the second is a string representation
109       * of the value, or {@code null} if there is no value for that
110       * field.
111       *
112       * @return  A standard set of elements that should be logged in
113       *          requests for this type of operation.
114       */
115      public abstract String[][] getRequestLogElements();
116    
117      /**
118       * Retrieves a standard set of elements that should be logged in
119       * responses for this type of operation.  Each element in the array
120       * will itself be a two-element array in which the first element is
121       * the name of the field and the second is a string representation
122       * of the value, or {@code null} if there is no value for that
123       * field.
124       *
125       * @return  A standard set of elements that should be logged in
126       *          responses for this type of operation.
127       */
128      public abstract String[][] getResponseLogElements();
129    
130      /**
131       * Retrieves the client connection with which this operation is
132       * associated.
133       *
134       * @return  The client connection with which this operation is
135       *          associated.
136       */
137      public abstract ClientConnection getClientConnection();
138    
139      /**
140       * Retrieves the unique identifier that is assigned to the client
141       * connection that submitted this operation.
142       *
143       * @return  The unique identifier that is assigned to the client
144       *          connection that submitted this operation.
145       */
146      public abstract long getConnectionID();
147    
148      /**
149       * Retrieves the operation ID for this operation.
150       *
151       * @return  The operation ID for this operation.
152       */
153      public abstract long getOperationID();
154    
155      /**
156       * Retrieves the message ID assigned to this operation.
157       *
158       * @return  The message ID assigned to this operation.
159       */
160      public abstract int getMessageID();
161    
162      /**
163       * Retrieves the set of controls included in the request from the
164       * client.  The returned list must not be altered.
165       *
166       * @return  The set of controls included in the request from the
167       *          client.
168       */
169      public abstract List<Control> getRequestControls();
170    
171      /**
172       * Adds the provided control to the set of request controls for this
173       * operation.  This method may only be called by pre-parse plugins.
174       *
175       * @param  control  The control to add to the set of request
176       *                  controls for this operation.
177       */
178      public abstract void addRequestControl(Control control);
179    
180      /**
181       * Removes the provided control from the set of request controls for
182       * this operation.  This method may only be called by pre-parse
183       * plugins.
184       *
185       * @param  control  The control to remove from the set of request
186       *                  controls for this operation.
187       */
188      public abstract void removeRequestControl(Control control);
189    
190      /**
191       * Retrieves the set of controls to include in the response to the
192       * client.  The contents of this list must not be altered.
193       *
194       * @return  The set of controls to include in the response to the
195       *          client.
196       */
197      public abstract List<Control> getResponseControls();
198    
199      /**
200       * Adds the provided control to the set of controls to include in
201       * the response to the client.  This method may not be called by
202       * post-response plugins.
203       *
204       * @param  control  The control to add to the set of controls to
205       *                  include in the response to the client.
206       */
207      public abstract void addResponseControl(Control control);
208    
209      /**
210       * Removes the provided control from the set of controls to include
211       * in the response to the client.  This method may not be called by
212       * post-response plugins.
213       *
214       * @param  control  The control to remove from the set of controls
215       *                  to include in the response to the client.
216       */
217      public abstract void removeResponseControl(Control control);
218    
219      /**
220       * Retrieves the result code for this operation.
221       *
222       * @return  The result code associated for this operation, or
223       *          {@code UNDEFINED} if the operation has not yet
224       *          completed.
225       */
226      public abstract ResultCode getResultCode();
227    
228      /**
229       * Specifies the result code for this operation.  This method may
230       * not be called by post-response plugins.
231       *
232       * @param  resultCode  The result code for this operation.
233       */
234      public abstract void setResultCode(ResultCode resultCode);
235    
236      /**
237       * Retrieves the error message for this operation.  Its contents may
238       * be altered by pre-parse, pre-operation, and post-operation
239       * plugins, but not by post-response plugins.
240       *
241       * @return  The error message for this operation.
242       */
243      public abstract MessageBuilder getErrorMessage();
244    
245      /**
246       * Specifies the error message for this operation.  This method may
247       * not be called by post-response plugins.
248       *
249       * @param  errorMessage  The error message for this operation.
250       */
251      public abstract void setErrorMessage(MessageBuilder errorMessage);
252    
253      /**
254       * Appends the provided message to the error message buffer.  If the
255       * buffer has not yet been created, then this will create it first
256       * and then add the provided message.  This method may not be called
257       * by post-response plugins.
258       *
259       * @param  message  The message to append to the error message
260       */
261      public abstract void appendErrorMessage(Message message);
262    
263      /**
264       * Retrieves the additional log message for this operation, which
265       * should be written to the log but not included in the response to
266       * the client.  The contents of this buffer may be altered by
267       * pre-parse, pre-operation, and post-operation plugins, but not by
268       * post-response plugins.
269       *
270       * @return  The additional log message for this operation.
271       */
272      public abstract MessageBuilder getAdditionalLogMessage();
273    
274      /**
275       * Specifies the additional log message for this operation, which
276       * should be written to the log but not included in the response to
277       * the client.  This method may not be called by post-response
278       * plugins.
279       *
280       * @param  additionalLogMessage  The additional log message for this
281       */
282      public abstract void setAdditionalLogMessage(
283          MessageBuilder additionalLogMessage);
284    
285      /**
286       * Appends the provided message to the additional log information
287       * for this operation.  This method may not be called by
288       * post-response plugins.
289       *
290       * @param  message  The message that should be appended to the
291       */
292      public abstract void appendAdditionalLogMessage(Message message);
293    
294      /**
295       * Retrieves the matched DN for this operation.
296       *
297       * @return  The matched DN for this operation, or {@code null} if
298       *          the operation has not yet completed or does not have a
299       *          matched DN.
300       */
301      public abstract DN getMatchedDN();
302    
303      /**
304       * Specifies the matched DN for this operation.  This may not be
305       * called by post-response plugins.
306       *
307       * @param  matchedDN  The matched DN for this operation.
308       */
309      public abstract void setMatchedDN(DN matchedDN);
310    
311      /**
312       * Retrieves the set of referral URLs for this operation.  Its
313       * contents must not be altered by the caller.
314       *
315       * @return  The set of referral URLs for this operation, or
316       *          {@code null} if the operation is not yet complete or
317       *          does not have a set of referral URLs.
318       */
319      public abstract List<String> getReferralURLs();
320    
321      /**
322       * Specifies the set of referral URLs for this operation.  This may
323       * not be called by post-response plugins.
324       *
325       * @param  referralURLs  The set of referral URLs for this
326       *                       operation.
327       */
328      public abstract void setReferralURLs(List<String> referralURLs);
329    
330      /**
331       * Sets the response elements for this operation based on the
332       * information contained in the provided {@code DirectoryException}
333       * object.  This method may not be called by post-response plugins.
334       *
335       * @param  directoryException  The exception containing the
336       *                             information to use for the response
337       *                             elements.
338       */
339      public abstract void setResponseData(
340          DirectoryException directoryException);
341    
342      /**
343       * Indicates whether this is an internal operation rather than one
344       * that was requested by an external client.
345       *
346       * @return  {@code true} if this is an internal operation, or
347       *          {@code false} if it is not.
348       */
349      public abstract boolean isInternalOperation();
350    
351      /**
352       * Specifies whether this is an internal operation rather than one
353       * that was requested by an external client.  This may not be called
354       * from within a plugin.
355       *
356       * @param  isInternalOperation  Specifies whether this is an
357       *                              internal operation rather than one
358       *                              that was requested by an external
359       *                              client.
360       */
361      public abstract void setInternalOperation(boolean
362          isInternalOperation);
363    
364      /**
365       * Indicates whether this is a synchronization operation rather than
366       * one that was requested by an external client.
367       *
368       * @return  {@code true} if this is a data synchronization
369       *          operation, or {@code false} if it is not.
370       */
371      public abstract boolean isSynchronizationOperation();
372    
373      /**
374       * Specifies whether this is a synchronization operation rather than
375       * one that was requested by an external client.  This method may
376       * not be called from within a plugin.
377       *
378       * @param  isSynchronizationOperation  Specifies whether this is a
379       *                                     synchronization operation
380       *                                     rather than one that was
381       *                                     requested by an external
382       *                                     client.
383       */
384      public abstract void setSynchronizationOperation(
385          boolean isSynchronizationOperation);
386    
387      /**
388       * Specifies whether this operation must be synchronized to other
389       * copies of the data.
390       *
391       * @param  dontSynchronize  Specifies whether this operation must be
392       *                          synchronized to other copies
393       *                          of the data.
394       */
395      public abstract void setDontSynchronize(boolean dontSynchronize);
396    
397      /**
398       * Retrieves the entry for the user that should be considered the
399       * authorization identity for this operation.  In many cases, it
400       * will be the same as the authorization entry for the underlying
401       * client connection, or {@code null} if no authentication has been
402       * performed on that connection.  However, it may be some other
403       * value if special processing has been requested (e.g., the
404       * operation included a proxied authorization control).  This method
405       * should not be called by pre-parse plugins because the correct
406       * value may not yet have been determined.
407       *
408       * @return  The entry for the user that should be considered the
409       *          authorization identity for this operation, or
410       *          {@code null} if the authorization identity should be the
411       *          unauthenticated  user.
412       */
413      public abstract Entry getAuthorizationEntry();
414    
415      /**
416       * Provides the entry for the user that should be considered the
417       * authorization identity for this operation.  This must not be
418       * called from within a plugin.
419       *
420       * @param  authorizationEntry  The entry for the user that should be
421       *                             considered the authorization identity
422       *                             for this operation, or {@code null}
423       *                             if it should be the unauthenticated
424       *                             user.
425       */
426      public abstract void setAuthorizationEntry(Entry
427          authorizationEntry);
428    
429      /**
430       * Retrieves the authorization DN for this operation.  In many
431       * cases, it will be the same as the DN of the authenticated user
432       * for the underlying connection, or the null DN if no
433       * authentication has been performed on that connection.  However,
434       * it may be some other value if special processing has been
435       * requested (e.g., the operation included a proxied authorization
436       * control).  This method should not be called by pre-parse plugins
437       * because the correct value may not have yet been determined.
438       *
439       * @return  The authorization DN for this operation, or the null DN
440       *          if it should be the unauthenticated user..
441       */
442      public abstract DN getAuthorizationDN();
443    
444      /**
445       * Retrieves the set of attachments defined for this operation, as a
446       * mapping between the attachment name and the associated object.
447       *
448       * @return  The set of attachments defined for this operation.
449       */
450      public abstract Map<String, Object> getAttachments();
451    
452      /**
453       * Retrieves the attachment with the specified name.
454       *
455       * @param  name  The name for the attachment to retrieve.  It will
456       *               be treated in a case-sensitive manner.
457       *
458       * @return  The requested attachment object, or {@code null} if it
459       *          does not exist.
460       */
461      public abstract Object getAttachment(String name);
462    
463      /**
464       * Removes the attachment with the specified name.
465       *
466       * @param  name  The name for the attachment to remove.  It will be
467       *               treated in a case-sensitive manner.
468       *
469       * @return  The attachment that was removed, or {@code null} if it
470       *          does not exist.
471       */
472      public abstract Object removeAttachment(String name);
473    
474      /**
475       * Sets the value of the specified attachment.  If an attachment
476       * already exists with the same name, it will be replaced.
477       * Otherwise, a new attachment will be added.
478       *
479       * @param  name   The name to use for the attachment.
480       * @param  value  The value to use for the attachment.
481       *
482       * @return  The former value held by the attachment with the given
483       *          name, or {@code null} if there was previously no such
484       *          attachment.
485       */
486      public abstract Object setAttachment(String name, Object value);
487    
488      /**
489       * Retrieves the time that processing started for this operation.
490       *
491       * @return  The time that processing started for this operation.
492       */
493      public abstract long getProcessingStartTime();
494    
495      /**
496       * Retrieves the time that processing stopped for this operation.
497       * This will actually hold a time immediately before the response
498       * was sent to the client.
499       *
500       * @return  The time that processing stopped for this operation.
501       */
502      public abstract long getProcessingStopTime();
503    
504      /**
505       * Retrieves the length of time in milliseconds that the server
506       * spent processing this operation.  This should not be called until
507       * after the server has sent the response to the client.
508       *
509       * @return  The length of time in milliseconds that the server spent
510       *          processing this operation.
511       */
512      public abstract long getProcessingTime();
513    
514      /**
515       * Retrieves the length of time in nanoseconds that
516       * the server spent processing this operation if available.
517       * This should not be called until after the server has sent the
518       * response to the client.
519       *
520       * @return  The length of time in nanoseconds that the server
521       *          spent processing this operation or -1 if its not
522       *          available.
523       */
524      public abstract long getProcessingNanoTime();
525    
526      /**
527       * Indicates that processing on this operation has completed
528       * successfully and that the client should perform any associated
529       * cleanup work.
530       */
531      public abstract void operationCompleted();
532    
533      /**
534       * Attempts to cancel this operation before processing has
535       * completed.
536       *
537       * @param  cancelRequest  Information about the way in which the
538       *                        operation should be canceled.
539       *
540       * @return  A code providing information on the result of the
541       *          cancellation.
542       */
543      public abstract CancelResult cancel(CancelRequest cancelRequest);
544    
545      /**
546       * Attempts to abort this operation before processing has
547       * completed.
548       *
549       * @param  cancelRequest  Information about the way in which the
550       *                        operation should be canceled.
551       */
552      public abstract void abort(CancelRequest cancelRequest);
553    
554    
555      /**
556       * Retrieves the cancel request that has been issued for this
557       * operation, if there is one.  This method should not be called by
558       * post-operation or post-response plugins.
559       *
560       * @return  The cancel request that has been issued for this
561       *          operation, or {@code null} if there has not been any
562       *          request to cancel.
563       */
564      public abstract CancelRequest getCancelRequest();
565    
566      /**
567       * Retrieves the cancel result for this operation.
568       *
569       * @return  The cancel result for this operation.  It will be
570       *          {@code null} if the operation has not seen and reacted
571       *          to a cancel request.
572       */
573      public abstract CancelResult getCancelResult();
574    
575      /**
576       * Retrieves a string representation of this operation.
577       *
578       * @return  A string representation of this operation.
579       */
580      public abstract String toString();
581    
582      /**
583       * Appends a string representation of this operation to the provided
584       * buffer.
585       *
586       * @param  buffer  The buffer into which a string representation of
587       *                 this operation should be appended.
588       */
589      public abstract void toString(StringBuilder buffer);
590    
591      /**
592       * Indicates whether this operation needs to be synchronized to
593       * other copies of the data.
594       *
595       * @return  {@code true} if this operation should not be
596       *          synchronized, or {@code false} if it should be
597       *          synchronized.
598       */
599      public abstract boolean dontSynchronize();
600    
601      /**
602       * Set the attachments to the operation.
603       *
604       * @param attachments - Attachments to register within the
605       *                      operation
606       */
607      public abstract void setAttachments(Map<String,
608          Object> attachments);
609    
610      /**
611       * Checks to see if this operation requested to cancel in which case
612       * CanceledOperationException will be thrown.
613       *
614       * @param signalTooLate <code>true</code> to signal that any further
615       *                      cancel requests will be too late after
616       *                      return from this call or <code>false</code>
617       *                      otherwise.
618       *
619       * @throws CanceledOperationException if this operation should
620       * be cancelled.
621       */
622      public void checkIfCanceled(boolean signalTooLate)
623          throws CanceledOperationException;
624    
625    }
626