From 796501a41d3929aa07548ccde5c3d69f3e16aadf Mon Sep 17 00:00:00 2001 From: Robert Burrell Donkin Date: Sat, 11 Feb 2006 21:20:55 +0000 Subject: [PATCH] Java documentation improvements: added notes about the value of the constants describes where they might be useful to a user. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@377058 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/commons/logging/LogFactory.java | 30 ++++++++++++------- .../commons/logging/impl/LogFactoryImpl.java | 15 ++++++---- 2 files changed, 28 insertions(+), 17 deletions(-) diff --git a/src/java/org/apache/commons/logging/LogFactory.java b/src/java/org/apache/commons/logging/LogFactory.java index b97d4d3..fe23c0f 100644 --- a/src/java/org/apache/commons/logging/LogFactory.java +++ b/src/java/org/apache/commons/logging/LogFactory.java @@ -54,21 +54,22 @@ public abstract class LogFactory { // ----------------------------------------------------- Manifest Constants /** - * The name of the key in the config file used to specify the priority of - * that particular config file. The associated value is a floating-point - * number; higher values take priority over lower values. + * The name (priority) of the key in the config file used to + * specify the priority of that particular config file. The associated value + * is a floating-point number; higher values take priority over lower values. */ public static final String PRIORITY_KEY = "priority"; /** - * The name of the key in the config file used to specify whether logging - * classes should be loaded via the thread context class loader (TCCL), - * or not. By default, the TCCL is used. + * The name (use_tccl) of the key in the config file used + * to specify whether logging classes should be loaded via the thread + * context class loader (TCCL), or not. By default, the TCCL is used. */ public static final String TCCL_KEY = "use_tccl"; /** - * The name of the property used to identify the LogFactory implementation + * The name (org.apache.commons.logging.LogFactory) of the property + * used to identify the LogFactory implementation * class name. This can be used as a system property, or as an entry in a * configuration properties file. */ @@ -83,7 +84,7 @@ public abstract class LogFactory { "org.apache.commons.logging.impl.LogFactoryImpl"; /** - * The name of the properties file to search for. + * The name (commons-logging.properties) of the properties file to search for. */ public static final String FACTORY_PROPERTIES = "commons-logging.properties"; @@ -97,7 +98,8 @@ public abstract class LogFactory { "META-INF/services/org.apache.commons.logging.LogFactory"; /** - * The name of the property used to enable internal commons-logging + * The name (org.apache.commons.logging.diagnostics.dest) + * of the property used to enable internal commons-logging * diagnostic output, in order to get information on what logging * implementations are being discovered, what classloaders they * are loaded through, etc. @@ -106,6 +108,9 @@ public abstract class LogFactory { * assumed to be the name of a file. The special strings * STDOUT or STDERR (case-sensitive) indicate output to * System.out and System.err respectively. + *

+ * Diagnostic logging should be used only to debug problematic + * configurations and should not be set in normal production use. */ public static final String DIAGNOSTICS_DEST_PROPERTY = "org.apache.commons.logging.diagnostics.dest"; @@ -125,7 +130,9 @@ public abstract class LogFactory { private static String diagnosticPrefix; /** - *

Setting this system property value allows the Hashtable used to store + *

Setting this system property + * (org.apache.commons.logging.LogFactory.HashtableImpl) + * value allows the Hashtable used to store * classloaders to be substituted by an alternative implementation. *

*

@@ -161,7 +168,8 @@ public abstract class LogFactory { public static final String HASHTABLE_IMPLEMENTATION_PROPERTY = "org.apache.commons.logging.LogFactory.HashtableImpl"; /** Name used to load the weak hashtable implementation by names */ - private static final String WEAK_HASHTABLE_CLASSNAME = "org.apache.commons.logging.impl.WeakHashtable"; + private static final String WEAK_HASHTABLE_CLASSNAME = + "org.apache.commons.logging.impl.WeakHashtable"; /** * A reference to the classloader that loaded this class. This is the diff --git a/src/java/org/apache/commons/logging/impl/LogFactoryImpl.java b/src/java/org/apache/commons/logging/impl/LogFactoryImpl.java index 5a3284f..3f800b9 100644 --- a/src/java/org/apache/commons/logging/impl/LogFactoryImpl.java +++ b/src/java/org/apache/commons/logging/impl/LogFactoryImpl.java @@ -95,8 +95,8 @@ public class LogFactoryImpl extends LogFactory { /** - * The name of the system property identifying our {@link Log} - * implementation class. + * The name (org.apache.commons.logging.Log) of the system + * property identifying our {@link Log} implementation class. */ public static final String LOG_PROPERTY = "org.apache.commons.logging.Log"; @@ -104,13 +104,14 @@ public class LogFactoryImpl extends LogFactory { /** * The deprecated system property used for backwards compatibility with - * the old {@link org.apache.commons.logging.LogSource} class. + * old versions of JCL. */ protected static final String LOG_PROPERTY_OLD = "org.apache.commons.logging.log"; /** - * The name of the system property which can be set true/false to + * The name (org.apache.commons.logging.Log.allowFlawedContext) + * of the system property which can be set true/false to * determine system behaviour when a bad context-classloader is encountered. * When set to false * @@ -122,7 +123,8 @@ public class LogFactoryImpl extends LogFactory { "org.apache.commons.logging.Log.allowFlawedContext"; /** - * The name of the system property which can be set true/false to + * The name (org.apache.commons.logging.Log.allowFlawedDiscovery) + * of the system property which can be set true/false to * determine system behaviour when a bad logging adapter class is * encountered during logging discovery. When set to false, an * exception will be thrown and the app will fail to start. When set @@ -137,7 +139,8 @@ public class LogFactoryImpl extends LogFactory { "org.apache.commons.logging.Log.allowFlawedDiscovery"; /** - * The name of the system property which can be set true/false to + * The name (org.apache.commons.logging.Log.allowFlawedHierarchy) + * of the system property which can be set true/false to * determine system behaviour when a logging adapter class is * encountered which has bound to the wrong Log class implementation. * When set to false, an exception will be thrown and the app will fail