Add command-line tool debugging support

Updated the command-line tool framework to make it possible to
include arguments that allow the tool to generate a log file
containing any debug messages generated while the tool was running.
The new --helpDebug argument can be used to obtain usage information
for arguments related to debug logging in any tools that support it.
All of the tools included with the LDAP SDK have been updated to
provide support for debug logging.

Updated the debug logging framework to make it possible to format
debug messages as multi-line strings.  Debug messages will be
generated as JSON objects, but they use a single-line string
representation by default.  It is now possible to generate those
messages as multi-line strings, which may be easier for humans to
read, but may be more difficult for some applications to parse.

docs/release-notes.html

@@ -78,6 +78,25 @@ <h3>Version 7.0.1</h3>
                   <br><br>
                 </li>
 
+                <li>
+                  Updated the command-line tool framework to make it possible to include arguments
+                  that allow the tool to generate a log file containing any debug messages
+                  generated while the tool was running. The new --helpDebug argument can be used to
+                  obtain usage information for arguments related to debug logging in any tools that
+                  support it.  All of the tools included with the LDAP SDK have been updated to
+                  provide support for debug logging.
+                  <br><br>
+                </li>
+
+                <li>
+                  Updated the debug logging framework to make it possible to format debug messages
+                  as multi-line strings.  Debug messages will be generated as JSON objects, but
+                  they use a single-line string representation by default.  It is now possible to
+                  generate those messages as multi-line strings, which may be easier for humans to
+                  read, but may be more difficult for some applications to parse.
+                  <br><br>
+                </li>
+
                 <li>
                   Updated the OID registry to include records for a number of collation matching
                   rules.

messages/unboundid-ldapsdk-util.properties

@@ -101,8 +101,38 @@ INFO_CL_TOOL_DESCRIPTION_TEE_OUTPUT=Write all standard output and standard \
 INFO_CL_TOOL_DESCRIPTION_HELP=Display usage information for this program.
 INFO_CL_TOOL_DESCRIPTION_HELP_SUBCOMMANDS=Display the names and descriptions \
   of the supported subcommands.
+INFO_CL_TOOL_DESCRIPTION_HELP_DEBUG=Display usage information for debug \
+  logging.
+INFO_CL_TOOL_DESCRIPTION_ENABLE_DEBUG=Enables debug logging for the tool.
+INFO_CL_TOOL_DESCRIPTION_DEBUG_LOG_LEVEL=The debug log level to use for the \
+  tool.  Allowed values include ''off'', ''severe'', ''warning'', ''info'', \
+  ''fine'', ''finer'', and ''finest''.  If this is not specified, a default \
+  level of ''severe'' will be used.
+INFO_CL_TOOL_DESCRIPTION_DEBUG_LOG_CATEGORY=The message categories to include \
+  in the debug log output.  Allowed values include ''asn1'', ''connect'', \
+  ''exception'', ''ldap'', ''connectionpool'', ''ldif'', ''monitor'', \
+  ''codingerror'', and ''other''.  This argument may be provided multiple \
+  times to indicate that multiple categories should be included.  If this is \
+  not specified, then all categories will be included.
+INFO_CL_TOOL_DESCRIPTION_INCLUDE_DEBUG_STACK_TRACES=Indicates that debug log \
+  messages should include a stack trace with the code location from which \
+  each debug message originated.
+INFO_CL_TOOL_DESCRIPTION_USE_MULTI_LINE_DEBUG_MESSAGES=Indicates that \
+  debug log messages (which will be JSON objects) should be written as \
+  multi-line strings rather than single-line strings.
+INFO_CL_TOOL_DESCRIPTION_DEBUG_LOG_FILE=The path to the debug log file to be \
+  written.  If this is not specified, a default path of ''{0}'' will be used.
 INFO_CL_TOOL_DESCRIPTION_VERSION=Display version information for this program.
 INFO_CL_TOOL_LABEL_EXAMPLES=Examples
+INFO_CL_TOOL_DEBUG_USAGE_SUMMARY=This tool allows capturing additional debug \
+  information about its internal processing to a specified log file.  \
+  Supported arguments for controlling debug logging include:
+ERR_CL_TOOL_CANNOT_PARSE_DEBUG_LOG_LEVEL=Unable to parse ''{0}'' as a valid \
+  debug log level value.
+ERR_CL_TOOL_CANNOT_PARSE_DEBUG_LOG_CATEGORY=Unable to parse ''{0}'' as a \
+  valid debug log category value.
+ERR_CL_TOOL_CANNOT_CREATE_DEBUG_FILE_HANDLER=An error occurred while \
+  attempting to create a debug handler for logging to file ''{0}'':  {1}
 INFO_LDAP_TOOL_ARG_GROUP_CONNECT=LDAP Connection Arguments
 INFO_LDAP_TOOL_ARG_GROUP_CONNECT_AND_AUTH=LDAP Connection and Authentication \
   Arguments
@@ -1239,6 +1269,8 @@ ERR_BC_FIPS_PROVIDER_CANNOT_INSTANTIATE_JSSE_PROVIDER=An unexpected error \
   provider class ''{0}'':  {1}
 ERR_DEBUG_CANNOT_WRITE_TO_FILE=An unexpected error occurred while attempting \
   to write a debug message to file ''{0}'':  {1}.  The debug message was:  {2}
+ERR_DEBUG_CANNOT_PARSE_LEVEL=Unable to parse value ''{0}'' as a valid debug \
+  log level.
 ERR_GET_NON_BC_FIPS_CLASS_LOADER_UNKNOWN_INSTANCE_ROOT=Unable to create a \
   class loader for accessing non-FIPS-compliant Bouncy Castle functionality \
   because the JVM does not appear to be running within a Ping Identity server \

src/com/unboundid/ldap/listener/InMemoryDirectoryServerTool.java

@@ -1080,6 +1080,17 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * {@inheritDoc}
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * {@inheritDoc}
    */

src/com/unboundid/ldap/sdk/examples/AuthRate.java

@@ -472,6 +472,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/Base64Tool.java

@@ -379,6 +379,22 @@ protected boolean supportsOutputFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Adds the command-line arguments supported for use with this tool to the
    * provided argument parser.  The tool may need to retain references to the

src/com/unboundid/ldap/sdk/examples/IdentifyReferencesToMissingEntries.java

@@ -356,6 +356,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/IdentifyUniqueAttributeConflicts.java

@@ -449,6 +449,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/IndentLDAPFilter.java

@@ -347,6 +347,22 @@ protected boolean supportsOutputFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Adds the command-line arguments supported for use with this tool to the
    * provided argument parser.  The tool may need to retain references to the

src/com/unboundid/ldap/sdk/examples/LDAPCompare.java

@@ -352,6 +352,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/LDAPDebugger.java

@@ -335,6 +335,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/LDAPModify.java

@@ -322,6 +322,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/LDAPSearch.java

@@ -405,6 +405,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether this tool should default to interactively prompting for
    * the bind password if a password is required but no argument was provided

src/com/unboundid/ldap/sdk/examples/ModRate.java

@@ -485,6 +485,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/SearchAndModRate.java

@@ -511,6 +511,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/SearchRate.java

@@ -520,6 +520,22 @@ public boolean supportsPropertiesFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Indicates whether the LDAP-specific arguments should include alternate
    * versions of all long identifiers that consist of multiple words so that

src/com/unboundid/ldap/sdk/examples/TestLDAPSDKPerformance.java

@@ -389,6 +389,22 @@ protected boolean supportsOutputFile()
 
 
 
+  /**
+   * Indicates whether this tool supports the ability to generate a debug log
+   * file.  If this method returns {@code true}, then the tool will expose
+   * additional arguments that can control debug logging.
+   *
+   * @return  {@code true} if this tool supports the ability to generate a debug
+   *          log file, or {@code false} if not.
+   */
+  @Override()
+  protected boolean supportsDebugLogging()
+  {
+    return true;
+  }
+
+
+
   /**
    * Retrieves an optional message that may provide additional information about
    * the way that the tool completed its processing.  For example if the tool