com.unboundid.ldap.sdk.unboundidds.tools

Class ToolInvocationLogger

java.lang.Object

com.unboundid.ldap.sdk.unboundidds.tools.ToolInvocationLogger

@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class ToolInvocationLogger
extends java.lang.Object

This class provides a utility that can log information about the launch and completion of a tool invocation.

NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

Method Summary

Modifier and Type	Method and Description
static ToolInvocationLogDetails	getLogMessageDetails(java.lang.String commandName, boolean logByDefault, java.io.PrintStream toolErrorStream) Retrieves an object with a set of information about the invocation logging that should be performed for the specified tool, if any.
static void	logCompletionMessage(ToolInvocationLogDetails logDetails, java.lang.Integer exitCode, java.lang.String exitMessage) Logs a message about the completion of the specified tool.
static void	logLaunchMessage(ToolInvocationLogDetails logDetails, java.util.List<ObjectPair<java.lang.String,java.lang.String>> commandLineArguments, java.util.List<ObjectPair<java.lang.String,java.lang.String>> propertiesFileArguments, java.lang.String propertiesFilePath) Logs a message about the launch of the specified tool.

Methods inherited from class java.lang.Object

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

Method Detail

getLogMessageDetails

@NotNull
public static ToolInvocationLogDetails getLogMessageDetails(@NotNull
                                                                     java.lang.String commandName,
                                                                     boolean logByDefault,
                                                                     @NotNull
                                                                     java.io.PrintStream toolErrorStream)

Retrieves an object with a set of information about the invocation logging that should be performed for the specified tool, if any.

Parameters:

commandName - The name of the command (without any path information) for the associated tool. It must not be null.

logByDefault - Indicates whether the tool indicates that invocation log messages should be generated for the specified tool by default. This may be overridden by content in the tool-invocation-logging.properties file, but it will be used in the absence of the properties file or if the properties file does not specify whether logging should be performed for the specified tool.

toolErrorStream - A print stream that may be used to report information about any problems encountered while attempting to perform invocation logging. It must not be null.

Returns:

An object with a set of information about the invocation logging that should be performed for the specified tool. The ToolInvocationLogDetails.logInvocation() method may be used to determine whether invocation logging should be performed.

logLaunchMessage

public static void logLaunchMessage(@NotNull
                                    ToolInvocationLogDetails logDetails,
                                    @NotNull
                                    java.util.List<ObjectPair<java.lang.String,java.lang.String>> commandLineArguments,
                                    @NotNull
                                    java.util.List<ObjectPair<java.lang.String,java.lang.String>> propertiesFileArguments,
                                    @NotNull
                                    java.lang.String propertiesFilePath)

Logs a message about the launch of the specified tool. This method must acquire an exclusive lock on each log file before attempting to append any data to it.

Parameters:

logDetails - The tool invocation log details object obtained from running the getLogMessageDetails(java.lang.String, boolean, java.io.PrintStream) method. It must not be null.

commandLineArguments - A list of the name-value pairs for any command-line arguments provided when running the program. This must not be null, but it may be empty.

For a tool run in interactive mode, this should be the arguments that would have been provided if the tool had been invoked non-interactively. For any arguments that have a name but no value (including Boolean arguments and subcommand names), or for unnamed trailing arguments, the first item in the pair should be non-null and the second item should be null. For arguments whose values may contain sensitive information, the value should have already been replaced with the string "*****REDACTED*****".

propertiesFileArguments - A list of the name-value pairs for any arguments obtained from a properties file rather than being supplied on the command line. This must not be null, but may be empty. The same constraints specified for the commandLineArguments parameter also apply to this parameter.

propertiesFilePath - The path to the properties file from which the propertiesFileArguments values were obtained.

logCompletionMessage

public static void logCompletionMessage(@NotNull
                                        ToolInvocationLogDetails logDetails,
                                        @Nullable
                                        java.lang.Integer exitCode,
                                        @Nullable
                                        java.lang.String exitMessage)

Logs a message about the completion of the specified tool. This method must acquire an exclusive lock on each log file before attempting to append any data to it.

Parameters:

logDetails - The tool invocation log details object obtained from running the getLogMessageDetails(java.lang.String, boolean, java.io.PrintStream) method. It must not be null.

exitCode - An integer exit code that may be used to broadly indicate whether the tool completed successfully. A value of zero typically indicates that it did complete successfully, while a nonzero value generally indicates that some error occurred. This may be null if the tool did not complete normally (for example, because the tool processing was interrupted by a JVM shutdown).

exitMessage - An optional message that provides information about the completion of the tool processing. It may be null if no such message is available.