Add a debug log file property

Added support for a new "com.unboundid.ldap.sdk.debug.file" property
that can be used to indicate that LDAP SDK debug log messages should
be written to a specified file.  This is intended to be used in
conjunction with other debugging-related properties that can enable
and configure debug logging without a code change in the underlying
application.  Previously, the output was always written to the JVM's
standard error stream, but this property will cause it to be written
to a file instead.

docs/release-notes.html

@@ -41,6 +41,17 @@ <h3>Version 6.0.1</h3>
                   <br><br>
                 </li>
 
+                <li>
+                  Added support for a new "com.unboundid.ldap.sdk.debug.file" property that can be
+                  used to indicate that LDAP SDK debug log messages should be written to a
+                  specified file.  This is intended to be used in conjunction with other
+                  debugging-related properties that can enable and configure debug logging without
+                  a code change in the underlying application.  Previously, the output was always
+                  written to the JVM's standard error stream, but this property will cause it to
+                  be written to a file instead.
+                  <br><br>
+                </li>
+
                 <li>
                   Lowered the debug level for exception messages that may be logged as a result of
                   a SocketTimeoutException caught internally in the course of trying whether to

src/com/unboundid/util/Debug.java

@@ -44,6 +44,7 @@
 import java.util.Properties;
 import java.util.Set;
 import java.util.StringTokenizer;
+import java.util.logging.FileHandler;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
@@ -170,6 +171,19 @@ public final class Debug
 
 
 
+  /**
+   * The name of the system property that will be used to indicate that debug
+   * log messages should be written to the specified file.  The fully-qualified
+   * name for this property is "{@code com.unboundid.ldap.sdk.debug.file}".  If
+   * it is set, then its value should be a pattern that describes the path to
+   * the log file to create as described in the Javadoc documentation for the
+   * {@code java.util.logging.FileHandler} class.
+   */
+  @NotNull public static final String PROPERTY_DEBUG_FILE =
+       "com.unboundid.ldap.sdk.debug.file";
+
+
+
   /**
    * The name that will be used for the Java logger that will actually handle
    * the debug messages if debugging is enabled.
@@ -219,6 +233,26 @@ public final class Debug
     initialize(StaticUtils.getSystemProperties(PROPERTY_DEBUG_ENABLED,
          PROPERTY_DEBUG_LEVEL, PROPERTY_DEBUG_TYPE,
          PROPERTY_INCLUDE_STACK_TRACE));
+
+    final String logFilePropertyValue =
+         StaticUtils.getSystemProperty(PROPERTY_DEBUG_FILE);
+    if (logFilePropertyValue != null)
+    {
+      try
+      {
+        logger.setUseParentHandlers(false);
+
+        final FileHandler fileHandler =
+             new FileHandler(logFilePropertyValue, true);
+        fileHandler.setFormatter(
+             new MinimalLogFormatter(null, false, false, true));
+        logger.addHandler(fileHandler);
+      }
+      catch (final Exception e)
+      {
+        throw new RuntimeException(e);
+      }
+    }
   }
 
 

tests/unit/src/com/unboundid/ldap/sdk/ProhibitedMethodCallsTestCase.java

@@ -298,7 +298,7 @@ public void testLoggerLogLevel(final File f)
          throws Exception
   {
     final Map<String,Set<Integer>> allowedExceptions = StaticUtils.mapOf(
-         "Debug.java", StaticUtils.setOf(91),
+         "Debug.java", StaticUtils.setOf(92),
          "StaticUtils.java", StaticUtils.setOf(563, 586));
 
     final Map<Integer,String> unwrappedLines =