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