com.unboundid.directory.sdk.common.api

Class FileBasedAccessLogger

java.lang.Object

com.unboundid.directory.sdk.common.api.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 Summary

Constructors

Constructor and Description
FileBasedAccessLogger() Creates a new instance of this file-based access logger.

Method Summary

Modifier and Type	Method and Description
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.
void	defineConfigArguments(ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizeAccessLogger() Performs any cleanup which may be necessary when this file-based access logger is to be taken out of service.
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.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
void	initializeAccessLogger(ServerContext serverContext, FileBasedAccessLoggerConfig config, ArgumentParser parser) Initializes this file-based access logger.
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.
java.lang.CharSequence	logAbandonForward(OperationContext opContext, AbandonRequest request, ForwardTarget target) Logs a message about an abandon request that will be forwarded to another server.
java.lang.CharSequence	logAbandonRequest(OperationContext opContext, AbandonRequest request) Logs a message about an abandon request received from a client.
java.lang.CharSequence	logAbandonResult(CompletedOperationContext opContext, AbandonRequest request, GenericResult result) Logs a message about the result of processing an abandon request.
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.
java.lang.CharSequence	logAddForward(OperationContext opContext, AddRequest request, ForwardTarget target) Logs a message about an add request that will be forwarded to another server.
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.
java.lang.CharSequence	logAddRequest(OperationContext opContext, AddRequest request) Logs a message about an add request received from a client.
java.lang.CharSequence	logAddResponse(CompletedOperationContext opContext, AddRequest request, AddResult result) Logs a message about the result of processing an add request.
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.
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.
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.
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.
java.lang.CharSequence	logBindRequest(OperationContext opContext, SASLBindRequest request) Logs a message about a SASL bind request received from a client.
java.lang.CharSequence	logBindRequest(OperationContext opContext, SimpleBindRequest request) Logs a message about a simple bind request received from a client.
java.lang.CharSequence	logBindResponse(CompletedOperationContext opContext, SASLBindRequest request, BindResult result) Logs a message about the result of processing a SASL bind request.
java.lang.CharSequence	logBindResponse(CompletedOperationContext opContext, SimpleBindRequest request, BindResult result) Logs a message about the result of processing a simple bind request.
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.
java.lang.CharSequence	logCompareForward(OperationContext opContext, CompareRequest request, ForwardTarget target) Logs a message about a compare request that will be forwarded to another server.
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.
java.lang.CharSequence	logCompareRequest(OperationContext opContext, CompareRequest request) Logs a message about a compare request received from a client.
java.lang.CharSequence	logCompareResponse(CompletedOperationContext opContext, CompareRequest request, CompareResult result) Logs a message about the result of processing a compare request.
java.lang.CharSequence	logConnect(ClientContext clientContext) Logs a message indicating that a new connection has been established.
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.
java.lang.CharSequence	logDeleteForward(OperationContext opContext, DeleteRequest request, ForwardTarget target) Logs a message about a delete request that will be forwarded to another server.
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.
java.lang.CharSequence	logDeleteRequest(OperationContext opContext, DeleteRequest request) Logs a message about a delete request received from a client.
java.lang.CharSequence	logDeleteResponse(CompletedOperationContext opContext, DeleteRequest request, DeleteResult result) Logs a message about the result of processing a delete request.
java.lang.CharSequence	logDisconnect(ClientContext clientContext, DisconnectReason disconnectReason, java.lang.String message) Logs a message indicating that a connection has been closed.
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.
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.
java.lang.CharSequence	logExtendedForward(OperationContext opContext, ExtendedRequest request, ForwardTarget target) Logs a message about an extended request that will be forwarded to another server.
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.
java.lang.CharSequence	logExtendedRequest(OperationContext opContext, ExtendedRequest request) Logs a message about an extended request received from a client.
java.lang.CharSequence	logExtendedResponse(CompletedOperationContext opContext, ExtendedRequest request, ExtendedResult result) Logs a message about the result of processing an extended request.
java.lang.CharSequence	logIntermediateResponse(OperationContext opContext, IntermediateResponse intermediateResponse) Logs a message about an intermediate response that was returned to the client.
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.
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.
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.
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.
java.lang.CharSequence	logModifyDNRequest(OperationContext opContext, ModifyDNRequest request) Logs a message about a modify DN request received from a client.
java.lang.CharSequence	logModifyDNResponse(CompletedOperationContext opContext, ModifyDNRequest request, ModifyDNResult result) Logs a message about the result of processing a modify DN request.
java.lang.CharSequence	logModifyForward(OperationContext opContext, ModifyRequest request, ForwardTarget target) Logs a message about a modify request that will be forwarded to another server.
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.
java.lang.CharSequence	logModifyRequest(OperationContext opContext, ModifyRequest request) Logs a message about a modify request received from a client.
java.lang.CharSequence	logModifyResponse(CompletedOperationContext opContext, ModifyRequest request, ModifyResult result) Logs a message about the result of processing a modify request.
java.lang.CharSequence	logSearchForward(OperationContext opContext, SearchRequest request, ForwardTarget target) Logs a message about a search request that will be forwarded to another server.
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.
java.lang.CharSequence	logSearchRequest(OperationContext opContext, SearchRequest request) Logs a message about a search request received from a client.
java.lang.CharSequence	logSearchResultDone(CompletedSearchOperationContext opContext, SearchRequest request, SearchResult result) Logs a message about the result of processing a search request.
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.
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.
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.
java.lang.CharSequence	logUnbindRequest(OperationContext opContext, UnbindRequest request) Logs a message about an unbind request received from a client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

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.