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 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 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 * docs/licenses/cddl.txt. 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 * Portions Copyright 2010-2024 Ping Identity Corporation 026 */ 027package com.unboundid.directory.sdk.common.scripting; 028 029 030 031import java.security.cert.Certificate; 032import java.util.List; 033import java.util.Map; 034 035import com.unboundid.directory.sdk.broker.internal.BrokerExtension; 036import com.unboundid.directory.sdk.common.config.FileBasedAccessLoggerConfig; 037import com.unboundid.directory.sdk.common.internal.Reconfigurable; 038import com.unboundid.directory.sdk.common.operation.AbandonRequest; 039import com.unboundid.directory.sdk.common.operation.AddRequest; 040import com.unboundid.directory.sdk.common.operation.AddResult; 041import com.unboundid.directory.sdk.common.operation.BindResult; 042import com.unboundid.directory.sdk.common.operation.CompareRequest; 043import com.unboundid.directory.sdk.common.operation.CompareResult; 044import com.unboundid.directory.sdk.common.operation.DeleteRequest; 045import com.unboundid.directory.sdk.common.operation.DeleteResult; 046import com.unboundid.directory.sdk.common.operation.ExtendedRequest; 047import com.unboundid.directory.sdk.common.operation.ExtendedResult; 048import com.unboundid.directory.sdk.common.operation.GenericResult; 049import com.unboundid.directory.sdk.common.operation.ModifyRequest; 050import com.unboundid.directory.sdk.common.operation.ModifyResult; 051import com.unboundid.directory.sdk.common.operation.ModifyDNRequest; 052import com.unboundid.directory.sdk.common.operation.ModifyDNResult; 053import com.unboundid.directory.sdk.common.operation.SASLBindRequest; 054import com.unboundid.directory.sdk.common.operation.SearchRequest; 055import com.unboundid.directory.sdk.common.operation.SearchResult; 056import com.unboundid.directory.sdk.common.operation.SimpleBindRequest; 057import com.unboundid.directory.sdk.common.operation.UnbindRequest; 058import com.unboundid.directory.sdk.common.types.AssuredReplicationResult; 059import com.unboundid.directory.sdk.common.types.ClientContext; 060import com.unboundid.directory.sdk.common.types.CompletedOperationContext; 061import com.unboundid.directory.sdk.common.types.CompletedSearchOperationContext; 062import com.unboundid.directory.sdk.common.types.DisconnectReason; 063import com.unboundid.directory.sdk.common.types.Entry; 064import com.unboundid.directory.sdk.common.types.ForwardTarget; 065import com.unboundid.directory.sdk.common.types.OperationContext; 066import com.unboundid.directory.sdk.common.types.ServerContext; 067import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension; 068import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension; 069import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension; 070import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension; 071import com.unboundid.ldap.sdk.Control; 072import com.unboundid.ldap.sdk.IntermediateResponse; 073import com.unboundid.ldap.sdk.LDAPException; 074import com.unboundid.ldap.sdk.ResultCode; 075import com.unboundid.ldap.sdk.unboundidds.MoveSubtreeResult; 076import com.unboundid.util.Extensible; 077import com.unboundid.util.ThreadSafety; 078import com.unboundid.util.ThreadSafetyLevel; 079import com.unboundid.util.args.ArgumentException; 080import com.unboundid.util.args.ArgumentParser; 081 082 083 084/** 085 * This class defines an API that may be used to create a specific type of 086 * scripted access logger which is intended to write log messages to text files. 087 * This is a convenience for developers which wish to create custom access 088 * loggers that write to text files and provides support for a wide range of 089 * functionality including high-performance and highly-concurrent logging. All 090 * of the options available to {@link ScriptedAccessLogger} implementations are 091 * available for file-based access loggers, as well as options for indicating 092 * the log file path, the rotation and retention policies, whether to buffer the 093 * output, etc. 094 * <BR><BR> 095 * Note that scripted file-based access loggers will automatically be registered 096 * within the server as disk space consumers, so there is no need to implement 097 * the {@link com.unboundid.directory.sdk.common.api.DiskSpaceConsumer} 098 * interface. Also note that configuration change related to the log file 099 * (e.g., the log file path, buffer size, queue size, etc.) will also 100 * automatically be handled by the server, so subclasses only need to be 101 * concerned about changes to the custom arguments they define. 102 * <BR> 103 * <H2>Configuring File-Based Access Loggers</H2> 104 * In order to configure an access logger created using this API, use a command 105 * like: 106 * <PRE> 107 * dsconfig create-log-publisher \ 108 * --publisher-name "<I>{logger-name}</I>" \ 109 * --type groovy-scripted-file-based-access \ 110 * --set enabled:true \ 111 * --set "log-file:<I>{path}</I>" \ 112 * --set "rotation-policy:<I>{rotation-policy-name}</I>" \ 113 * --set "retention-policy:<I>{retention-policy-name}</I>" \ 114 * --set "script-class:<I>{class-name}</I>" \ 115 * --set "script-argument:<I>{name=value}</I>" 116 * </PRE> 117 * where "<I>{logger-name}</I>" is the name to use for the access logger 118 * instance, "<I>{path}</I>" is the path to the log file to be written, 119 * "<I>{rotation-policy-name}</I>" is the name of the log rotation policy to use 120 * for the log file, "<I>{retention-policy-name}</I>" is the name of the log 121 * retention policy to use for the log file, "<I>{class-name}</I>" is the 122 * fully-qualified name of the Groovy class written using this API, and 123 * "<I>{name=value}</I>" represents name-value pairs for any arguments to 124 * provide to the logger. If multiple arguments should be provided to the 125 * logger, then the "<CODE>--set script-argument:<I>{name=value}</I></CODE>" 126 * option should be provided multiple times. It is also possible to specify 127 * multiple log rotation and/or retention policies if desired. 128 * 129 * @see com.unboundid.directory.sdk.common.api.AccessLogger 130 * @see com.unboundid.directory.sdk.common.api.FileBasedAccessLogger 131 * @see ScriptedAccessLogger 132 */ 133@Extensible() 134@DirectoryServerExtension() 135@DirectoryProxyServerExtension(appliesToLocalContent=true, 136 appliesToRemoteContent=false) 137@SynchronizationServerExtension(appliesToLocalContent=true, 138 appliesToSynchronizedContent=false) 139@MetricsEngineExtension() 140@BrokerExtension() 141@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 142public abstract class ScriptedFileBasedAccessLogger 143 implements Reconfigurable<FileBasedAccessLoggerConfig> 144{ 145 /** 146 * Creates a new instance of this access logger. All access logger 147 * implementations must include a default constructor, but any initialization 148 * should generally be done in the {@code initializeAccessLogger} method. 149 */ 150 public ScriptedFileBasedAccessLogger() 151 { 152 // No implementation is required. 153 } 154 155 156 157 /** 158 * {@inheritDoc} 159 */ 160 public void defineConfigArguments(final ArgumentParser parser) 161 throws ArgumentException 162 { 163 // No arguments will be allowed by default. 164 } 165 166 167 168 /** 169 * Initializes this access logger. 170 * 171 * @param serverContext A handle to the server context for the server in 172 * which this extension is running. 173 * @param config The general configuration for this access logger. 174 * @param parser The argument parser which has been initialized from 175 * the configuration for this access logger. 176 * 177 * @throws LDAPException If a problem occurs while initializing this access 178 * logger. 179 */ 180 public void initializeAccessLogger(final ServerContext serverContext, 181 final FileBasedAccessLoggerConfig config, 182 final ArgumentParser parser) 183 throws LDAPException 184 { 185 // No initialization will be performed by default. 186 } 187 188 189 190 /** 191 * {@inheritDoc} 192 */ 193 public boolean isConfigurationAcceptable( 194 final FileBasedAccessLoggerConfig config, 195 final ArgumentParser parser, 196 final List<String> unacceptableReasons) 197 { 198 // No extended validation will be performed by default. 199 return true; 200 } 201 202 203 204 /** 205 * {@inheritDoc} 206 */ 207 public ResultCode applyConfiguration(final FileBasedAccessLoggerConfig config, 208 final ArgumentParser parser, 209 final List<String> adminActionsRequired, 210 final List<String> messages) 211 { 212 // By default, no configuration changes will be applied. If there are any 213 // arguments, then add an admin action message indicating that the extension 214 // needs to be restarted for any changes to take effect. 215 if (! parser.getNamedArguments().isEmpty()) 216 { 217 adminActionsRequired.add( 218 "No configuration change has actually been applied. The new " + 219 "configuration will not take effect until this access logger " + 220 "is disabled and re-enabled or until the server is restarted."); 221 } 222 223 return ResultCode.SUCCESS; 224 } 225 226 227 228 /** 229 * Performs any cleanup which may be necessary when this access logger is to 230 * be taken out of service. 231 */ 232 public void finalizeAccessLogger() 233 { 234 // No implementation is required. 235 } 236 237 238 239 /** 240 * Logs a message indicating that a new connection has been established. 241 * 242 * @param clientContext Information about the client connection that has 243 * been accepted. 244 * 245 * @return The content of the log message that should be written. It may be 246 * {@code null} or empty if no message should be written. It may 247 * optionally include line breaks if the log message should span 248 * multiple lines. 249 */ 250 public CharSequence logConnect(final ClientContext clientContext) 251 { 252 // No log message will be generated by default. 253 return null; 254 } 255 256 257 258 /** 259 * Logs a message indicating that a connection has been closed. 260 * 261 * @param clientContext Information about the client connection that has 262 * been closed. 263 * @param disconnectReason A general reason that the connection has been 264 * closed. 265 * @param message A message with additional information about the 266 * closure. It may be {@code null} if none is 267 * available. 268 * 269 * @return The content of the log message that should be written. It may be 270 * {@code null} or empty if no message should be written. It may 271 * optionally include line breaks if the log message should span 272 * multiple lines. 273 */ 274 public CharSequence logDisconnect(final ClientContext clientContext, 275 final DisconnectReason disconnectReason, 276 final String message) 277 { 278 // No log message will be generated by default. 279 return null; 280 } 281 282 283 284 /** 285 * Logs a message about security negotiation performed by a client. 286 * 287 * @param clientContext Information about the client connection on which 288 * the negotiation was completed. 289 * @param protocol The security protocol selected by the negotiation. 290 * It may be {@code null} if no protocol is available. 291 * @param cipher The cipher suite selected by the negotiation. It 292 * may be {@code null} if no cipher is available. 293 * @param properties A set of additional properties that may be included 294 * in the log message. It may be {@code null} or empty 295 * if no additional properties are needed. 296 * 297 * @return The content of the log message that should be written. It may be 298 * {@code null} or empty if no message should be written. It may 299 * optionally include line breaks if the log message should span 300 * multiple lines. 301 */ 302 public CharSequence logSecurityNegotiation(final ClientContext clientContext, 303 final String protocol, final String cipher, 304 final Map<String,String> properties) 305 { 306 // No log message will be generated by default. 307 return null; 308 } 309 310 311 312 /** 313 * Logs a message about a certificate chain presented by a client. 314 * 315 * @param clientContext Information about the client that presented the 316 * certificate chain. 317 * @param certChain The certificate chain presented by the client. 318 * @param authDN The DN of the user as whom the client was 319 * automatically authenticated, or {@code null} if the 320 * client was not automatically authenticated. 321 * 322 * @return The content of the log message that should be written. It may be 323 * {@code null} or empty if no message should be written. It may 324 * optionally include line breaks if the log message should span 325 * multiple lines. 326 */ 327 public CharSequence logClientCertificateChain( 328 final ClientContext clientContext, 329 final Certificate[] certChain, final String authDN) 330 { 331 // No log message will be generated by default. 332 return null; 333 } 334 335 336 337 /** 338 * Logs a message about an abandon request received from a client. 339 * 340 * @param opContext The operation context for the abandon operation. 341 * @param request The abandon request that was received. 342 * 343 * @return The content of the log message that should be written. It may be 344 * {@code null} or empty if no message should be written. It may 345 * optionally include line breaks if the log message should span 346 * multiple lines. 347 */ 348 public CharSequence logAbandonRequest(final OperationContext opContext, 349 final AbandonRequest request) 350 { 351 // No log message will be generated by default. 352 return null; 353 } 354 355 356 357 /** 358 * Logs a message about an abandon request that will be forwarded to another 359 * server. 360 * 361 * @param opContext The operation context for the abandon operation. 362 * @param request The abandon request that was received. 363 * @param target Information about the server to which the request will 364 * be forwarded. 365 * 366 * @return The content of the log message that should be written. It may be 367 * {@code null} or empty if no message should be written. It may 368 * optionally include line breaks if the log message should span 369 * multiple lines. 370 */ 371 public CharSequence logAbandonForward(final OperationContext opContext, 372 final AbandonRequest request, 373 final ForwardTarget target) 374 { 375 // No log message will be generated by default. 376 return null; 377 } 378 379 380 381 /** 382 * Logs a message about the result of processing an abandon request. 383 * 384 * @param opContext The operation context for the abandon operation. 385 * @param request The abandon request that was received. 386 * @param result The result of processing the abandon request. 387 * 388 * @return The content of the log message that should be written. It may be 389 * {@code null} or empty if no message should be written. It may 390 * optionally include line breaks if the log message should span 391 * multiple lines. 392 */ 393 public CharSequence logAbandonResult( 394 final CompletedOperationContext opContext, 395 final AbandonRequest request, 396 final GenericResult result) 397 { 398 // No log message will be generated by default. 399 return null; 400 } 401 402 403 404 /** 405 * Logs a message about an add request received from a client. 406 * 407 * @param opContext The operation context for the add operation. 408 * @param request The add request that was received. 409 * 410 * @return The content of the log message that should be written. It may be 411 * {@code null} or empty if no message should be written. It may 412 * optionally include line breaks if the log message should span 413 * multiple lines. 414 */ 415 public CharSequence logAddRequest(final OperationContext opContext, 416 final AddRequest request) 417 { 418 // No log message will be generated by default. 419 return null; 420 } 421 422 423 424 /** 425 * Logs a message about an add request that will be forwarded to another 426 * server. 427 * 428 * @param opContext The operation context for the add operation. 429 * @param request The add request that was received. 430 * @param target Information about the server to which the request will 431 * be forwarded. 432 * 433 * @return The content of the log message that should be written. It may be 434 * {@code null} or empty if no message should be written. It may 435 * optionally include line breaks if the log message should span 436 * multiple lines. 437 */ 438 public CharSequence logAddForward(final OperationContext opContext, 439 final AddRequest request, 440 final ForwardTarget target) 441 { 442 // No log message will be generated by default. 443 return null; 444 } 445 446 447 448 /** 449 * Logs a message about a failure encountered while attempting to forward an 450 * add request to another server. 451 * 452 * @param opContext The operation context for the add operation. 453 * @param request The add request that was received. 454 * @param target Information about the server to which the request was 455 * forwarded. 456 * @param failure The exception that was received when attempting to 457 * forward the request. 458 * 459 * @return The content of the log message that should be written. It may be 460 * {@code null} or empty if no message should be written. It may 461 * optionally include line breaks if the log message should span 462 * multiple lines. 463 */ 464 public CharSequence logAddForwardFailure(final OperationContext opContext, 465 final AddRequest request, 466 final ForwardTarget target, 467 final LDAPException failure) 468 { 469 // No log message will be generated by default. 470 return null; 471 } 472 473 474 475 /** 476 * Logs a message about the result of processing an add request. 477 * 478 * @param opContext The operation context for the add operation. 479 * @param request The add request that was received. 480 * @param result The result of processing the add request. 481 * 482 * @return The content of the log message that should be written. It may be 483 * {@code null} or empty if no message should be written. It may 484 * optionally include line breaks if the log message should span 485 * multiple lines. 486 */ 487 public CharSequence logAddResponse(final CompletedOperationContext opContext, 488 final AddRequest request, 489 final AddResult result) 490 { 491 // No log message will be generated by default. 492 return null; 493 } 494 495 496 497 /** 498 * Logs a message about the result of replication assurance processing for an 499 * add operation. 500 * 501 * @param opContext The operation context for the add operation. 502 * @param request The add request that was received. 503 * @param result The result of processing the add request. 504 * @param assuranceResult The replication assurance processing result. 505 * 506 * @return The content of the log message that should be written. It may be 507 * {@code null} or empty if no message should be written. It may 508 * optionally include line breaks if the log message should span 509 * multiple lines. 510 */ 511 public CharSequence logAddAssuranceCompleted( 512 final CompletedOperationContext opContext, 513 final AddRequest request, final AddResult result, 514 final AssuredReplicationResult assuranceResult) 515 { 516 // No log message will be generated by default. 517 return null; 518 } 519 520 521 522 /** 523 * Logs a message about a simple bind request received from a client. 524 * 525 * @param opContext The operation context for the bind operation. 526 * @param request The bind request that was received. 527 * 528 * @return The content of the log message that should be written. It may be 529 * {@code null} or empty if no message should be written. It may 530 * optionally include line breaks if the log message should span 531 * multiple lines. 532 */ 533 public CharSequence logBindRequest(final OperationContext opContext, 534 final SimpleBindRequest request) 535 { 536 // No log message will be generated by default. 537 return null; 538 } 539 540 541 542 /** 543 * Logs a message about a simple bind request that will be forwarded to 544 * another server. 545 * 546 * @param opContext The operation context for the bind operation. 547 * @param request The bind request that was received. 548 * @param target Information about the server to which the request will 549 * be forwarded. 550 * 551 * @return The content of the log message that should be written. It may be 552 * {@code null} or empty if no message should be written. It may 553 * optionally include line breaks if the log message should span 554 * multiple lines. 555 */ 556 public CharSequence logBindForward(final OperationContext opContext, 557 final SimpleBindRequest request, 558 final ForwardTarget target) 559 { 560 // No log message will be generated by default. 561 return null; 562 } 563 564 565 566 /** 567 * Logs a message about a failure encountered while attempting to forward a 568 * simple bind request to another server. 569 * 570 * @param opContext The operation context for the bind operation. 571 * @param request The bind request that was received. 572 * @param target Information about the server to which the request was 573 * forwarded. 574 * @param failure The exception that was received when attempting to 575 * forward the request. 576 * 577 * @return The content of the log message that should be written. It may be 578 * {@code null} or empty if no message should be written. It may 579 * optionally include line breaks if the log message should span 580 * multiple lines. 581 */ 582 public CharSequence logBindForwardFailure(final OperationContext opContext, 583 final SimpleBindRequest request, 584 final ForwardTarget target, 585 final LDAPException failure) 586 { 587 // No log message will be generated by default. 588 return null; 589 } 590 591 592 593 /** 594 * Logs a message about the result of processing a simple bind request. 595 * 596 * @param opContext The operation context for the bind operation. 597 * @param request The bind request that was received. 598 * @param result The result of processing the bind request. 599 * 600 * @return The content of the log message that should be written. It may be 601 * {@code null} or empty if no message should be written. It may 602 * optionally include line breaks if the log message should span 603 * multiple lines. 604 */ 605 public CharSequence logBindResponse(final CompletedOperationContext opContext, 606 final SimpleBindRequest request, 607 final BindResult result) 608 { 609 // No log message will be generated by default. 610 return null; 611 } 612 613 614 615 /** 616 * Logs a message about a SASL bind request received from a client. 617 * 618 * @param opContext The operation context for the bind operation. 619 * @param request The bind request that was received. 620 * 621 * @return The content of the log message that should be written. It may be 622 * {@code null} or empty if no message should be written. It may 623 * optionally include line breaks if the log message should span 624 * multiple lines. 625 */ 626 public CharSequence logBindRequest(final OperationContext opContext, 627 final SASLBindRequest request) 628 { 629 // No log message will be generated by default. 630 return null; 631 } 632 633 634 635 /** 636 * Logs a message about a SASL bind request that will be forwarded to 637 * another server. 638 * 639 * @param opContext The operation context for the bind operation. 640 * @param request The bind request that was received. 641 * @param target Information about the server to which the request will 642 * be forwarded. 643 * 644 * @return The content of the log message that should be written. It may be 645 * {@code null} or empty if no message should be written. It may 646 * optionally include line breaks if the log message should span 647 * multiple lines. 648 */ 649 public CharSequence logBindForward(final OperationContext opContext, 650 final SASLBindRequest request, 651 final ForwardTarget target) 652 { 653 // No log message will be generated by default. 654 return null; 655 } 656 657 658 659 /** 660 * Logs a message about a failure encountered while attempting to forward a 661 * SASL bind request to another server. 662 * 663 * @param opContext The operation context for the bind operation. 664 * @param request The bind request that was received. 665 * @param target Information about the server to which the request was 666 * forwarded. 667 * @param failure The exception that was received when attempting to 668 * forward the request. 669 * 670 * @return The content of the log message that should be written. It may be 671 * {@code null} or empty if no message should be written. It may 672 * optionally include line breaks if the log message should span 673 * multiple lines. 674 */ 675 public CharSequence logBindForwardFailure(final OperationContext opContext, 676 final SASLBindRequest request, 677 final ForwardTarget target, 678 final LDAPException failure) 679 { 680 // No log message will be generated by default. 681 return null; 682 } 683 684 685 686 /** 687 * Logs a message about the result of processing a SASL bind request. 688 * 689 * @param opContext The operation context for the bind operation. 690 * @param request The bind request that was received. 691 * @param result The result of processing the bind request. 692 * 693 * @return The content of the log message that should be written. It may be 694 * {@code null} or empty if no message should be written. It may 695 * optionally include line breaks if the log message should span 696 * multiple lines. 697 */ 698 public CharSequence logBindResponse(final CompletedOperationContext opContext, 699 final SASLBindRequest request, 700 final BindResult result) 701 { 702 // No log message will be generated by default. 703 return null; 704 } 705 706 707 708 /** 709 * Logs a message about a compare request received from a client. 710 * 711 * @param opContext The operation context for the compare operation. 712 * @param request The compare request that was received. 713 * 714 * @return The content of the log message that should be written. It may be 715 * {@code null} or empty if no message should be written. It may 716 * optionally include line breaks if the log message should span 717 * multiple lines. 718 */ 719 public CharSequence logCompareRequest(final OperationContext opContext, 720 final CompareRequest request) 721 { 722 // No log message will be generated by default. 723 return null; 724 } 725 726 727 728 /** 729 * Logs a message about a compare request that will be forwarded to another 730 * server. 731 * 732 * @param opContext The operation context for the compare operation. 733 * @param request The compare request that was received. 734 * @param target Information about the server to which the request will 735 * be forwarded. 736 * 737 * @return The content of the log message that should be written. It may be 738 * {@code null} or empty if no message should be written. It may 739 * optionally include line breaks if the log message should span 740 * multiple lines. 741 */ 742 public CharSequence logCompareForward(final OperationContext opContext, 743 final CompareRequest request, 744 final ForwardTarget target) 745 { 746 // No log message will be generated by default. 747 return null; 748 } 749 750 751 752 /** 753 * Logs a message about a failure encountered while attempting to forward a 754 * compare request to another server. 755 * 756 * @param opContext The operation context for the compare operation. 757 * @param request The compare request that was received. 758 * @param target Information about the server to which the request was 759 * forwarded. 760 * @param failure The exception that was received when attempting to 761 * forward the request. 762 * 763 * @return The content of the log message that should be written. It may be 764 * {@code null} or empty if no message should be written. It may 765 * optionally include line breaks if the log message should span 766 * multiple lines. 767 */ 768 public CharSequence logCompareForwardFailure(final OperationContext opContext, 769 final CompareRequest request, 770 final ForwardTarget target, 771 final LDAPException failure) 772 { 773 // No log message will be generated by default. 774 return null; 775 } 776 777 778 779 /** 780 * Logs a message about the result of processing a compare request. 781 * 782 * @param opContext The operation context for the compare operation. 783 * @param request The compare request that was received. 784 * @param result The result of processing the compare request. 785 * 786 * @return The content of the log message that should be written. It may be 787 * {@code null} or empty if no message should be written. It may 788 * optionally include line breaks if the log message should span 789 * multiple lines. 790 */ 791 public CharSequence logCompareResponse( 792 final CompletedOperationContext opContext, 793 final CompareRequest request, 794 final CompareResult result) 795 { 796 // No log message will be generated by default. 797 return null; 798 } 799 800 801 802 /** 803 * Logs a message about a delete request received from a client. 804 * 805 * @param opContext The operation context for the delete operation. 806 * @param request The delete request that was received. 807 * 808 * @return The content of the log message that should be written. It may be 809 * {@code null} or empty if no message should be written. It may 810 * optionally include line breaks if the log message should span 811 * multiple lines. 812 */ 813 public CharSequence logDeleteRequest(final OperationContext opContext, 814 final DeleteRequest request) 815 { 816 // No log message will be generated by default. 817 return null; 818 } 819 820 821 822 /** 823 * Logs a message about a delete request that will be forwarded to another 824 * server. 825 * 826 * @param opContext The operation context for the delete operation. 827 * @param request The delete request that was received. 828 * @param target Information about the server to which the request will 829 * be forwarded. 830 * 831 * @return The content of the log message that should be written. It may be 832 * {@code null} or empty if no message should be written. It may 833 * optionally include line breaks if the log message should span 834 * multiple lines. 835 */ 836 public CharSequence logDeleteForward(final OperationContext opContext, 837 final DeleteRequest request, 838 final ForwardTarget target) 839 { 840 // No log message will be generated by default. 841 return null; 842 } 843 844 845 846 /** 847 * Logs a message about a failure encountered while attempting to forward a 848 * delete request to another server. 849 * 850 * @param opContext The operation context for the delete operation. 851 * @param request The delete request that was received. 852 * @param target Information about the server to which the request was 853 * forwarded. 854 * @param failure The exception that was received when attempting to 855 * forward the request. 856 * 857 * @return The content of the log message that should be written. It may be 858 * {@code null} or empty if no message should be written. It may 859 * optionally include line breaks if the log message should span 860 * multiple lines. 861 */ 862 public CharSequence logDeleteForwardFailure(final OperationContext opContext, 863 final DeleteRequest request, 864 final ForwardTarget target, 865 final LDAPException failure) 866 { 867 // No log message will be generated by default. 868 return null; 869 } 870 871 872 873 /** 874 * Logs a message about the result of processing a delete request. 875 * 876 * @param opContext The operation context for the delete operation. 877 * @param request The delete request that was received. 878 * @param result The result of processing the delete request. 879 * 880 * @return The content of the log message that should be written. It may be 881 * {@code null} or empty if no message should be written. It may 882 * optionally include line breaks if the log message should span 883 * multiple lines. 884 */ 885 public CharSequence logDeleteResponse( 886 final CompletedOperationContext opContext, 887 final DeleteRequest request, 888 final DeleteResult result) 889 { 890 // No log message will be generated by default. 891 return null; 892 } 893 894 895 896 /** 897 * Logs a message about the result of replication assurance processing for a 898 * delete operation. 899 * 900 * @param opContext The operation context for the delete operation. 901 * @param request The delete request that was received. 902 * @param result The result of processing the delete request. 903 * @param assuranceResult The replication assurance processing result. 904 * 905 * @return The content of the log message that should be written. It may be 906 * {@code null} or empty if no message should be written. It may 907 * optionally include line breaks if the log message should span 908 * multiple lines. 909 */ 910 public CharSequence logDeleteAssuranceCompleted( 911 final CompletedOperationContext opContext, 912 final DeleteRequest request, 913 final DeleteResult result, 914 final AssuredReplicationResult assuranceResult) 915 { 916 // No log message will be generated by default. 917 return null; 918 } 919 920 921 922 /** 923 * Logs a message about an extended request received from a client. 924 * 925 * @param opContext The operation context for the extended operation. 926 * @param request The extended request that was received. 927 * 928 * @return The content of the log message that should be written. It may be 929 * {@code null} or empty if no message should be written. It may 930 * optionally include line breaks if the log message should span 931 * multiple lines. 932 */ 933 public CharSequence logExtendedRequest(final OperationContext opContext, 934 final ExtendedRequest request) 935 { 936 // No log message will be generated by default. 937 return null; 938 } 939 940 941 942 /** 943 * Logs a message about an extended request that will be forwarded to another 944 * server. 945 * 946 * @param opContext The operation context for the extended operation. 947 * @param request The extended request that was received. 948 * @param target Information about the server to which the request will 949 * be forwarded. 950 * 951 * @return The content of the log message that should be written. It may be 952 * {@code null} or empty if no message should be written. It may 953 * optionally include line breaks if the log message should span 954 * multiple lines. 955 */ 956 public CharSequence logExtendedForward(final OperationContext opContext, 957 final ExtendedRequest request, 958 final ForwardTarget target) 959 { 960 // No log message will be generated by default. 961 return null; 962 } 963 964 965 966 /** 967 * Logs a message about a failure encountered while attempting to forward an 968 * extended request to another server. 969 * 970 * @param opContext The operation context for the extended operation. 971 * @param request The extended request that was received. 972 * @param target Information about the server to which the request was 973 * forwarded. 974 * @param failure The exception that was received when attempting to 975 * forward the request. 976 * 977 * @return The content of the log message that should be written. It may be 978 * {@code null} or empty if no message should be written. It may 979 * optionally include line breaks if the log message should span 980 * multiple lines. 981 */ 982 public CharSequence logExtendedForwardFailure( 983 final OperationContext opContext, 984 final ExtendedRequest request, 985 final ForwardTarget target, 986 final LDAPException failure) 987 { 988 // No log message will be generated by default. 989 return null; 990 } 991 992 993 994 /** 995 * Logs a message about the result of processing an extended request. 996 * 997 * @param opContext The operation context for the extended operation. 998 * @param request The extended request that was received. 999 * @param result The result of processing the extended request. 1000 * 1001 * @return The content of the log message that should be written. It may be 1002 * {@code null} or empty if no message should be written. It may 1003 * optionally include line breaks if the log message should span 1004 * multiple lines. 1005 */ 1006 public CharSequence logExtendedResponse( 1007 final CompletedOperationContext opContext, 1008 final ExtendedRequest request, 1009 final ExtendedResult result) 1010 { 1011 // No log message will be generated by default. 1012 return null; 1013 } 1014 1015 1016 1017 /** 1018 * Logs a message about a modify request received from a client. 1019 * 1020 * @param opContext The operation context for the modify operation. 1021 * @param request The modify request that was received. 1022 * 1023 * @return The content of the log message that should be written. It may be 1024 * {@code null} or empty if no message should be written. It may 1025 * optionally include line breaks if the log message should span 1026 * multiple lines. 1027 */ 1028 public CharSequence logModifyRequest(final OperationContext opContext, 1029 final ModifyRequest request) 1030 { 1031 // No log message will be generated by default. 1032 return null; 1033 } 1034 1035 1036 1037 /** 1038 * Logs a message about a modify request that will be forwarded to another 1039 * server. 1040 * 1041 * @param opContext The operation context for the modify operation. 1042 * @param request The modify request that was received. 1043 * @param target Information about the server to which the request will 1044 * be forwarded. 1045 * 1046 * @return The content of the log message that should be written. It may be 1047 * {@code null} or empty if no message should be written. It may 1048 * optionally include line breaks if the log message should span 1049 * multiple lines. 1050 */ 1051 public CharSequence logModifyForward(final OperationContext opContext, 1052 final ModifyRequest request, 1053 final ForwardTarget target) 1054 { 1055 // No log message will be generated by default. 1056 return null; 1057 } 1058 1059 1060 1061 /** 1062 * Logs a message about a failure encountered while attempting to forward a 1063 * modify request to another server. 1064 * 1065 * @param opContext The operation context for the modify operation. 1066 * @param request The modify request that was received. 1067 * @param target Information about the server to which the request was 1068 * forwarded. 1069 * @param failure The exception that was received when attempting to 1070 * forward the request. 1071 * 1072 * @return The content of the log message that should be written. It may be 1073 * {@code null} or empty if no message should be written. It may 1074 * optionally include line breaks if the log message should span 1075 * multiple lines. 1076 */ 1077 public CharSequence logModifyForwardFailure(final OperationContext opContext, 1078 final ModifyRequest request, 1079 final ForwardTarget target, 1080 final LDAPException failure) 1081 { 1082 // No log message will be generated by default. 1083 return null; 1084 } 1085 1086 1087 1088 /** 1089 * Logs a message about the result of processing a modify request. 1090 * 1091 * @param opContext The operation context for the modify operation. 1092 * @param request The modify request that was received. 1093 * @param result The result of processing the modify request. 1094 * 1095 * @return The content of the log message that should be written. It may be 1096 * {@code null} or empty if no message should be written. It may 1097 * optionally include line breaks if the log message should span 1098 * multiple lines. 1099 */ 1100 public CharSequence logModifyResponse( 1101 final CompletedOperationContext opContext, 1102 final ModifyRequest request, 1103 final ModifyResult result) 1104 { 1105 // No log message will be generated by default. 1106 return null; 1107 } 1108 1109 1110 1111 /** 1112 * Logs a message about the result of replication assurance processing for a 1113 * modify operation. 1114 * 1115 * @param opContext The operation context for the modify operation. 1116 * @param request The modify request that was received. 1117 * @param result The result of processing the modify request. 1118 * @param assuranceResult The replication assurance processing result. 1119 * 1120 * @return The content of the log message that should be written. It may be 1121 * {@code null} or empty if no message should be written. It may 1122 * optionally include line breaks if the log message should span 1123 * multiple lines. 1124 */ 1125 public CharSequence logModifyAssuranceCompleted( 1126 final CompletedOperationContext opContext, 1127 final ModifyRequest request, 1128 final ModifyResult result, 1129 final AssuredReplicationResult assuranceResult) 1130 { 1131 // No log message will be generated by default. 1132 return null; 1133 } 1134 1135 1136 1137 /** 1138 * Logs a message about a modify DN request received from a client. 1139 * 1140 * @param opContext The operation context for the modify DN operation. 1141 * @param request The modify DN request that was received. 1142 * 1143 * @return The content of the log message that should be written. It may be 1144 * {@code null} or empty if no message should be written. It may 1145 * optionally include line breaks if the log message should span 1146 * multiple lines. 1147 */ 1148 public CharSequence logModifyDNRequest(final OperationContext opContext, 1149 final ModifyDNRequest request) 1150 { 1151 // No log message will be generated by default. 1152 return null; 1153 } 1154 1155 1156 1157 /** 1158 * Logs a message about a modify DN request that will be forwarded to another 1159 * server. 1160 * 1161 * @param opContext The operation context for the modify DN operation. 1162 * @param request The modify DN request that was received. 1163 * @param target Information about the server to which the request will 1164 * be forwarded. 1165 * 1166 * @return The content of the log message that should be written. It may be 1167 * {@code null} or empty if no message should be written. It may 1168 * optionally include line breaks if the log message should span 1169 * multiple lines. 1170 */ 1171 public CharSequence logModifyDNForward(final OperationContext opContext, 1172 final ModifyDNRequest request, 1173 final ForwardTarget target) 1174 { 1175 // No log message will be generated by default. 1176 return null; 1177 } 1178 1179 1180 1181 /** 1182 * Logs a message about a failure encountered while attempting to forward a 1183 * modify DN request to another server. 1184 * 1185 * @param opContext The operation context for the modify DN operation. 1186 * @param request The modify DN request that was received. 1187 * @param target Information about the server to which the request was 1188 * forwarded. 1189 * @param failure The exception that was received when attempting to 1190 * forward the request. 1191 * 1192 * @return The content of the log message that should be written. It may be 1193 * {@code null} or empty if no message should be written. It may 1194 * optionally include line breaks if the log message should span 1195 * multiple lines. 1196 */ 1197 public CharSequence logModifyDNForwardFailure( 1198 final OperationContext opContext, 1199 final ModifyDNRequest request, 1200 final ForwardTarget target, 1201 final LDAPException failure) 1202 { 1203 // No log message will be generated by default. 1204 return null; 1205 } 1206 1207 1208 1209 /** 1210 * Logs a message about the result of processing a modify DN request. 1211 * 1212 * @param opContext The operation context for the modify DN operation. 1213 * @param request The modify DN request that was received. 1214 * @param result The result of processing the modify DN request. 1215 * 1216 * @return The content of the log message that should be written. It may be 1217 * {@code null} or empty if no message should be written. It may 1218 * optionally include line breaks if the log message should span 1219 * multiple lines. 1220 */ 1221 public CharSequence logModifyDNResponse( 1222 final CompletedOperationContext opContext, 1223 final ModifyDNRequest request, 1224 final ModifyDNResult result) 1225 { 1226 // No log message will be generated by default. 1227 return null; 1228 } 1229 1230 1231 1232 /** 1233 * Logs a message about the result of replication assurance processing for a 1234 * modify DN operation. 1235 * 1236 * @param opContext The operation context for the modify DN operation. 1237 * @param request The modify DN request that was received. 1238 * @param result The result of processing the modify DN request. 1239 * @param assuranceResult The replication assurance processing result. 1240 * 1241 * @return The content of the log message that should be written. It may be 1242 * {@code null} or empty if no message should be written. It may 1243 * optionally include line breaks if the log message should span 1244 * multiple lines. 1245 */ 1246 public CharSequence logModifyDNAssuranceCompleted( 1247 final CompletedOperationContext opContext, 1248 final ModifyDNRequest request, 1249 final ModifyDNResult result, 1250 final AssuredReplicationResult assuranceResult) 1251 { 1252 // No log message will be generated by default. 1253 return null; 1254 } 1255 1256 1257 1258 /** 1259 * Logs a message about a search request received from a client. 1260 * 1261 * @param opContext The operation context for the search operation. 1262 * @param request The search request that was received. 1263 * 1264 * @return The content of the log message that should be written. It may be 1265 * {@code null} or empty if no message should be written. It may 1266 * optionally include line breaks if the log message should span 1267 * multiple lines. 1268 */ 1269 public CharSequence logSearchRequest(final OperationContext opContext, 1270 final SearchRequest request) 1271 { 1272 // No log message will be generated by default. 1273 return null; 1274 } 1275 1276 1277 1278 /** 1279 * Logs a message about a search request that will be forwarded to another 1280 * server. 1281 * 1282 * @param opContext The operation context for the search operation. 1283 * @param request The search request that was received. 1284 * @param target Information about the server to which the request will 1285 * be forwarded. 1286 * 1287 * @return The content of the log message that should be written. It may be 1288 * {@code null} or empty if no message should be written. It may 1289 * optionally include line breaks if the log message should span 1290 * multiple lines. 1291 */ 1292 public CharSequence logSearchForward(final OperationContext opContext, 1293 final SearchRequest request, 1294 final ForwardTarget target) 1295 { 1296 // No log message will be generated by default. 1297 return null; 1298 } 1299 1300 1301 1302 /** 1303 * Logs a message about a failure encountered while attempting to forward a 1304 * search request to another server. 1305 * 1306 * @param opContext The operation context for the search operation. 1307 * @param request The search request that was received. 1308 * @param target Information about the server to which the request was 1309 * forwarded. 1310 * @param failure The exception that was received when attempting to 1311 * forward the request. 1312 * 1313 * @return The content of the log message that should be written. It may be 1314 * {@code null} or empty if no message should be written. It may 1315 * optionally include line breaks if the log message should span 1316 * multiple lines. 1317 */ 1318 public CharSequence logSearchForwardFailure(final OperationContext opContext, 1319 final SearchRequest request, 1320 final ForwardTarget target, 1321 final LDAPException failure) 1322 { 1323 // No log message will be generated by default. 1324 return null; 1325 } 1326 1327 1328 1329 /** 1330 * Logs a message about a search result entry that was returned to the client. 1331 * 1332 * @param opContext The operation context for the search operation. 1333 * @param request The search request that was received. 1334 * @param entry The entry that was returned. 1335 * @param controls The set of controls included with the entry, or an empty 1336 * list if there were none. 1337 * 1338 * @return The content of the log message that should be written. It may be 1339 * {@code null} or empty if no message should be written. It may 1340 * optionally include line breaks if the log message should span 1341 * multiple lines. 1342 */ 1343 public CharSequence logSearchResultEntry(final OperationContext opContext, 1344 final SearchRequest request, 1345 final Entry entry, 1346 final List<Control> controls) 1347 { 1348 // No log message will be generated by default. 1349 return null; 1350 } 1351 1352 1353 1354 /** 1355 * Logs a message about a search result reference that was returned to the 1356 * client. 1357 * 1358 * @param opContext The operation context for the search operation. 1359 * @param request The search request that was received. 1360 * @param referralURLs The referral URLs for the reference that was 1361 * returned. 1362 * @param controls The set of controls included with the reference, or 1363 * an empty list if there were none. 1364 * 1365 * @return The content of the log message that should be written. It may be 1366 * {@code null} or empty if no message should be written. It may 1367 * optionally include line breaks if the log message should span 1368 * multiple lines. 1369 */ 1370 public CharSequence logSearchResultReference(final OperationContext opContext, 1371 final SearchRequest request, 1372 final List<String> referralURLs, 1373 final List<Control> controls) 1374 { 1375 // No log message will be generated by default. 1376 return null; 1377 } 1378 1379 1380 1381 /** 1382 * Logs a message about the result of processing a search request. 1383 * 1384 * @param opContext The operation context for the search operation. 1385 * @param request The search request that was received. 1386 * @param result The result of processing the search request. 1387 * 1388 * @return The content of the log message that should be written. It may be 1389 * {@code null} or empty if no message should be written. It may 1390 * optionally include line breaks if the log message should span 1391 * multiple lines. 1392 */ 1393 public CharSequence logSearchResultDone( 1394 final CompletedSearchOperationContext opContext, 1395 final SearchRequest request, 1396 final SearchResult result) 1397 { 1398 // No log message will be generated by default. 1399 return null; 1400 } 1401 1402 1403 1404 /** 1405 * Logs a message about an unbind request received from a client. 1406 * 1407 * @param opContext The operation context for the unbind operation. 1408 * @param request The unbind request that was received. 1409 * 1410 * @return The content of the log message that should be written. It may be 1411 * {@code null} or empty if no message should be written. It may 1412 * optionally include line breaks if the log message should span 1413 * multiple lines. 1414 */ 1415 public CharSequence logUnbindRequest(final OperationContext opContext, 1416 final UnbindRequest request) 1417 { 1418 // No log message will be generated by default. 1419 return null; 1420 } 1421 1422 1423 1424 /** 1425 * Logs a message about an intermediate response that was returned to the 1426 * client. 1427 * 1428 * @param opContext The operation context for the associated 1429 * operation. 1430 * @param intermediateResponse The intermediate response that was returned. 1431 * 1432 * @return The content of the log message that should be written. It may be 1433 * {@code null} or empty if no message should be written. It may 1434 * optionally include line breaks if the log message should span 1435 * multiple lines. 1436 */ 1437 public CharSequence logIntermediateResponse(final OperationContext opContext, 1438 final IntermediateResponse intermediateResponse) 1439 { 1440 // No log message will be generated by default. 1441 return null; 1442 } 1443 1444 1445 1446 /** 1447 * Writes a message to the access logger to indicate that the Directory Proxy 1448 * Server will attempt to perform entry rebalancing by migrating a subtree 1449 * from one backend set to another. 1450 * 1451 * @param rebalancingOperationID The unique ID assigned to the entry 1452 * balancing operation. 1453 * @param triggerOperation The operation that triggered the entry 1454 * rebalancing. It may be {@code null} if the 1455 * rebalancing operation wasn't triggered by a 1456 * client request. 1457 * @param baseDN The base DN of the subtree to migrate. 1458 * @param sizeLimit The maximum number of entries to migrate. 1459 * @param sourceBackendSetName The name of the backend set containing the 1460 * subtree to migrate. 1461 * @param sourceAddress The address of the server from which the 1462 * source entries will be read. 1463 * @param sourcePort The port of the server from which the 1464 * source entries will be read. 1465 * @param targetBackendSetName The name of the backend set to which the 1466 * subtree will be migrated. 1467 * @param targetAddress The address of the server to which the 1468 * subtree will be migrated. 1469 * @param targetPort The port of the server to which the subtree 1470 * will be migrated. 1471 * 1472 * @return The content of the log message that should be written. It may be 1473 * {@code null} or empty if no message should be written. It may 1474 * optionally include line breaks if the log message should span 1475 * multiple lines. 1476 */ 1477 public CharSequence logEntryRebalancingRequest( 1478 final long rebalancingOperationID, 1479 final OperationContext triggerOperation, 1480 final String baseDN, final int sizeLimit, 1481 final String sourceBackendSetName, 1482 final String sourceAddress, final int sourcePort, 1483 final String targetBackendSetName, 1484 final String targetAddress, final int targetPort) 1485 { 1486 // No log message will be generated by default. 1487 return null; 1488 } 1489 1490 1491 1492 /** 1493 * Writes a message to the access logger to indicate that the Directory Proxy 1494 * Server will attempt to perform entry rebalancing by migrating a subtree 1495 * from one backend set to another. 1496 * 1497 * @param rebalancingOperationID The unique ID assigned to the entry 1498 * balancing operation. 1499 * @param triggerOperation The operation that triggered the entry 1500 * rebalancing. It may be {@code null} if the 1501 * rebalancing operation wasn't triggered by a 1502 * client request. 1503 * @param baseDN The base DN of the subtree to migrate. 1504 * @param sizeLimit The maximum number of entries to migrate. 1505 * @param sourceBackendSetName The name of the backend set containing the 1506 * subtree to migrate. 1507 * @param sourceAddress The address of the server from which the 1508 * source entries will be read. 1509 * @param sourcePort The port of the server from which the 1510 * source entries will be read. 1511 * @param targetBackendSetName The name of the backend set to which the 1512 * subtree will be migrated. 1513 * @param targetAddress The address of the server to which the 1514 * subtree will be migrated. 1515 * @param targetPort The port of the server to which the subtree 1516 * will be migrated. 1517 * @param moveSubtreeResult An object with information about the result 1518 * of the subtree move processing. 1519 * 1520 * @return The content of the log message that should be written. It may be 1521 * {@code null} or empty if no message should be written. It may 1522 * optionally include line breaks if the log message should span 1523 * multiple lines. 1524 */ 1525 public CharSequence logEntryRebalancingResult( 1526 final long rebalancingOperationID, 1527 final OperationContext triggerOperation, 1528 final String baseDN, final int sizeLimit, 1529 final String sourceBackendSetName, 1530 final String sourceAddress, final int sourcePort, 1531 final String targetBackendSetName, 1532 final String targetAddress, final int targetPort, 1533 final MoveSubtreeResult moveSubtreeResult) 1534 { 1535 // No log message will be generated by default. 1536 return null; 1537 } 1538}