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