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