/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at
 * docs/licenses/cddl.txt
 * or http://www.opensource.org/licenses/cddl1.php.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at
 * docs/licenses/cddl.txt.  If applicable,
 * add the following below this CDDL HEADER, with the fields enclosed
 * by brackets "[]" replaced with your own identifying information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Copyright 2011-2016 UnboundID Corp.
 */
package com.unboundid.directory.sdk.common.api;



import java.security.cert.Certificate;
import java.util.Collections;
import java.util.List;
import java.util.Map;

import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
import com.unboundid.directory.sdk.common.config.FileBasedAccessLoggerConfig;
import com.unboundid.directory.sdk.common.internal.ExampleUsageProvider;
import com.unboundid.directory.sdk.common.internal.Reconfigurable;
import com.unboundid.directory.sdk.common.internal.UnboundIDExtension;
import com.unboundid.directory.sdk.common.operation.AbandonRequest;
import com.unboundid.directory.sdk.common.operation.AddRequest;
import com.unboundid.directory.sdk.common.operation.AddResult;
import com.unboundid.directory.sdk.common.operation.BindResult;
import com.unboundid.directory.sdk.common.operation.CompareRequest;
import com.unboundid.directory.sdk.common.operation.CompareResult;
import com.unboundid.directory.sdk.common.operation.DeleteRequest;
import com.unboundid.directory.sdk.common.operation.DeleteResult;
import com.unboundid.directory.sdk.common.operation.ExtendedRequest;
import com.unboundid.directory.sdk.common.operation.ExtendedResult;
import com.unboundid.directory.sdk.common.operation.GenericResult;
import com.unboundid.directory.sdk.common.operation.ModifyRequest;
import com.unboundid.directory.sdk.common.operation.ModifyResult;
import com.unboundid.directory.sdk.common.operation.ModifyDNRequest;
import com.unboundid.directory.sdk.common.operation.ModifyDNResult;
import com.unboundid.directory.sdk.common.operation.SASLBindRequest;
import com.unboundid.directory.sdk.common.operation.SearchRequest;
import com.unboundid.directory.sdk.common.operation.SearchResult;
import com.unboundid.directory.sdk.common.operation.SimpleBindRequest;
import com.unboundid.directory.sdk.common.operation.UnbindRequest;
import com.unboundid.directory.sdk.common.types.AssuredReplicationResult;
import com.unboundid.directory.sdk.common.types.ClientContext;
import com.unboundid.directory.sdk.common.types.CompletedOperationContext;
import com.unboundid.directory.sdk.common.types.CompletedSearchOperationContext;
import com.unboundid.directory.sdk.common.types.DisconnectReason;
import com.unboundid.directory.sdk.common.types.Entry;
import com.unboundid.directory.sdk.common.types.ForwardTarget;
import com.unboundid.directory.sdk.common.types.OperationContext;
import com.unboundid.directory.sdk.common.types.ServerContext;
import com.unboundid.directory.sdk.ds.internal.DirectoryServerExtension;
import com.unboundid.directory.sdk.metrics.internal.MetricsEngineExtension;
import com.unboundid.directory.sdk.proxy.internal.DirectoryProxyServerExtension;
import com.unboundid.directory.sdk.sync.internal.SynchronizationServerExtension;
import com.unboundid.ldap.sdk.Control;
import com.unboundid.ldap.sdk.IntermediateResponse;
import com.unboundid.ldap.sdk.LDAPException;
import com.unboundid.ldap.sdk.ResultCode;
import com.unboundid.ldap.sdk.unboundidds.MoveSubtreeResult;
import com.unboundid.util.Extensible;
import com.unboundid.util.ThreadSafety;
import com.unboundid.util.ThreadSafetyLevel;
import com.unboundid.util.args.ArgumentException;
import com.unboundid.util.args.ArgumentParser;



/**
 * This class defines an API that may be used to create a specific type of
 * access logger which is intended to write log messages to text files.  This is
 * a convenience for developers which wish to create custom access loggers that
 * write to text files and provides support for a wide range of functionality
 * including high-performance and highly-concurrent logging.  All of the options
 * available to {@link AccessLogger} implementations are available for
 * file-based access loggers, as well as options for indicating the log file
 * path, the rotation and retention policies, whether to buffer the output, etc.
 * <BR><BR>
 * Note that file-based access loggers will automatically be registered within
 * the server as disk space consumers, so there is no need to implement the
 * {@link DiskSpaceConsumer} interface.  Also note that configuration change
 * related to the log file (e.g., the log file path, buffer size, queue size,
 * etc.) will also automatically be handled by the server, so subclasses only
 * need to be concerned about changes to the custom arguments they define.
 * <BR>
 * <H2>Configuring File-Based Access Loggers</H2>
 * In order to configure a file-based access logger created using this API, use
 * a command like:
 * <PRE>
 *      dsconfig create-log-publisher \
 *           --publisher-name "<I>{logger-name}</I>" \
 *           --type third-party-file-based-access \
 *           --set enabled:true \
 *           --set "log-file:<I>{path}</I>" \
 *           --set "rotation-policy:<I>{rotation-policy-name}</I>" \
 *           --set "retention-policy:<I>{retention-policy-name}</I>" \
 *           --set "extension-class:<I>{class-name}</I>" \
 *           --set "extension-argument:<I>{name=value}</I>"
 * </PRE>
 * where "<I>{logger-name}</I>" is the name to use for the access logger
 * instance, "<I>{path}</I>" is the path to the log file to be written,
 * "<I>{rotation-policy-name}</I>" is the name of the log rotation policy to use
 * for the log file, "<I>{retention-policy-name}</I>" is the name of the log
 * retention policy to use for the log file, "<I>{class-name}</I>" is the
 * fully-qualified name of the Java class that extends
 * {@code com.unboundid.directory.sdk.common.api.FileBasedAccessLogger}, and
 * "<I>{name=value}</I>" represents name-value pairs for any arguments to
 * provide to the logger.  If multiple arguments should be provided to the
 * logger, then the "<CODE>--set extension-argument:<I>{name=value}</I></CODE>"
 * option should be provided multiple times.  It is also possible to specify
 * multiple log rotation and/or retention policies if desired.
 *
 * @see  AccessLogger
 * @see  com.unboundid.directory.sdk.common.scripting.ScriptedAccessLogger
 * @see
 *    com.unboundid.directory.sdk.common.scripting.ScriptedFileBasedAccessLogger
 */
@Extensible()
@DirectoryServerExtension()
@DirectoryProxyServerExtension(appliesToLocalContent=true,
     appliesToRemoteContent=true)
@SynchronizationServerExtension(appliesToLocalContent=true,
     appliesToSynchronizedContent=false)
@MetricsEngineExtension()
@BrokerExtension()
@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
public abstract class FileBasedAccessLogger
       implements UnboundIDExtension,
                  Reconfigurable<FileBasedAccessLoggerConfig>,
                  ExampleUsageProvider
{
  /**
   * Creates a new instance of this file-based access logger.  All file-based
   * access logger implementations must include a default constructor, but any
   * initialization should generally be done in the
   * {@code initializeAccessLogger} method.
   */
  public FileBasedAccessLogger()
  {
    // No implementation is required.
  }



  /**
   * {@inheritDoc}
   */
  public abstract String getExtensionName();



  /**
   * {@inheritDoc}
   */
  public abstract String[] getExtensionDescription();



  /**
   * {@inheritDoc}
   */
  public void defineConfigArguments(final ArgumentParser parser)
         throws ArgumentException
  {
    // No arguments will be allowed by default.
  }



  /**
   * Initializes this file-based access logger.  Note that the work of
   * initializing the log file writer will automatically be handled by the
   * server, so the only initialization that needs to be performed is that
   * required for custom arguments.
   *
   * @param  serverContext  A handle to the server context for the server in
   *                        which this extension is running.
   * @param  config         The general configuration for this file-based access
   *                        logger.
   * @param  parser         The argument parser which has been initialized from
   *                        the configuration for this file-based access logger.
   *
   * @throws  LDAPException  If a problem occurs while initializing this
   *                         file-based access logger.
   */
  public void initializeAccessLogger(final ServerContext serverContext,
                                     final FileBasedAccessLoggerConfig config,
                                     final ArgumentParser parser)
         throws LDAPException
  {
    // No initialization will be performed by default.
  }



  /**
   * {@inheritDoc}  Note that the server will automatically handle the work of
   * validating any changes to properties related to the log file, so only
   * changes to custom arguments need to be examined here.
   */
  public boolean isConfigurationAcceptable(
                      final FileBasedAccessLoggerConfig config,
                      final ArgumentParser parser,
                      final List<String> unacceptableReasons)
  {
    // No extended validation will be performed by default.
    return true;
  }



  /**
   * {@inheritDoc}  Note that the server will automatically handle the work of
   * applying any changes to properties related to the log file, so only changes
   * to custom arguments need to be examined here.
   */
  public ResultCode applyConfiguration(final FileBasedAccessLoggerConfig config,
                                       final ArgumentParser parser,
                                       final List<String> adminActionsRequired,
                                       final List<String> messages)
  {
    // If there are any custom arguments, then add an admin action message
    // indicating that the extension needs to be restarted for any changes to
    // take effect.
    if (! parser.getNamedArguments().isEmpty())
    {
      adminActionsRequired.add(
           "If any extension-argument values have been altered, then " +
                "those new values have not actually been applied.  The new " +
                "configuration for those arguments will not take effect " +
                "until this file-based access logger is disabled and " +
                "re-enabled, or until the server is restarted.");
    }

    return ResultCode.SUCCESS;
  }



  /**
   * Performs any cleanup which may be necessary when this file-based access
   * logger is to be taken out of service.  Any processing required for shutting
   * down the log file writer will be automatically handled by the server.
   */
  public void finalizeAccessLogger()
  {
    // No implementation is required.
  }



  /**
   * Logs a message indicating that a new connection has been established.
   *
   * @param  clientContext  Information about the client connection that has
   *                        been accepted.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logConnect(final ClientContext clientContext)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message indicating that a connection has been closed.
   *
   * @param  clientContext     Information about the client connection that has
   *                           been closed.
   * @param  disconnectReason  A general reason that the connection has been
   *                           closed.
   * @param  message           A message with additional information about the
   *                           closure.  It may be {@code null} if none is
   *                           available.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logDisconnect(final ClientContext clientContext,
                                    final DisconnectReason disconnectReason,
                                    final String message)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about security negotiation performed by a client.
   *
   * @param  clientContext  Information about the client connection on which
   *                        the negotiation was completed.
   * @param  protocol       The security protocol selected by the negotiation.
   *                        It may be {@code null} if no protocol is available.
   * @param  cipher         The cipher suite selected by the negotiation.  It
   *                        may be {@code null} if no cipher is available.
   * @param  properties     A set of additional properties that may be included
   *                        in the log message.  It may be {@code null} or empty
   *                        if no additional properties are needed.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logSecurityNegotiation(final ClientContext clientContext,
                           final String protocol, final String cipher,
                           final Map<String,String> properties)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a certificate chain presented by a client.
   *
   * @param  clientContext  Information about the client that presented the
   *                        certificate chain.
   * @param  certChain      The certificate chain presented by the client.
   * @param  authDN         The DN of the user as whom the client was
   *                        automatically authenticated, or {@code null} if the
   *                        client was not automatically authenticated.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logClientCertificateChain(
                           final ClientContext clientContext,
                           final Certificate[] certChain, final String authDN)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an abandon request received from a client.
   *
   * @param  opContext  The operation context for the abandon operation.
   * @param  request    The abandon request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAbandonRequest(final OperationContext opContext,
                                        final AbandonRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an abandon request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the abandon operation.
   * @param  request    The abandon request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAbandonForward(final OperationContext opContext,
                                        final AbandonRequest request,
                                        final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing an abandon request.
   *
   * @param  opContext  The operation context for the abandon operation.
   * @param  request    The abandon request that was received.
   * @param  result     The result of processing the abandon request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAbandonResult(
                           final CompletedOperationContext opContext,
                           final AbandonRequest request,
                           final GenericResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an add request received from a client.
   *
   * @param  opContext  The operation context for the add operation.
   * @param  request    The add request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAddRequest(final OperationContext opContext,
                                    final AddRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an add request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the add operation.
   * @param  request    The add request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAddForward(final OperationContext opContext,
                                    final AddRequest request,
                                    final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward an
   * add request to another server.
   *
   * @param  opContext  The operation context for the add operation.
   * @param  request    The add request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAddForwardFailure(final OperationContext opContext,
                                           final AddRequest request,
                                           final ForwardTarget target,
                                           final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing an add request.
   *
   * @param  opContext  The operation context for the add operation.
   * @param  request    The add request that was received.
   * @param  result     The result of processing the add request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAddResponse(final CompletedOperationContext opContext,
                                     final AddRequest request,
                                     final AddResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of replication assurance processing for an
   * add operation.
   *
   * @param  opContext        The operation context for the add operation.
   * @param  request          The add request that was received.
   * @param  result           The result of processing the add request.
   * @param  assuranceResult  The replication assurance processing result.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logAddAssuranceCompleted(
                           final CompletedOperationContext opContext,
                           final AddRequest request, final AddResult result,
                           final AssuredReplicationResult assuranceResult)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a simple bind request received from a client.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindRequest(final OperationContext opContext,
                                     final SimpleBindRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a simple bind request that will be forwarded to
   * another server.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindForward(final OperationContext opContext,
                                     final SimpleBindRequest request,
                                     final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward a
   * simple bind request to another server.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindForwardFailure(final OperationContext opContext,
                                            final SimpleBindRequest request,
                                            final ForwardTarget target,
                                            final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing a simple bind request.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   * @param  result     The result of processing the bind request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindResponse(final CompletedOperationContext opContext,
                                      final SimpleBindRequest request,
                                      final BindResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a SASL bind request received from a client.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindRequest(final OperationContext opContext,
                                     final SASLBindRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a SASL bind request that will be forwarded to
   * another server.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindForward(final OperationContext opContext,
                                     final SASLBindRequest request,
                                     final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward a
   * SASL bind request to another server.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindForwardFailure(final OperationContext opContext,
                                            final SASLBindRequest request,
                                            final ForwardTarget target,
                                            final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing a SASL bind request.
   *
   * @param  opContext  The operation context for the bind operation.
   * @param  request    The bind request that was received.
   * @param  result     The result of processing the bind request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logBindResponse(final CompletedOperationContext opContext,
                                      final SASLBindRequest request,
                                      final BindResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a compare request received from a client.
   *
   * @param  opContext  The operation context for the compare operation.
   * @param  request    The compare request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logCompareRequest(final OperationContext opContext,
                                        final CompareRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a compare request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the compare operation.
   * @param  request    The compare request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logCompareForward(final OperationContext opContext,
                                        final CompareRequest request,
                                        final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward a
   * compare request to another server.
   *
   * @param  opContext  The operation context for the compare operation.
   * @param  request    The compare request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logCompareForwardFailure(final OperationContext opContext,
                                               final CompareRequest request,
                                               final ForwardTarget target,
                                               final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing a compare request.
   *
   * @param  opContext  The operation context for the compare operation.
   * @param  request    The compare request that was received.
   * @param  result     The result of processing the compare request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logCompareResponse(
                           final CompletedOperationContext opContext,
                           final CompareRequest request,
                           final CompareResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a delete request received from a client.
   *
   * @param  opContext  The operation context for the delete operation.
   * @param  request    The delete request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logDeleteRequest(final OperationContext opContext,
                                       final DeleteRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a delete request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the delete operation.
   * @param  request    The delete request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logDeleteForward(final OperationContext opContext,
                                       final DeleteRequest request,
                                       final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward a
   * delete request to another server.
   *
   * @param  opContext  The operation context for the delete operation.
   * @param  request    The delete request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logDeleteForwardFailure(final OperationContext opContext,
                                              final DeleteRequest request,
                                              final ForwardTarget target,
                                              final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing a delete request.
   *
   * @param  opContext  The operation context for the delete operation.
   * @param  request    The delete request that was received.
   * @param  result     The result of processing the delete request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logDeleteResponse(
                           final CompletedOperationContext opContext,
                           final DeleteRequest request,
                           final DeleteResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of replication assurance processing for a
   * delete operation.
   *
   * @param  opContext        The operation context for the delete operation.
   * @param  request          The delete request that was received.
   * @param  result           The result of processing the delete request.
   * @param  assuranceResult  The replication assurance processing result.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logDeleteAssuranceCompleted(
                           final CompletedOperationContext opContext,
                           final DeleteRequest request,
                           final DeleteResult result,
                           final AssuredReplicationResult assuranceResult)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an extended request received from a client.
   *
   * @param  opContext  The operation context for the extended operation.
   * @param  request    The extended request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logExtendedRequest(final OperationContext opContext,
                                         final ExtendedRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an extended request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the extended operation.
   * @param  request    The extended request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logExtendedForward(final OperationContext opContext,
                                         final ExtendedRequest request,
                                         final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward an
   * extended request to another server.
   *
   * @param  opContext  The operation context for the extended operation.
   * @param  request    The extended request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logExtendedForwardFailure(
                           final OperationContext opContext,
                           final ExtendedRequest request,
                           final ForwardTarget target,
                           final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing an extended request.
   *
   * @param  opContext  The operation context for the extended operation.
   * @param  request    The extended request that was received.
   * @param  result     The result of processing the extended request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logExtendedResponse(
                           final CompletedOperationContext opContext,
                           final ExtendedRequest request,
                           final ExtendedResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a modify request received from a client.
   *
   * @param  opContext  The operation context for the modify operation.
   * @param  request    The modify request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyRequest(final OperationContext opContext,
                                       final ModifyRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a modify request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the modify operation.
   * @param  request    The modify request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyForward(final OperationContext opContext,
                                       final ModifyRequest request,
                                       final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward a
   * modify request to another server.
   *
   * @param  opContext  The operation context for the modify operation.
   * @param  request    The modify request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyForwardFailure(final OperationContext opContext,
                                              final ModifyRequest request,
                                              final ForwardTarget target,
                                              final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing a modify request.
   *
   * @param  opContext  The operation context for the modify operation.
   * @param  request    The modify request that was received.
   * @param  result     The result of processing the modify request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyResponse(
                           final CompletedOperationContext opContext,
                           final ModifyRequest request,
                           final ModifyResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of replication assurance processing for a
   * modify operation.
   *
   * @param  opContext        The operation context for the modify operation.
   * @param  request          The modify request that was received.
   * @param  result           The result of processing the modify request.
   * @param  assuranceResult  The replication assurance processing result.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyAssuranceCompleted(
                           final CompletedOperationContext opContext,
                           final ModifyRequest request,
                           final ModifyResult result,
                           final AssuredReplicationResult assuranceResult)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a modify DN request received from a client.
   *
   * @param  opContext  The operation context for the modify DN operation.
   * @param  request    The modify DN request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyDNRequest(final OperationContext opContext,
                                         final ModifyDNRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a modify DN request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the modify DN operation.
   * @param  request    The modify DN request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyDNForward(final OperationContext opContext,
                                         final ModifyDNRequest request,
                                         final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward a
   * modify DN request to another server.
   *
   * @param  opContext  The operation context for the modify DN operation.
   * @param  request    The modify DN request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyDNForwardFailure(
                           final OperationContext opContext,
                           final ModifyDNRequest request,
                           final ForwardTarget target,
                           final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing a modify DN request.
   *
   * @param  opContext  The operation context for the modify DN operation.
   * @param  request    The modify DN request that was received.
   * @param  result     The result of processing the modify DN request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyDNResponse(
                           final CompletedOperationContext opContext,
                           final ModifyDNRequest request,
                           final ModifyDNResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of replication assurance processing for a
   * modify DN operation.
   *
   * @param  opContext        The operation context for the modify DN operation.
   * @param  request          The modify DN request that was received.
   * @param  result           The result of processing the modify DN request.
   * @param  assuranceResult  The replication assurance processing result.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logModifyDNAssuranceCompleted(
                           final CompletedOperationContext opContext,
                           final ModifyDNRequest request,
                           final ModifyDNResult result,
                           final AssuredReplicationResult assuranceResult)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a search request received from a client.
   *
   * @param  opContext  The operation context for the search operation.
   * @param  request    The search request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logSearchRequest(final OperationContext opContext,
                                       final SearchRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a search request that will be forwarded to another
   * server.
   *
   * @param  opContext  The operation context for the search operation.
   * @param  request    The search request that was received.
   * @param  target     Information about the server to which the request will
   *                    be forwarded.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logSearchForward(final OperationContext opContext,
                                       final SearchRequest request,
                                       final ForwardTarget target)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a failure encountered while attempting to forward a
   * search request to another server.
   *
   * @param  opContext  The operation context for the search operation.
   * @param  request    The search request that was received.
   * @param  target     Information about the server to which the request was
   *                    forwarded.
   * @param  failure    The exception that was received when attempting to
   *                    forward the request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logSearchForwardFailure(final OperationContext opContext,
                                              final SearchRequest request,
                                              final ForwardTarget target,
                                              final LDAPException failure)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a search result entry that was returned to the client.
   *
   * @param  opContext  The operation context for the search operation.
   * @param  request    The search request that was received.
   * @param  entry      The entry that was returned.
   * @param  controls   The set of controls included with the entry, or an empty
   *                    list if there were none.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logSearchResultEntry(final OperationContext opContext,
                                           final SearchRequest request,
                                           final Entry entry,
                                           final List<Control> controls)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about a search result reference that was returned to the
   * client.
   *
   * @param  opContext     The operation context for the search operation.
   * @param  request       The search request that was received.
   * @param  referralURLs  The referral URLs for the reference that was
   *                       returned.
   * @param  controls      The set of controls included with the reference, or
   *                       an empty list if there were none.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logSearchResultReference(final OperationContext opContext,
                                               final SearchRequest request,
                                               final List<String> referralURLs,
                                               final List<Control> controls)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about the result of processing a search request.
   *
   * @param  opContext  The operation context for the search operation.
   * @param  request    The search request that was received.
   * @param  result     The result of processing the search request.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logSearchResultDone(
                           final CompletedSearchOperationContext opContext,
                           final SearchRequest request,
                           final SearchResult result)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an unbind request received from a client.
   *
   * @param  opContext  The operation context for the unbind operation.
   * @param  request    The unbind request that was received.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logUnbindRequest(final OperationContext opContext,
                                       final UnbindRequest request)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Logs a message about an intermediate response that was returned to the
   * client.
   *
   * @param  opContext             The operation context for the associated
   *                               operation.
   * @param  intermediateResponse  The intermediate response that was returned.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logIntermediateResponse(final OperationContext opContext,
                           final IntermediateResponse intermediateResponse)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Writes a message to the access logger to indicate that the Directory Proxy
   * Server will attempt to perform entry rebalancing by migrating a subtree
   * from one backend set to another.
   *
   * @param  rebalancingOperationID  The unique ID assigned to the entry
   *                                 balancing operation.
   * @param  triggerOperation        The operation that triggered the entry
   *                                 rebalancing.  It may be {@code null} if the
   *                                 rebalancing operation wasn't triggered by a
   *                                 client request.
   * @param  baseDN                  The base DN of the subtree to migrate.
   * @param  sizeLimit               The maximum number of entries to migrate.
   * @param  sourceBackendSetName    The name of the backend set containing the
   *                                 subtree to migrate.
   * @param  sourceAddress           The address of the server from which the
   *                                 source entries will be read.
   * @param  sourcePort              The port of the server from which the
   *                                 source entries will be read.
   * @param  targetBackendSetName    The name of the backend set to which the
   *                                 subtree will be migrated.
   * @param  targetAddress           The address of the server to which the
   *                                 subtree will be migrated.
   * @param  targetPort              The port of the server to which the subtree
   *                                 will be migrated.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logEntryRebalancingRequest(
                           final long rebalancingOperationID,
                           final OperationContext triggerOperation,
                           final String baseDN, final int sizeLimit,
                           final String sourceBackendSetName,
                           final String sourceAddress, final int sourcePort,
                           final String targetBackendSetName,
                           final String targetAddress, final int targetPort)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * Writes a message to the access logger to indicate that the Directory Proxy
   * Server will attempt to perform entry rebalancing by migrating a subtree
   * from one backend set to another.
   *
   * @param  rebalancingOperationID  The unique ID assigned to the entry
   *                                 balancing operation.
   * @param  triggerOperation        The operation that triggered the entry
   *                                 rebalancing.  It may be {@code null} if the
   *                                 rebalancing operation wasn't triggered by a
   *                                 client request.
   * @param  baseDN                  The base DN of the subtree to migrate.
   * @param  sizeLimit               The maximum number of entries to migrate.
   * @param  sourceBackendSetName    The name of the backend set containing the
   *                                 subtree to migrate.
   * @param  sourceAddress           The address of the server from which the
   *                                 source entries will be read.
   * @param  sourcePort              The port of the server from which the
   *                                 source entries will be read.
   * @param  targetBackendSetName    The name of the backend set to which the
   *                                 subtree will be migrated.
   * @param  targetAddress           The address of the server to which the
   *                                 subtree will be migrated.
   * @param  targetPort              The port of the server to which the subtree
   *                                 will be migrated.
   * @param  moveSubtreeResult       An object with information about the result
   *                                 of the subtree move processing.
   *
   * @return  The content of the log message that should be written.  It may be
   *          {@code null} or empty if no message should be written.  It may
   *          optionally include line breaks if the log message should span
   *          multiple lines.
   */
  public CharSequence logEntryRebalancingResult(
                           final long rebalancingOperationID,
                           final OperationContext triggerOperation,
                           final String baseDN, final int sizeLimit,
                           final String sourceBackendSetName,
                           final String sourceAddress, final int sourcePort,
                           final String targetBackendSetName,
                           final String targetAddress, final int targetPort,
                           final MoveSubtreeResult moveSubtreeResult)
  {
    // No log message will be generated by default.
    return null;
  }



  /**
   * {@inheritDoc}
   */
  public Map<List<String>,String> getExamplesArgumentSets()
  {
    return Collections.emptyMap();
  }
}