changeset 421:8dfe14917105

6949710: 3/3 the GC'able nature of Logging objects needs to be made brutally clear Summary: Add words in more places to make it clear that Logger objects are GC'able unless there is a strong reference. Reviewed-by: dholmes, andrew, minqi
author dcubed
date Wed, 22 Sep 2010 09:57:07 -0700
parents bf87d5af4361
children 2e8ca9a18288 068cae30ff10
files src/share/classes/java/util/logging/LogManager.java src/share/classes/java/util/logging/Logger.java
diffstat 2 files changed, 40 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/logging/LogManager.java	Mon Sep 20 13:59:16 2010 +0200
+++ b/src/share/classes/java/util/logging/LogManager.java	Wed Sep 22 09:57:07 2010 -0700
@@ -680,6 +680,11 @@
      * Note that since untrusted code may create loggers with
      * arbitrary names this method should not be relied on to
      * find Loggers for security sensitive logging.
+     * It is also important to note that the Logger associated with the
+     * String {@code name} may be garbage collected at any time if there
+     * is no strong reference to the Logger. The caller of this method
+     * must check the return value for null in order to properly handle
+     * the case where the Logger has been garbage collected.
      * <p>
      * @param name name of the logger
      * @return  matching logger or null if none is found
@@ -703,6 +708,14 @@
      * <p>
      * Note:  Loggers may be added dynamically as new classes are loaded.
      * This method only reports on the loggers that are currently registered.
+     * It is also important to note that this method only returns the name
+     * of a Logger, not a strong reference to the Logger itself.
+     * The returned String does nothing to prevent the Logger from being
+     * garbage collected. In particular, if the returned name is passed
+     * to {@code LogManager.getLogger()}, then the caller must check the
+     * return value from {@code LogManager.getLogger()} for null to properly
+     * handle the case where the Logger has been garbage collected in the
+     * time since its name was returned by this method.
      * <p>
      * @return  enumeration of logger name strings
      */
--- a/src/share/classes/java/util/logging/Logger.java	Mon Sep 20 13:59:16 2010 +0200
+++ b/src/share/classes/java/util/logging/Logger.java	Wed Sep 22 09:57:07 2010 -0700
@@ -41,7 +41,10 @@
  * <p>
  * Logger objects may be obtained by calls on one of the getLogger
  * factory methods.  These will either create a new Logger or
- * return a suitable existing Logger.
+ * return a suitable existing Logger. It is important to note that
+ * the Logger returned by one of the {@code getLogger} factory methods
+ * may be garbage collected at any time if a strong reference to the
+ * Logger is not kept.
  * <p>
  * Logging messages will be forwarded to registered Handler
  * objects, which can forward the messages to a variety of
@@ -192,6 +195,8 @@
      * use of the logging package (for example in products) should create
      * and use their own Logger objects, with appropriate names, so that
      * logging can be controlled on a suitable per-Logger granularity.
+     * Developers also need to keep a strong reference to their Logger
+     * objects to prevent them from being garbage collected.
      * <p>
      * The preferred way to get the global logger object is via the call
      * <code>Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)</code>.
@@ -205,7 +210,9 @@
      * who are making serious use of the logging package (for example
      * in products) should create and use their own Logger objects,
      * with appropriate names, so that logging can be controlled on a
-     * suitable per-Logger granularity.
+     * suitable per-Logger granularity. Developers also need to keep a
+     * strong reference to their Logger objects to prevent them from
+     * being garbage collected.
      * <p>
      * @deprecated Initialization of this field is prone to deadlocks.
      * The field must be initialized by the Logger class initialization
@@ -278,6 +285,15 @@
      * based on the LogManager configuration and it will configured
      * to also send logging output to its parent's handlers.  It will
      * be registered in the LogManager global namespace.
+     * <p>
+     * Note: The LogManager may only retain a weak reference to the newly
+     * created Logger. It is important to understand that a previously
+     * created Logger with the given name may be garbage collected at any
+     * time if there is no strong reference to the Logger. In particular,
+     * this means that two back-to-back calls like
+     * {@code getLogger("MyLogger").log(...)} may use different Logger
+     * objects named "MyLogger" if there is no strong reference to the
+     * Logger named "MyLogger" elsewhere in the program.
      *
      * @param   name            A name for the logger.  This should
      *                          be a dot-separated name and should normally
@@ -302,6 +318,15 @@
      * output to its parent loggers Handlers.  It will be registered in
      * the LogManager global namespace.
      * <p>
+     * Note: The LogManager may only retain a weak reference to the newly
+     * created Logger. It is important to understand that a previously
+     * created Logger with the given name may be garbage collected at any
+     * time if there is no strong reference to the Logger. In particular,
+     * this means that two back-to-back calls like
+     * {@code getLogger("MyLogger", ...).log(...)} may use different Logger
+     * objects named "MyLogger" if there is no strong reference to the
+     * Logger named "MyLogger" elsewhere in the program.
+     * <p>
      * If the named Logger already exists and does not yet have a
      * localization resource bundle then the given resource bundle
      * name is used.  If the named Logger already exists and has