Package com.unboundid.directory.sdk.common.api

Class FileBasedAccessLogger

  • All Implemented Interfaces:
    Configurable, ExampleUsageProvider, Reconfigurable<FileBasedAccessLoggerConfig>, UnboundIDExtension
    @Extensible
@DirectoryServerExtension
@DirectoryProxyServerExtension(appliesToLocalContent=true,
                               appliesToRemoteContent=true)
@SynchronizationServerExtension(appliesToLocalContent=true,
                                appliesToSynchronizedContent=false)
@MetricsEngineExtension
@BrokerExtension
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class FileBasedAccessLogger
extends java.lang.Object
implements UnboundIDExtension, Reconfigurable<FileBasedAccessLoggerConfig>, ExampleUsageProvider
    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 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.

    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 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.

    Configuring File-Based Access Loggers

    In order to configure a file-based access logger created using this API, use a command like: 
          dsconfig create-log-publisher \
           --publisher-name "{logger-name}" \
           --type third-party-file-based-access \
           --set enabled:true \
           --set "log-file:{path}" \
           --set "rotation-policy:{rotation-policy-name}" \
           --set "retention-policy:{retention-policy-name}" \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
    where "{logger-name}" is the name to use for the access logger instance, "{path}" is the path to the log file to be written, "{rotation-policy-name}" is the name of the log rotation policy to use for the log file, "{retention-policy-name}" is the name of the log retention policy to use for the log file, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.common.api.FileBasedAccessLogger, and "{name=value}" represents name-value pairs for any arguments to provide to the logger. If multiple arguments should be provided to the logger, then the "--set extension-argument:{name=value}" option should be provided multiple times. It is also possible to specify multiple log rotation and/or retention policies if desired.
    See Also:
    AccessLogger, ScriptedAccessLogger, ScriptedFileBasedAccessLogger

    • Constructor Detail

      • FileBasedAccessLogger

        public FileBasedAccessLogger()
        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 initializeAccessLogger method.

    • Method Detail

      • getExtensionDescription

        public abstract java.lang.String[] getExtensionDescription()
        Retrieves a human-readable description for this extension. Each element of the array that is returned will be considered a separate paragraph in generated documentation.
        Specified by:
        getExtensionDescription in interface UnboundIDExtension
        Returns:
        A human-readable description for this extension, or null or an empty array if no description should be available.

      • defineConfigArguments

        public void defineConfigArguments​(ArgumentParser parser)
                           throws ArgumentException
        Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).
        Specified by:
        defineConfigArguments in interface Configurable
        Parameters:
        parser - The argument parser to be updated with the configuration arguments which may be used by this extension.
        Throws:
        ArgumentException - If a problem is encountered while updating the provided argument parser.

      • initializeAccessLogger

        public void initializeAccessLogger​(ServerContext serverContext,
                                   FileBasedAccessLoggerConfig config,
                                   ArgumentParser parser)
                            throws LDAPException
        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.
        Parameters:
        serverContext - A handle to the server context for the server in which this extension is running.
        config - The general configuration for this file-based access logger.
        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.

      • isConfigurationAcceptable

        public boolean isConfigurationAcceptable​(FileBasedAccessLoggerConfig config,
                                         ArgumentParser parser,
                                         java.util.List<java.lang.String> unacceptableReasons)
        Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension. The parser will have been used to parse any configuration available for this extension, and any automatic validation will have been performed. This method may be used to perform any more complex validation which cannot be performed automatically by the argument parser. 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.
        Specified by:
        isConfigurationAcceptable in interface Reconfigurable<FileBasedAccessLoggerConfig>
        Parameters:
        config - The general configuration for this extension.
        parser - The argument parser that has been used to parse the proposed configuration for this extension.
        unacceptableReasons - A list to which messages may be added to provide additional information about why the provided configuration is not acceptable.
        Returns:
        true if the configuration in the provided argument parser appears to be acceptable, or false if not.

      • applyConfiguration

        public ResultCode applyConfiguration​(FileBasedAccessLoggerConfig config,
                                     ArgumentParser parser,
                                     java.util.List<java.lang.String> adminActionsRequired,
                                     java.util.List<java.lang.String> messages)
        Attempts to apply the configuration from the provided argument parser to this extension. 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.
        Specified by:
        applyConfiguration in interface Reconfigurable<FileBasedAccessLoggerConfig>
        Parameters:
        config - The general configuration for this extension.
        parser - The argument parser that has been used to parse the new configuration for this extension.
        adminActionsRequired - A list to which messages may be added to provide additional information about any additional administrative actions that may be required to apply some of the configuration changes.
        messages - A list to which messages may be added to provide additional information about the processing performed by this method.
        Returns:
        A result code providing information about the result of applying the configuration change. A result of SUCCESS should be used to indicate that all processing completed successfully. Any other result will indicate that a problem occurred during processing.

      • finalizeAccessLogger

        public void finalizeAccessLogger()
        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.

      • logConnect

        public java.lang.CharSequence logConnect​(ClientContext clientContext)
        Logs a message indicating that a new connection has been established.
        Parameters:
        clientContext - Information about the client connection that has been accepted.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logDisconnect

        public java.lang.CharSequence logDisconnect​(ClientContext clientContext,
                                            DisconnectReason disconnectReason,
                                            java.lang.String message)
        Logs a message indicating that a connection has been closed.
        Parameters:
        clientContext - Information about the client connection that has been closed.
        disconnectReason - A general reason that the connection has been closed.
        message - A message with additional information about the closure. It may be null if none is available.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logSecurityNegotiation

        public java.lang.CharSequence logSecurityNegotiation​(ClientContext clientContext,
                                                     java.lang.String protocol,
                                                     java.lang.String cipher,
                                                     java.util.Map<java.lang.String,​java.lang.String> properties)
        Logs a message about security negotiation performed by a client.
        Parameters:
        clientContext - Information about the client connection on which the negotiation was completed.
        protocol - The security protocol selected by the negotiation. It may be null if no protocol is available.
        cipher - The cipher suite selected by the negotiation. It may be null if no cipher is available.
        properties - A set of additional properties that may be included in the log message. It may be null or empty if no additional properties are needed.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logClientCertificateChain

        public java.lang.CharSequence logClientCertificateChain​(ClientContext clientContext,
                                                        java.security.cert.Certificate[] certChain,
                                                        java.lang.String authDN)
        Logs a message about a certificate chain presented by a client.
        Parameters:
        clientContext - Information about the client that presented the certificate chain.
        certChain - The certificate chain presented by the client.
        authDN - The DN of the user as whom the client was automatically authenticated, or null if the client was not automatically authenticated.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAbandonRequest

        public java.lang.CharSequence logAbandonRequest​(OperationContext opContext,
                                                AbandonRequest request)
        Logs a message about an abandon request received from a client.
        Parameters:
        opContext - The operation context for the abandon operation.
        request - The abandon request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAbandonForward

        public java.lang.CharSequence logAbandonForward​(OperationContext opContext,
                                                AbandonRequest request,
                                                ForwardTarget target)
        Logs a message about an abandon request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the abandon operation.
        request - The abandon request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAbandonResult

        public java.lang.CharSequence logAbandonResult​(CompletedOperationContext opContext,
                                               AbandonRequest request,
                                               GenericResult result)
        Logs a message about the result of processing an abandon request.
        Parameters:
        opContext - The operation context for the abandon operation.
        request - The abandon request that was received.
        result - The result of processing the abandon request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAddRequest

        public java.lang.CharSequence logAddRequest​(OperationContext opContext,
                                            AddRequest request)
        Logs a message about an add request received from a client.
        Parameters:
        opContext - The operation context for the add operation.
        request - The add request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAddForward

        public java.lang.CharSequence logAddForward​(OperationContext opContext,
                                            AddRequest request,
                                            ForwardTarget target)
        Logs a message about an add request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the add operation.
        request - The add request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAddForwardFailure

        public java.lang.CharSequence logAddForwardFailure​(OperationContext opContext,
                                                   AddRequest request,
                                                   ForwardTarget target,
                                                   LDAPException failure)
        Logs a message about a failure encountered while attempting to forward an add request to another server.
        Parameters:
        opContext - The operation context for the add operation.
        request - The add request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAddResponse

        public java.lang.CharSequence logAddResponse​(CompletedOperationContext opContext,
                                             AddRequest request,
                                             AddResult result)
        Logs a message about the result of processing an add request.
        Parameters:
        opContext - The operation context for the add operation.
        request - The add request that was received.
        result - The result of processing the add request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logAddAssuranceCompleted

        public java.lang.CharSequence logAddAssuranceCompleted​(CompletedOperationContext opContext,
                                                       AddRequest request,
                                                       AddResult result,
                                                       AssuredReplicationResult assuranceResult)
        Logs a message about the result of replication assurance processing for an add operation.
        Parameters:
        opContext - The operation context for the add operation.
        request - The add request that was received.
        result - The result of processing the add request.
        assuranceResult - The replication assurance processing result.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindRequest

        public java.lang.CharSequence logBindRequest​(OperationContext opContext,
                                             SimpleBindRequest request)
        Logs a message about a simple bind request received from a client.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindForward

        public java.lang.CharSequence logBindForward​(OperationContext opContext,
                                             SimpleBindRequest request,
                                             ForwardTarget target)
        Logs a message about a simple bind request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindForwardFailure

        public java.lang.CharSequence logBindForwardFailure​(OperationContext opContext,
                                                    SimpleBindRequest request,
                                                    ForwardTarget target,
                                                    LDAPException failure)
        Logs a message about a failure encountered while attempting to forward a simple bind request to another server.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindResponse

        public java.lang.CharSequence logBindResponse​(CompletedOperationContext opContext,
                                              SimpleBindRequest request,
                                              BindResult result)
        Logs a message about the result of processing a simple bind request.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        result - The result of processing the bind request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindRequest

        public java.lang.CharSequence logBindRequest​(OperationContext opContext,
                                             SASLBindRequest request)
        Logs a message about a SASL bind request received from a client.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindForward

        public java.lang.CharSequence logBindForward​(OperationContext opContext,
                                             SASLBindRequest request,
                                             ForwardTarget target)
        Logs a message about a SASL bind request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindForwardFailure

        public java.lang.CharSequence logBindForwardFailure​(OperationContext opContext,
                                                    SASLBindRequest request,
                                                    ForwardTarget target,
                                                    LDAPException failure)
        Logs a message about a failure encountered while attempting to forward a SASL bind request to another server.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logBindResponse

        public java.lang.CharSequence logBindResponse​(CompletedOperationContext opContext,
                                              SASLBindRequest request,
                                              BindResult result)
        Logs a message about the result of processing a SASL bind request.
        Parameters:
        opContext - The operation context for the bind operation.
        request - The bind request that was received.
        result - The result of processing the bind request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logCompareRequest

        public java.lang.CharSequence logCompareRequest​(OperationContext opContext,
                                                CompareRequest request)
        Logs a message about a compare request received from a client.
        Parameters:
        opContext - The operation context for the compare operation.
        request - The compare request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logCompareForward

        public java.lang.CharSequence logCompareForward​(OperationContext opContext,
                                                CompareRequest request,
                                                ForwardTarget target)
        Logs a message about a compare request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the compare operation.
        request - The compare request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logCompareForwardFailure

        public java.lang.CharSequence logCompareForwardFailure​(OperationContext opContext,
                                                       CompareRequest request,
                                                       ForwardTarget target,
                                                       LDAPException failure)
        Logs a message about a failure encountered while attempting to forward a compare request to another server.
        Parameters:
        opContext - The operation context for the compare operation.
        request - The compare request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logCompareResponse

        public java.lang.CharSequence logCompareResponse​(CompletedOperationContext opContext,
                                                 CompareRequest request,
                                                 CompareResult result)
        Logs a message about the result of processing a compare request.
        Parameters:
        opContext - The operation context for the compare operation.
        request - The compare request that was received.
        result - The result of processing the compare request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logDeleteRequest

        public java.lang.CharSequence logDeleteRequest​(OperationContext opContext,
                                               DeleteRequest request)
        Logs a message about a delete request received from a client.
        Parameters:
        opContext - The operation context for the delete operation.
        request - The delete request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logDeleteForward

        public java.lang.CharSequence logDeleteForward​(OperationContext opContext,
                                               DeleteRequest request,
                                               ForwardTarget target)
        Logs a message about a delete request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the delete operation.
        request - The delete request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logDeleteForwardFailure

        public java.lang.CharSequence logDeleteForwardFailure​(OperationContext opContext,
                                                      DeleteRequest request,
                                                      ForwardTarget target,
                                                      LDAPException failure)
        Logs a message about a failure encountered while attempting to forward a delete request to another server.
        Parameters:
        opContext - The operation context for the delete operation.
        request - The delete request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logDeleteResponse

        public java.lang.CharSequence logDeleteResponse​(CompletedOperationContext opContext,
                                                DeleteRequest request,
                                                DeleteResult result)
        Logs a message about the result of processing a delete request.
        Parameters:
        opContext - The operation context for the delete operation.
        request - The delete request that was received.
        result - The result of processing the delete request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logDeleteAssuranceCompleted

        public java.lang.CharSequence logDeleteAssuranceCompleted​(CompletedOperationContext opContext,
                                                          DeleteRequest request,
                                                          DeleteResult result,
                                                          AssuredReplicationResult assuranceResult)
        Logs a message about the result of replication assurance processing for a delete operation.
        Parameters:
        opContext - The operation context for the delete operation.
        request - The delete request that was received.
        result - The result of processing the delete request.
        assuranceResult - The replication assurance processing result.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logExtendedRequest

        public java.lang.CharSequence logExtendedRequest​(OperationContext opContext,
                                                 ExtendedRequest request)
        Logs a message about an extended request received from a client.
        Parameters:
        opContext - The operation context for the extended operation.
        request - The extended request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logExtendedForward

        public java.lang.CharSequence logExtendedForward​(OperationContext opContext,
                                                 ExtendedRequest request,
                                                 ForwardTarget target)
        Logs a message about an extended request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the extended operation.
        request - The extended request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logExtendedForwardFailure

        public java.lang.CharSequence logExtendedForwardFailure​(OperationContext opContext,
                                                        ExtendedRequest request,
                                                        ForwardTarget target,
                                                        LDAPException failure)
        Logs a message about a failure encountered while attempting to forward an extended request to another server.
        Parameters:
        opContext - The operation context for the extended operation.
        request - The extended request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logExtendedResponse

        public java.lang.CharSequence logExtendedResponse​(CompletedOperationContext opContext,
                                                  ExtendedRequest request,
                                                  ExtendedResult result)
        Logs a message about the result of processing an extended request.
        Parameters:
        opContext - The operation context for the extended operation.
        request - The extended request that was received.
        result - The result of processing the extended request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyRequest

        public java.lang.CharSequence logModifyRequest​(OperationContext opContext,
                                               ModifyRequest request)
        Logs a message about a modify request received from a client.
        Parameters:
        opContext - The operation context for the modify operation.
        request - The modify request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyForward

        public java.lang.CharSequence logModifyForward​(OperationContext opContext,
                                               ModifyRequest request,
                                               ForwardTarget target)
        Logs a message about a modify request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the modify operation.
        request - The modify request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyForwardFailure

        public java.lang.CharSequence logModifyForwardFailure​(OperationContext opContext,
                                                      ModifyRequest request,
                                                      ForwardTarget target,
                                                      LDAPException failure)
        Logs a message about a failure encountered while attempting to forward a modify request to another server.
        Parameters:
        opContext - The operation context for the modify operation.
        request - The modify request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyResponse

        public java.lang.CharSequence logModifyResponse​(CompletedOperationContext opContext,
                                                ModifyRequest request,
                                                ModifyResult result)
        Logs a message about the result of processing a modify request.
        Parameters:
        opContext - The operation context for the modify operation.
        request - The modify request that was received.
        result - The result of processing the modify request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyAssuranceCompleted

        public java.lang.CharSequence logModifyAssuranceCompleted​(CompletedOperationContext opContext,
                                                          ModifyRequest request,
                                                          ModifyResult result,
                                                          AssuredReplicationResult assuranceResult)
        Logs a message about the result of replication assurance processing for a modify operation.
        Parameters:
        opContext - The operation context for the modify operation.
        request - The modify request that was received.
        result - The result of processing the modify request.
        assuranceResult - The replication assurance processing result.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyDNRequest

        public java.lang.CharSequence logModifyDNRequest​(OperationContext opContext,
                                                 ModifyDNRequest request)
        Logs a message about a modify DN request received from a client.
        Parameters:
        opContext - The operation context for the modify DN operation.
        request - The modify DN request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyDNForward

        public java.lang.CharSequence logModifyDNForward​(OperationContext opContext,
                                                 ModifyDNRequest request,
                                                 ForwardTarget target)
        Logs a message about a modify DN request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the modify DN operation.
        request - The modify DN request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyDNForwardFailure

        public java.lang.CharSequence logModifyDNForwardFailure​(OperationContext opContext,
                                                        ModifyDNRequest request,
                                                        ForwardTarget target,
                                                        LDAPException failure)
        Logs a message about a failure encountered while attempting to forward a modify DN request to another server.
        Parameters:
        opContext - The operation context for the modify DN operation.
        request - The modify DN request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyDNResponse

        public java.lang.CharSequence logModifyDNResponse​(CompletedOperationContext opContext,
                                                  ModifyDNRequest request,
                                                  ModifyDNResult result)
        Logs a message about the result of processing a modify DN request.
        Parameters:
        opContext - The operation context for the modify DN operation.
        request - The modify DN request that was received.
        result - The result of processing the modify DN request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logModifyDNAssuranceCompleted

        public java.lang.CharSequence logModifyDNAssuranceCompleted​(CompletedOperationContext opContext,
                                                            ModifyDNRequest request,
                                                            ModifyDNResult result,
                                                            AssuredReplicationResult assuranceResult)
        Logs a message about the result of replication assurance processing for a modify DN operation.
        Parameters:
        opContext - The operation context for the modify DN operation.
        request - The modify DN request that was received.
        result - The result of processing the modify DN request.
        assuranceResult - The replication assurance processing result.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logSearchRequest

        public java.lang.CharSequence logSearchRequest​(OperationContext opContext,
                                               SearchRequest request)
        Logs a message about a search request received from a client.
        Parameters:
        opContext - The operation context for the search operation.
        request - The search request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logSearchForward

        public java.lang.CharSequence logSearchForward​(OperationContext opContext,
                                               SearchRequest request,
                                               ForwardTarget target)
        Logs a message about a search request that will be forwarded to another server.
        Parameters:
        opContext - The operation context for the search operation.
        request - The search request that was received.
        target - Information about the server to which the request will be forwarded.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logSearchForwardFailure

        public java.lang.CharSequence logSearchForwardFailure​(OperationContext opContext,
                                                      SearchRequest request,
                                                      ForwardTarget target,
                                                      LDAPException failure)
        Logs a message about a failure encountered while attempting to forward a search request to another server.
        Parameters:
        opContext - The operation context for the search operation.
        request - The search request that was received.
        target - Information about the server to which the request was forwarded.
        failure - The exception that was received when attempting to forward the request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logSearchResultEntry

        public java.lang.CharSequence logSearchResultEntry​(OperationContext opContext,
                                                   SearchRequest request,
                                                   Entry entry,
                                                   java.util.List<Control> controls)
        Logs a message about a search result entry that was returned to the client.
        Parameters:
        opContext - The operation context for the search operation.
        request - The search request that was received.
        entry - The entry that was returned.
        controls - The set of controls included with the entry, or an empty list if there were none.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logSearchResultReference

        public java.lang.CharSequence logSearchResultReference​(OperationContext opContext,
                                                       SearchRequest request,
                                                       java.util.List<java.lang.String> referralURLs,
                                                       java.util.List<Control> controls)
        Logs a message about a search result reference that was returned to the client.
        Parameters:
        opContext - The operation context for the search operation.
        request - The search request that was received.
        referralURLs - The referral URLs for the reference that was returned.
        controls - The set of controls included with the reference, or an empty list if there were none.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logSearchResultDone

        public java.lang.CharSequence logSearchResultDone​(CompletedSearchOperationContext opContext,
                                                  SearchRequest request,
                                                  SearchResult result)
        Logs a message about the result of processing a search request.
        Parameters:
        opContext - The operation context for the search operation.
        request - The search request that was received.
        result - The result of processing the search request.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logUnbindRequest

        public java.lang.CharSequence logUnbindRequest​(OperationContext opContext,
                                               UnbindRequest request)
        Logs a message about an unbind request received from a client.
        Parameters:
        opContext - The operation context for the unbind operation.
        request - The unbind request that was received.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logIntermediateResponse

        public java.lang.CharSequence logIntermediateResponse​(OperationContext opContext,
                                                      IntermediateResponse intermediateResponse)
        Logs a message about an intermediate response that was returned to the client.
        Parameters:
        opContext - The operation context for the associated operation.
        intermediateResponse - The intermediate response that was returned.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logEntryRebalancingRequest

        public java.lang.CharSequence logEntryRebalancingRequest​(long rebalancingOperationID,
                                                         OperationContext triggerOperation,
                                                         java.lang.String baseDN,
                                                         int sizeLimit,
                                                         java.lang.String sourceBackendSetName,
                                                         java.lang.String sourceAddress,
                                                         int sourcePort,
                                                         java.lang.String targetBackendSetName,
                                                         java.lang.String targetAddress,
                                                         int targetPort)
        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.
        Parameters:
        rebalancingOperationID - The unique ID assigned to the entry balancing operation.
        triggerOperation - The operation that triggered the entry rebalancing. It may be null if the rebalancing operation wasn't triggered by a client request.
        baseDN - The base DN of the subtree to migrate.
        sizeLimit - The maximum number of entries to migrate.
        sourceBackendSetName - The name of the backend set containing the subtree to migrate.
        sourceAddress - The address of the server from which the source entries will be read.
        sourcePort - The port of the server from which the source entries will be read.
        targetBackendSetName - The name of the backend set to which the subtree will be migrated.
        targetAddress - The address of the server to which the subtree will be migrated.
        targetPort - The port of the server to which the subtree will be migrated.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • logEntryRebalancingResult

        public java.lang.CharSequence logEntryRebalancingResult​(long rebalancingOperationID,
                                                        OperationContext triggerOperation,
                                                        java.lang.String baseDN,
                                                        int sizeLimit,
                                                        java.lang.String sourceBackendSetName,
                                                        java.lang.String sourceAddress,
                                                        int sourcePort,
                                                        java.lang.String targetBackendSetName,
                                                        java.lang.String targetAddress,
                                                        int targetPort,
                                                        MoveSubtreeResult moveSubtreeResult)
        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.
        Parameters:
        rebalancingOperationID - The unique ID assigned to the entry balancing operation.
        triggerOperation - The operation that triggered the entry rebalancing. It may be null if the rebalancing operation wasn't triggered by a client request.
        baseDN - The base DN of the subtree to migrate.
        sizeLimit - The maximum number of entries to migrate.
        sourceBackendSetName - The name of the backend set containing the subtree to migrate.
        sourceAddress - The address of the server from which the source entries will be read.
        sourcePort - The port of the server from which the source entries will be read.
        targetBackendSetName - The name of the backend set to which the subtree will be migrated.
        targetAddress - The address of the server to which the subtree will be migrated.
        targetPort - The port of the server to which the subtree will be migrated.
        moveSubtreeResult - An object with information about the result of the subtree move processing.
        Returns:
        The content of the log message that should be written. It may be null or empty if no message should be written. It may optionally include line breaks if the log message should span multiple lines.

      • getExamplesArgumentSets

        public java.util.Map<java.util.List<java.lang.String>,​java.lang.String> getExamplesArgumentSets()
        Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.
        Specified by:
        getExamplesArgumentSets in interface ExampleUsageProvider
        Returns:
        A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.