From 03fced4b614b75252b9463e2a6583f8cdfd2941c Mon Sep 17 00:00:00 2001 From: Thomas Neidhart Date: Sat, 12 Jan 2013 15:08:32 +0000 Subject: [PATCH] Formatting and javadoc cleanup. git-svn-id: https://svn.apache.org/repos/asf/commons/proper/logging/trunk@1432446 13f79535-47bb-0310-9956-ffa450edef68 --- src/java/org/apache/commons/logging/Log.java | 120 +++++++----------- .../logging/LogConfigurationException.java | 23 +--- .../apache/commons/logging/LogFactory.java | 104 +++++---------- .../org/apache/commons/logging/LogSource.java | 65 +++------- 4 files changed, 106 insertions(+), 206 deletions(-) diff --git a/src/java/org/apache/commons/logging/Log.java b/src/java/org/apache/commons/logging/Log.java index 64a73ff..2df6a2e 100644 --- a/src/java/org/apache/commons/logging/Log.java +++ b/src/java/org/apache/commons/logging/Log.java @@ -15,16 +15,15 @@ * limitations under the License. */ - package org.apache.commons.logging; /** - *

A simple logging interface abstracting logging APIs. In order to be + * A simple logging interface abstracting logging APIs. In order to be * instantiated successfully by {@link LogFactory}, classes that implement * this interface must have a constructor that takes a single String - * parameter representing the "name" of this Log.

- * - *

The six logging levels used by Log are (in order): + * parameter representing the "name" of this Log. + *

+ * The six logging levels used by Log are (in order): *

    *
  1. trace (the least serious)
    2. *
  2. debug
    3. @@ -36,25 +35,24 @@ package org.apache.commons.logging; * The mapping of these log levels to the concepts used by the underlying * logging system is implementation dependent. * The implementation should ensure, though, that this ordering behaves - * as expected.

    - * - *

    Performance is often a logging concern. + * as expected. + *

    + * Performance is often a logging concern. * By examining the appropriate property, * a component can avoid expensive operations (producing information - * to be logged).

    - * - *

    For example, + * to be logged). + *

    + * For example, * 

      *    if (log.isDebugEnabled()) {
  *        ... do something expensive ...
  *        log.debug(theResult);
  *    }
  *
    - *

    - * - *

    Configuration of the underlying logging system will generally be done + *

    + * Configuration of the underlying logging system will generally be done * external to the Logging APIs, through whatever mechanism is supported by - * that system.

    + * that system. * * @author Scott Sanders * @author Rod Waldhoff @@ -62,163 +60,145 @@ package org.apache.commons.logging; */ public interface Log { - // ----------------------------------------------------- Logging Properties - /** - *

    Is debug logging currently enabled?

    - * - *

    Call this method to prevent having to perform expensive operations + * Is debug logging currently enabled? + *

    + * Call this method to prevent having to perform expensive operations * (for example, String concatenation) - * when the log level is more than debug.

    + * when the log level is more than debug. * * @return true if debug is enabled in the underlying logger. */ public boolean isDebugEnabled(); - /** - *

    Is error logging currently enabled?

    - * - *

    Call this method to prevent having to perform expensive operations + * Is error logging currently enabled? + *

    + * Call this method to prevent having to perform expensive operations * (for example, String concatenation) - * when the log level is more than error.

    + * when the log level is more than error. * * @return true if error is enabled in the underlying logger. */ public boolean isErrorEnabled(); - /** - *

    Is fatal logging currently enabled?

    - * - *

    Call this method to prevent having to perform expensive operations + * Is fatal logging currently enabled? + *

    + * Call this method to prevent having to perform expensive operations * (for example, String concatenation) - * when the log level is more than fatal.

    + * when the log level is more than fatal. * * @return true if fatal is enabled in the underlying logger. */ public boolean isFatalEnabled(); - /** - *

    Is info logging currently enabled?

    - * - *

    Call this method to prevent having to perform expensive operations + * Is info logging currently enabled? + *

    + * Call this method to prevent having to perform expensive operations * (for example, String concatenation) - * when the log level is more than info.

    + * when the log level is more than info. * * @return true if info is enabled in the underlying logger. */ public boolean isInfoEnabled(); - /** - *

    Is trace logging currently enabled?

    - * - *

    Call this method to prevent having to perform expensive operations + * Is trace logging currently enabled? + *

    + * Call this method to prevent having to perform expensive operations * (for example, String concatenation) - * when the log level is more than trace.

    + * when the log level is more than trace. * * @return true if trace is enabled in the underlying logger. */ public boolean isTraceEnabled(); - /** - *

    Is warn logging currently enabled?

    - * - *

    Call this method to prevent having to perform expensive operations + * Is warn logging currently enabled? + *

    + * Call this method to prevent having to perform expensive operations * (for example, String concatenation) - * when the log level is more than warn.

    + * when the log level is more than warn. * * @return true if warn is enabled in the underlying logger. */ public boolean isWarnEnabled(); - // -------------------------------------------------------- Logging Methods - /** - *

    Log a message with trace log level.

    + * Log a message with trace log level. * * @param message log this message */ public void trace(Object message); - /** - *

    Log an error with trace log level.

    + * Log an error with trace log level. * * @param message log this message * @param t log this cause */ public void trace(Object message, Throwable t); - /** - *

    Log a message with debug log level.

    + * Log a message with debug log level. * * @param message log this message */ public void debug(Object message); - /** - *

    Log an error with debug log level.

    + * Log an error with debug log level. * * @param message log this message * @param t log this cause */ public void debug(Object message, Throwable t); - /** - *

    Log a message with info log level.

    + * Log a message with info log level. * * @param message log this message */ public void info(Object message); - /** - *

    Log an error with info log level.

    + * Log an error with info log level. * * @param message log this message * @param t log this cause */ public void info(Object message, Throwable t); - /** - *

    Log a message with warn log level.

    + * Log a message with warn log level. * * @param message log this message */ public void warn(Object message); - /** - *

    Log an error with warn log level.

    + * Log an error with warn log level. * * @param message log this message * @param t log this cause */ public void warn(Object message, Throwable t); - /** - *

    Log a message with error log level.

    + * Log a message with error log level. * * @param message log this message */ public void error(Object message); - /** - *

    Log an error with error log level.

    + * Log an error with error log level. * * @param message log this message * @param t log this cause @@ -227,7 +207,7 @@ public interface Log { /** - *

    Log a message with fatal log level.

    + * Log a message with fatal log level. * * @param message log this message */ @@ -235,12 +215,10 @@ public interface Log { /** - *

    Log an error with fatal log level.

    + * Log an error with fatal log level. * * @param message log this message * @param t log this cause */ public void fatal(Object message, Throwable t); - - } diff --git a/src/java/org/apache/commons/logging/LogConfigurationException.java b/src/java/org/apache/commons/logging/LogConfigurationException.java index 9c9ab3f..61ae3f3 100644 --- a/src/java/org/apache/commons/logging/LogConfigurationException.java +++ b/src/java/org/apache/commons/logging/LogConfigurationException.java @@ -17,40 +17,32 @@ package org.apache.commons.logging; - /** - *

    An exception that is thrown only if a suitable LogFactory + * An exception that is thrown only if a suitable LogFactory * or Log instance cannot be created by the corresponding - * factory methods.

    + * factory methods. * * @author Craig R. McClanahan * @version $Id$ */ public class LogConfigurationException extends RuntimeException { - /** * Construct a new exception with null as its detail message. */ public LogConfigurationException() { - super(); - } - /** * Construct a new exception with the specified detail message. * * @param message The detail message */ public LogConfigurationException(String message) { - super(message); - } - /** * Construct a new exception with the specified cause and a derived * detail message. @@ -58,12 +50,9 @@ public class LogConfigurationException extends RuntimeException { * @param cause The underlying cause */ public LogConfigurationException(Throwable cause) { - this(cause == null ? null : cause.toString(), cause); - } - /** * Construct a new exception with the specified detail message and cause. * @@ -71,27 +60,19 @@ public class LogConfigurationException extends RuntimeException { * @param cause The underlying cause */ public LogConfigurationException(String message, Throwable cause) { - super(message + " (Caused by " + cause + ")"); this.cause = cause; // Two-argument version requires JDK 1.4 or later - } - /** * The underlying cause of this exception. */ protected Throwable cause = null; - /** * Return the underlying cause of this exception (if any). */ public Throwable getCause() { - return this.cause; - } - - } diff --git a/src/java/org/apache/commons/logging/LogFactory.java b/src/java/org/apache/commons/logging/LogFactory.java index 72b22db..e1e3b2c 100644 --- a/src/java/org/apache/commons/logging/LogFactory.java +++ b/src/java/org/apache/commons/logging/LogFactory.java @@ -17,7 +17,6 @@ package org.apache.commons.logging; - import java.io.BufferedReader; import java.io.FileOutputStream; import java.io.IOException; @@ -34,15 +33,14 @@ import java.util.Enumeration; import java.util.Hashtable; import java.util.Properties; - /** - *

    Factory for creating {@link Log} instances, with discovery and + * Factory for creating {@link Log} instances, with discovery and * configuration features similar to that employed by standard Java APIs - * such as JAXP.

    - * - *

    IMPLEMENTATION NOTE - This implementation is heavily + * such as JAXP. + *

    + * IMPLEMENTATION NOTE - This implementation is heavily * based on the SAXParserFactory and DocumentBuilderFactory implementations - * (corresponding to the JAXP pluggability APIs) found in Apache Xerces.

    + * (corresponding to the JAXP pluggability APIs) found in Apache Xerces. * * @author Craig R. McClanahan * @author Costin Manolache @@ -75,7 +73,6 @@ public abstract class LogFactory { // lib and JCL have the necessary permissions even when the untrusted // caller does not. That's a pretty hard route to exploit though. - // ----------------------------------------------------- Manifest Constants /** @@ -98,26 +95,22 @@ public abstract class LogFactory { * class name. This can be used as a system property, or as an entry in a * configuration properties file. */ - public static final String FACTORY_PROPERTY = - "org.apache.commons.logging.LogFactory"; + public static final String FACTORY_PROPERTY = "org.apache.commons.logging.LogFactory"; /** * The fully qualified class name of the fallback LogFactory * implementation class to use, if no other can be found. */ - public static final String FACTORY_DEFAULT = - "org.apache.commons.logging.impl.LogFactoryImpl"; + public static final String FACTORY_DEFAULT = "org.apache.commons.logging.impl.LogFactoryImpl"; /** * The name (commons-logging.properties) of the properties file to search for. */ - public static final String FACTORY_PROPERTIES = - "commons-logging.properties"; + public static final String FACTORY_PROPERTIES = "commons-logging.properties"; /** * JDK1.3+ * 'Service Provider' specification. - * */ protected static final String SERVICE_ID = "META-INF/services/org.apache.commons.logging.LogFactory"; @@ -192,6 +185,7 @@ 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"; @@ -207,7 +201,6 @@ public abstract class LogFactory { // ----------------------------------------------------------- Constructors - /** * Protected constructor that is not available for public use. */ @@ -216,7 +209,6 @@ public abstract class LogFactory { // --------------------------------------------------------- Public Methods - /** * Return the configuration attribute with the specified name (if any), * or null if there is no such attribute. @@ -225,7 +217,6 @@ public abstract class LogFactory { */ public abstract Object getAttribute(String name); - /** * Return an array containing the names of all currently defined * configuration attributes. If there are no such attributes, a zero @@ -233,41 +224,38 @@ public abstract class LogFactory { */ public abstract String[] getAttributeNames(); - /** * Convenience method to derive a name from the specified class and * call getInstance(String) with it. * * @param clazz Class for which a suitable Log name will be derived * - * @exception LogConfigurationException if a suitable Log + * @throws LogConfigurationException if a suitable Log * instance cannot be returned */ public abstract Log getInstance(Class clazz) throws LogConfigurationException; - /** - *

    Construct (if necessary) and return a Log instance, - * using the factory's current set of configuration attributes.

    - * - *

    NOTE - Depending upon the implementation of + * Construct (if necessary) and return a Log instance, + * using the factory's current set of configuration attributes. + *

    + * NOTE - Depending upon the implementation of * the LogFactory you are using, the Log * instance you are returned may or may not be local to the current * application, and may or may not be returned again on a subsequent - * call with the same name argument.

    + * call with the same name argument. * * @param name Logical name of the Log instance to be * returned (the meaning of this name is only known to the underlying * logging implementation that is being wrapped) * - * @exception LogConfigurationException if a suitable Log + * @throws LogConfigurationException if a suitable Log * instance cannot be returned */ public abstract Log getInstance(String name) throws LogConfigurationException; - /** * Release any internal references to previously created {@link Log} * instances returned by this factory. This is useful in environments @@ -277,7 +265,6 @@ public abstract class LogFactory { */ public abstract void release(); - /** * Remove any configuration attribute associated with the specified name. * If there is no such attribute, no action is taken. @@ -286,7 +273,6 @@ public abstract class LogFactory { */ public abstract void removeAttribute(String name); - /** * Set the configuration attribute with the specified name. Calling * this with a null value is equivalent to calling @@ -298,10 +284,8 @@ public abstract class LogFactory { */ public abstract void setAttribute(String name, Object value); - // ------------------------------------------------------- Static Variables - /** * The previously constructed LogFactory instances, keyed by * the ClassLoader with which it was created. @@ -377,7 +361,6 @@ public abstract class LogFactory { return result; } - // --------------------------------------------------------- Static Methods /** Utility method to safely trim a string. */ @@ -389,9 +372,10 @@ public abstract class LogFactory { } /** - *

    Construct (if necessary) and return a LogFactory + * Construct (if necessary) and return a LogFactory * instance, using the following ordered lookup procedure to determine - * the name of the implementation class to be loaded.

    + * the name of the implementation class to be loaded. + *

    *

    - * - *

    NOTE - If the properties file method of identifying the + *

    + * NOTE - If the properties file method of identifying the * LogFactory implementation class is utilized, all of the * properties defined in this file will be set as configuration attributes - * on the corresponding LogFactory instance.

    - * - *

    NOTE - In a multi-threaded environment it is possible + * on the corresponding LogFactory instance. + *

    + * NOTE - In a multi-threaded environment it is possible * that two different instances will be returned for the same * classloader environment. - *

    * - * @exception LogConfigurationException if the implementation class is not + * @throws LogConfigurationException if the implementation class is not * available or cannot be instantiated. */ public static LogFactory getFactory() throws LogConfigurationException { @@ -527,7 +510,6 @@ public abstract class LogFactory { throw e; } - // Second, try to find a service by using the JDK1.3 class // discovery mechanism, which involves putting a file with the name // of an interface class in the META-INF/services directory, where the @@ -591,7 +573,6 @@ public abstract class LogFactory { } } - // Third try looking into the properties file read earlier (if found) if (factory == null) { @@ -627,7 +608,6 @@ public abstract class LogFactory { } } - // Fourth, try the fallback implementation class if (factory == null) { @@ -669,14 +649,13 @@ public abstract class LogFactory { return factory; } - /** * Convenience method to return a named logger, without the application * having to care about factories. * * @param clazz Class from which a log name will be derived * - * @exception LogConfigurationException if a suitable Log + * @throws LogConfigurationException if a suitable Log * instance cannot be returned */ public static Log getLog(Class clazz) @@ -686,7 +665,6 @@ public abstract class LogFactory { } - /** * Convenience method to return a named logger, without the application * having to care about factories. @@ -695,7 +673,7 @@ public abstract class LogFactory { * returned (the meaning of this name is only known to the underlying * logging implementation that is being wrapped) * - * @exception LogConfigurationException if a suitable Log + * @throws LogConfigurationException if a suitable Log * instance cannot be returned */ public static Log getLog(String name) @@ -705,7 +683,6 @@ public abstract class LogFactory { } - /** * Release any internal references to previously created {@link LogFactory} * instances that have been associated with the specified class loader @@ -738,7 +715,6 @@ public abstract class LogFactory { } - /** * Release any internal references to previously created {@link LogFactory} * instances, after calling the instance method release() on @@ -748,7 +724,6 @@ public abstract class LogFactory { * garbage collection. */ public static void releaseAll() { - if (isDiagnosticsEnabled()) { logDiagnostic("Releasing factory for all classloaders."); } @@ -767,10 +742,8 @@ public abstract class LogFactory { nullClassLoaderFactory = null; } } - } - // ------------------------------------------------------ Protected Methods /** @@ -858,8 +831,7 @@ public abstract class LogFactory { * @throws SecurityException if the current java security policy doesn't * allow this class to access the context classloader. */ - private static ClassLoader getContextClassLoaderInternal() - throws LogConfigurationException { + private static ClassLoader getContextClassLoaderInternal() throws LogConfigurationException { return (ClassLoader)AccessController.doPrivileged( new PrivilegedAction() { public Object run() { @@ -1054,8 +1026,7 @@ public abstract class LogFactory { protected static LogFactory newFactory(final String factoryClass, final ClassLoader classLoader, final ClassLoader contextClassLoader) - throws LogConfigurationException - { + throws LogConfigurationException { // Note that any unchecked exceptions thrown by the createFactory // method will propagate out of this method; in particular a // ClassCastException can be thrown. @@ -1117,7 +1088,6 @@ public abstract class LogFactory { * @since 1.1 */ protected static Object createFactory(String factoryClass, ClassLoader classLoader) { - // This will be used to diagnose bad configurations // and allow a useful message to be sent to the user Class logFactoryClass = null; @@ -1348,9 +1318,7 @@ public abstract class LogFactory { * been granted permission for that operation. In this case, we need to * run the operation using an AccessController. */ - private static InputStream getResourceAsStream(final ClassLoader loader, - final String name) - { + private static InputStream getResourceAsStream(final ClassLoader loader, final String name) { return (InputStream)AccessController.doPrivileged( new PrivilegedAction() { public Object run() { @@ -1376,9 +1344,7 @@ public abstract class LogFactory { * hasMoreElements method returns false (ie an "empty" enumeration). * If resources could not be listed for some reason, null is returned. */ - private static Enumeration getResources(final ClassLoader loader, - final String name) - { + private static Enumeration getResources(final ClassLoader loader, final String name) { PrivilegedAction action = new PrivilegedAction() { public Object run() { @@ -1413,7 +1379,7 @@ public abstract class LogFactory { * succeed when this jarfile is privileged but the caller is not. * This method must therefore remain private to avoid security issues. *

    - * Null is returned if the URL cannot be opened. + * {@code Null} is returned if the URL cannot be opened. */ private static Properties getProperties(final URL url) { PrivilegedAction action = @@ -1476,9 +1442,7 @@ public abstract class LogFactory { * webapps. Webapps can also use explicit priorities to override a configuration * file in the shared classpath if needed. */ - private static final Properties getConfigurationFile( - ClassLoader classLoader, String fileName) { - + private static final Properties getConfigurationFile(ClassLoader classLoader, String fileName) { Properties props = null; double priority = 0.0; URL propsUrl = null; @@ -1571,7 +1535,7 @@ public abstract class LogFactory { * info to access data that should not be available to it. */ private static String getSystemProperty(final String key, final String def) - throws SecurityException { + throws SecurityException { return (String) AccessController.doPrivileged( new PrivilegedAction() { public Object run() { diff --git a/src/java/org/apache/commons/logging/LogSource.java b/src/java/org/apache/commons/logging/LogSource.java index 92c8b77..5d4681f 100644 --- a/src/java/org/apache/commons/logging/LogSource.java +++ b/src/java/org/apache/commons/logging/LogSource.java @@ -17,13 +17,11 @@ package org.apache.commons.logging; - import java.lang.reflect.Constructor; import java.util.Hashtable; import org.apache.commons.logging.impl.NoOpLog; - /** *

    Factory for creating {@link Log} instances. Applications should call * the makeNewLogInstance() method to instantiate new instances @@ -70,7 +68,6 @@ public class LogSource { /** Constructor for current log class */ static protected Constructor logImplctor = null; - // ----------------------------------------------------- Class Initializers static { @@ -134,24 +131,19 @@ public class LogSource { } - // ------------------------------------------------------------ Constructor - - /** Don't allow others to create instances */ + /** Don't allow others to create instances. */ private LogSource() { } - // ---------------------------------------------------------- Class Methods - /** * Set the log implementation/log implementation factory - * by the name of the class. The given class - * must implement {@link Log}, and provide a constructor that - * takes a single {@link String} argument (containing the name - * of the log). + * by the name of the class. The given class must implement {@link Log}, + * and provide a constructor that takes a single {@link String} argument + * (containing the name of the log). */ static public void setLogImplementation(String classname) throws LinkageError, @@ -167,12 +159,10 @@ public class LogSource { } } - /** - * Set the log implementation/log implementation factory - * by class. The given class must implement {@link Log}, - * and provide a constructor that takes a single {@link String} - * argument (containing the name of the log). + * Set the log implementation/log implementation factory by class. + * The given class must implement {@link Log}, and provide a constructor + * that takes a single {@link String} argument (containing the name of the log). */ static public void setLogImplementation(Class logclass) throws LinkageError, ExceptionInInitializerError, @@ -182,8 +172,7 @@ public class LogSource { logImplctor = logclass.getConstructor(argtypes); } - - /** Get a Log instance by class name */ + /** Get a Log instance by class name. */ static public Log getInstance(String name) { Log log = (Log) logs.get(name); if (null == log) { @@ -193,35 +182,26 @@ public class LogSource { return log; } - - /** Get a Log instance by class */ + /** Get a Log instance by class. */ static public Log getInstance(Class clazz) { return getInstance(clazz.getName()); } - /** - * Create a new {@link Log} implementation, based - * on the given name. + * Create a new {@link Log} implementation, based on the given name. *

    - * The specific {@link Log} implementation returned - * is determined by the value of the - * org.apache.commons.logging.log property. - * The value of org.apache.commons.logging.log may be set to - * the fully specified name of a class that implements - * the {@link Log} interface. This class must also - * have a public constructor that takes a single - * {@link String} argument (containing the name - * of the {@link Log} to be constructed. + * The specific {@link Log} implementation returned is determined by the + * value of the org.apache.commons.logging.log property. The value + * of org.apache.commons.logging.log may be set to the fully specified + * name of a class that implements the {@link Log} interface. This class must + * also have a public constructor that takes a single {@link String} argument + * (containing the name of the {@link Log} to be constructed. *

    - * When org.apache.commons.logging.log is not set, - * or when no corresponding class can be found, - * this method will return a Log4JLogger - * if the log4j Logger class is - * available in the {@link LogSource}'s classpath, or a - * Jdk14Logger if we are on a JDK 1.4 or later system, or - * NoOpLog if neither of the above conditions is true. - * + * When org.apache.commons.logging.log is not set, or when no corresponding + * class can be found, this method will return a Log4JLogger if the log4j Logger + * class is available in the {@link LogSource}'s classpath, or a Jdk14Logger if we + * are on a JDK 1.4 or later system, or NoOpLog if neither of the above conditions is true. + * * @param name the log name (or category) */ static public Log makeNewLogInstance(String name) { @@ -240,7 +220,6 @@ public class LogSource { } - /** * Returns a {@link String} array containing the names of * all logs known to me. @@ -248,6 +227,4 @@ public class LogSource { static public String[] getLogNames() { return (String[]) logs.keySet().toArray(new String[logs.size()]); } - - }