This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-logging.git
commit 42ad2ae0b60a29dd7435f5bfed885b359f93c30b Author: Gary Gregory <[email protected]> AuthorDate: Tue Oct 10 15:22:39 2023 -0400 Fix Javadoc warnings and errors --- .../org/apache/commons/logging/LogFactory.java | 171 +++++++++------------ .../java/org/apache/commons/logging/LogSource.java | 52 +++++-- .../logging/impl/Jdk13LumberjackLogger.java | 12 ++ .../apache/commons/logging/impl/Jdk14Logger.java | 24 +-- .../apache/commons/logging/impl/Log4JLogger.java | 25 +-- .../commons/logging/impl/LogFactoryImpl.java | 104 ++++++------- .../apache/commons/logging/impl/LogKitLogger.java | 4 +- .../org/apache/commons/logging/impl/NoOpLog.java | 88 ++++++++--- .../org/apache/commons/logging/impl/SimpleLog.java | 5 +- .../apache/commons/logging/impl/WeakHashtable.java | 5 +- 10 files changed, 278 insertions(+), 212 deletions(-) diff --git a/src/main/java/org/apache/commons/logging/LogFactory.java b/src/main/java/org/apache/commons/logging/LogFactory.java index 8f1c9ff..150f689 100644 --- a/src/main/java/org/apache/commons/logging/LogFactory.java +++ b/src/main/java/org/apache/commons/logging/LogFactory.java @@ -204,42 +204,37 @@ public abstract class LogFactory { * or {@code null} if there is no such attribute. * * @param name Name of the attribute to return + * @return the configuration attribute with the specified name. */ 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 - * length array is returned. + * Gets an array containing the names of all currently defined configuration attributes. If there are no such attributes, a zero length array is returned. + * + * @return an array containing the names of all currently defined configuration attributes */ public abstract String[] getAttributeNames(); /** - * Convenience method to derive a name from the specified class and - * call {@code getInstance(String)} with it. + * Convenience method to derive a name from the specified class and call {@code getInstance(String)} with it. * * @param clazz Class for which a suitable Log name will be derived - * @throws LogConfigurationException if a suitable {@code Log} - * instance cannot be returned + * @return a name from the specified class. + * @throws LogConfigurationException if a suitable {@code Log} instance cannot be returned */ - public abstract Log getInstance(Class clazz) - throws LogConfigurationException; + public abstract Log getInstance(Class clazz) throws LogConfigurationException; /** - * Construct (if necessary) and return a {@code Log} instance, - * using the factory's current set of configuration attributes. + * Construct (if necessary) and return a {@code Log} instance, using the factory's current set of configuration attributes. * <p> - * <strong>NOTE</strong> - Depending upon the implementation of - * the {@code LogFactory} you are using, the {@code 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. + * <strong>NOTE</strong> - Depending upon the implementation of the {@code LogFactory} you are using, the {@code 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. + * </p> * - * @param name Logical name of the {@code Log} instance to be - * returned (the meaning of this name is only known to the underlying - * logging implementation that is being wrapped) - * @throws LogConfigurationException if a suitable {@code Log} - * instance cannot be returned + * @param name Logical name of the {@code Log} instance to be returned (the meaning of this name is only known to the underlying logging implementation that + * is being wrapped) + * @return a {@code Log} instance. + * @throws LogConfigurationException if a suitable {@code Log} instance cannot be returned */ public abstract Log getInstance(String name) throws LogConfigurationException; @@ -385,34 +380,26 @@ public abstract class LogFactory { } /** - * Construct (if necessary) and return a {@code LogFactory} - * instance, using the following ordered lookup procedure to determine - * the name of the implementation class to be loaded. - * <p> + * Construct (if necessary) and return a {@code LogFactory} instance, using the following ordered lookup procedure to determine the name of the + * implementation class to be loaded. * <ul> - * <li>The {@code org.apache.commons.logging.LogFactory} system - * property.</li> + * <li>The {@code org.apache.commons.logging.LogFactory} system property.</li> * <li>The JDK 1.3 Service Discovery mechanism</li> - * <li>Use the properties file {@code commons-logging.properties} - * file, if found in the class path of this class. The configuration - * file is in standard {@code java.util.Properties} format and - * contains the fully qualified name of the implementation class - * with the key being the system property defined above.</li> - * <li>Fall back to a default implementation class - * ({@code org.apache.commons.logging.impl.LogFactoryImpl}).</li> + * <li>Use the properties file {@code commons-logging.properties} file, if found in the class path of this class. The configuration file is in standard + * {@code java.util.Properties} format and contains the fully qualified name of the implementation class with the key being the system property defined + * above.</li> + * <li>Fall back to a default implementation class ({@code org.apache.commons.logging.impl.LogFactoryImpl}).</li> * </ul> * <p> - * <em>NOTE</em> - If the properties file method of identifying the - * {@code LogFactory} implementation class is utilized, all of the - * properties defined in this file will be set as configuration attributes - * on the corresponding {@code LogFactory} instance. + * <em>NOTE</em> - If the properties file method of identifying the {@code LogFactory} implementation class is utilized, all of the properties defined in + * this file will be set as configuration attributes on the corresponding {@code LogFactory} instance. + * </p> * <p> - * <em>NOTE</em> - In a multi-threaded environment it is possible - * that two different instances will be returned for the same - * classloader environment. + * <em>NOTE</em> - In a multi-threaded environment it is possible that two different instances will be returned for the same classloader environment. + * </p> * - * @throws LogConfigurationException if the implementation class is not - * available or cannot be instantiated. + * @return a {@code LogFactory}. + * @throws LogConfigurationException if the implementation class is not available or cannot be instantiated. */ public static LogFactory getFactory() throws LogConfigurationException { // Identify the class loader we will be using @@ -645,26 +632,23 @@ public abstract class LogFactory { } /** - * Convenience method to return a named logger, without the application - * having to care about factories. + * 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 - * @throws LogConfigurationException if a suitable {@code Log} - * instance cannot be returned + * @return a named logger. + * @throws LogConfigurationException if a suitable {@code Log} instance cannot be returned */ public static Log getLog(final Class clazz) throws LogConfigurationException { return getFactory().getInstance(clazz); } /** - * Convenience method to return a named logger, without the application - * having to care about factories. + * Convenience method to return a named logger, without the application having to care about factories. * - * @param name Logical name of the {@code Log} instance to be - * returned (the meaning of this name is only known to the underlying - * logging implementation that is being wrapped) - * @throws LogConfigurationException if a suitable {@code Log} - * instance cannot be returned + * @param name Logical name of the {@code Log} instance to be returned (the meaning of this name is only known to the underlying logging implementation that + * is being wrapped) + * @return a named logger. + * @throws LogConfigurationException if a suitable {@code Log} instance cannot be returned */ public static Log getLog(final String name) throws LogConfigurationException { return getFactory().getInstance(name); @@ -741,6 +725,7 @@ public abstract class LogFactory { * all code is written to call this method rather than Class.getClassLoader, * so that we could put AccessController stuff in this method without any * disruption later if we need to. + * </p> * <p> * Even when using an AccessController, however, this method can still * throw SecurityException. Commons-logging basically relies on the @@ -750,11 +735,16 @@ public abstract class LogFactory { * from starting up. Maybe it would be good to detect this situation and * just disable all commons-logging? Not high priority though - as stated * above, security policies that prevent classloader access aren't common. + * </p> * <p> * Note that returning an object fetched via an AccessController would * technically be a security flaw anyway; untrusted code that has access * to a trusted JCL library could use it to fetch the classloader for * a class even when forbidden to do so directly. + * </p> + * + * @param clazz Class. + * @return a ClassLoader. * * @since 1.1 */ @@ -905,47 +895,35 @@ public abstract class LogFactory { } /** - * Return a new instance of the specified {@code LogFactory} - * implementation class, loaded by the specified class loader. - * If that fails, try the class loader used to load this - * (abstract) LogFactory. - * <h2>ClassLoader conflicts</h2> + * Return a new instance of the specified {@code LogFactory} implementation class, loaded by the specified class loader. If that fails, try the class loader + * used to load this (abstract) LogFactory. + * <h4>ClassLoader conflicts</h4> * <p> - * Note that there can be problems if the specified ClassLoader is not the - * same as the classloader that loaded this class, ie when loading a - * concrete LogFactory subclass via a context classloader. + * Note that there can be problems if the specified ClassLoader is not the same as the classloader that loaded this class, ie when loading a concrete + * LogFactory subclass via a context classloader. + * </p> * <p> - * The problem is the same one that can occur when loading a concrete Log - * subclass via a context classloader. + * The problem is the same one that can occur when loading a concrete Log subclass via a context classloader. + * </p> * <p> - * The problem occurs when code running in the context classloader calls - * class X which was loaded via a parent classloader, and class X then calls - * LogFactory.getFactory (either directly or via LogFactory.getLog). Because - * class X was loaded via the parent, it binds to LogFactory loaded via - * the parent. When the code in this method finds some LogFactoryYYYY - * class in the child (context) classloader, and there also happens to be a - * LogFactory class defined in the child classloader, then LogFactoryYYYY - * will be bound to LogFactory@childloader. It cannot be cast to - * LogFactory@parentloader, ie this method cannot return the object as - * the desired type. Note that it doesn't matter if the LogFactory class - * in the child classloader is identical to the LogFactory class in the - * parent classloader, they are not compatible. + * The problem occurs when code running in the context classloader calls class X which was loaded via a parent classloader, and class X then calls + * LogFactory.getFactory (either directly or via LogFactory.getLog). Because class X was loaded via the parent, it binds to LogFactory loaded via the + * parent. When the code in this method finds some LogFactoryYYYY class in the child (context) classloader, and there also happens to be a LogFactory class + * defined in the child classloader, then LogFactoryYYYY will be bound to LogFactory@childloader. It cannot be cast to LogFactory@parentloader, ie this + * method cannot return the object as the desired type. Note that it doesn't matter if the LogFactory class in the child classloader is identical to the + * LogFactory class in the parent classloader, they are not compatible. + * </p> * <p> - * The solution taken here is to simply print out an error message when - * this occurs then throw an exception. The deployer of the application - * must ensure they remove all occurrences of the LogFactory class from - * the child classloader in order to resolve the issue. Note that they - * do not have to move the custom LogFactory subclass; that is ok as - * long as the only LogFactory class it can find to bind to is in the - * parent classloader. + * The solution taken here is to simply print out an error message when this occurs then throw an exception. The deployer of the application must ensure + * they remove all occurrences of the LogFactory class from the child classloader in order to resolve the issue. Note that they do not have to move the + * custom LogFactory subclass; that is ok as long as the only LogFactory class it can find to bind to is in the parent classloader. + * </p> * - * @param factoryClass Fully qualified name of the {@code LogFactory} - * implementation class - * @param classLoader ClassLoader from which to load this class - * @param contextClassLoader is the context that this new factory will - * manage logging for. - * @throws LogConfigurationException if a suitable instance - * cannot be created + * @param factoryClass Fully qualified name of the {@code LogFactory} implementation class + * @param classLoader ClassLoader from which to load this class + * @param contextClassLoader is the context that this new factory will manage logging for. + * @return a new instance of the specified {@code LogFactory}. + * @throws LogConfigurationException if a suitable instance cannot be created * @since 1.1 */ protected static LogFactory newFactory(final String factoryClass, @@ -991,6 +969,11 @@ public abstract class LogFactory { * directly via CustomFactoryImpl.getFactory or similar would ever call * this. Anyway, it's here just in case, though the "managed class loader" * value output to the diagnostics will not report the correct value. + * </p> + * + * @param factoryClass factory class. + * @param classLoader class loader. + * @return a LogFactory. */ protected static LogFactory newFactory(final String factoryClass, final ClassLoader classLoader) { @@ -1000,11 +983,9 @@ public abstract class LogFactory { /** * Implements the operations described in the javadoc for newFactory. * - * @param factoryClass - * @param classLoader used to load the specified factory class. This is - * expected to be either the TCCL or the classloader which loaded this - * class. Note that the classloader which loaded this class might be - * "null" (ie the bootloader) for embedded systems. + * @param factoryClass Factory class. + * @param classLoader used to load the specified factory class. This is expected to be either the TCCL or the classloader which loaded this class. Note + * that the classloader which loaded this class might be "null" (ie the bootloader) for embedded systems. * @return either a LogFactory object or a LogConfigurationException object. * @since 1.1 */ diff --git a/src/main/java/org/apache/commons/logging/LogSource.java b/src/main/java/org/apache/commons/logging/LogSource.java index f545be2..5517bdb 100644 --- a/src/main/java/org/apache/commons/logging/LogSource.java +++ b/src/main/java/org/apache/commons/logging/LogSource.java @@ -55,6 +55,9 @@ public class LogSource { // ------------------------------------------------------- Class Attributes + /** + * Logs. + */ static protected Hashtable logs = new Hashtable(); /** Is log4j available (in the current classpath) */ @@ -138,15 +141,21 @@ public class 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). + * 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). + * + * @param className class name. + * @throws LinkageError if there is missing dependency. + * @throws NoSuchMethodException if a matching method is not found. + * @throws SecurityException If a security manager, <i>s</i>, is present and the caller's class loader is not the same as or an ancestor of the class + * loader for the current class and invocation of {@link SecurityManager#checkPackageAccess s.checkPackageAccess()} denies + * access to the package of this class. + * @throws ClassNotFoundException if the class cannot be located */ - static public void setLogImplementation(final String classname) + static public void setLogImplementation(final String className) throws LinkageError, NoSuchMethodException, SecurityException, ClassNotFoundException { try { - final Class logclass = Class.forName(classname); + final Class logclass = Class.forName(className); final Class[] argtypes = new Class[1]; argtypes[0] = "".getClass(); logImplctor = logclass.getConstructor(argtypes); @@ -156,9 +165,16 @@ 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). + * + * @param logclass class. + * @throws LinkageError if there is missing dependency. + * @throws ExceptionInInitializerError unexpected exception has occurred in a static initializer. + * @throws NoSuchMethodException if a matching method is not found. + * @throws SecurityException If a security manager, <i>s</i>, is present and the caller's class loader is not the same as or an ancestor of the + * class loader for the current class and invocation of {@link SecurityManager#checkPackageAccess + * s.checkPackageAccess()} denies access to the package of this class. */ static public void setLogImplementation(final Class logclass) throws LinkageError, ExceptionInInitializerError, NoSuchMethodException, SecurityException { @@ -167,12 +183,22 @@ public class LogSource { logImplctor = logclass.getConstructor(argtypes); } - /** Get a {@code Log} instance by class name. */ + /** + * Get a {@code Log} instance by class name. + * + * @param name Class name. + * @return a {@code Log} instance. + */ static public Log getInstance(final String name) { return (Log) logs.computeIfAbsent(name, k -> makeNewLogInstance(name)); } - /** Get a {@code Log} instance by class. */ + /** + * Get a {@code Log} instance by class. + * + * @param clazz a Class. + * @return a {@code Log} instance. + */ static public Log getInstance(final Class clazz) { return getInstance(clazz.getName()); } @@ -193,6 +219,7 @@ public class LogSource { * 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) + * @return a new instance. */ static public Log makeNewLogInstance(final String name) { Log log; @@ -211,6 +238,9 @@ public class LogSource { /** * Returns a {@link String} array containing the names of * all logs known to me. + * + * @return a {@link String} array containing the names of + * all logs known to me. */ static public String[] getLogNames() { return (String[]) logs.keySet().toArray(EMPTY_STRING_ARRAY); diff --git a/src/main/java/org/apache/commons/logging/impl/Jdk13LumberjackLogger.java b/src/main/java/org/apache/commons/logging/impl/Jdk13LumberjackLogger.java index a8da636..dd6a3d8 100644 --- a/src/main/java/org/apache/commons/logging/impl/Jdk13LumberjackLogger.java +++ b/src/main/java/org/apache/commons/logging/impl/Jdk13LumberjackLogger.java @@ -47,9 +47,19 @@ public class Jdk13LumberjackLogger implements Log, Serializable { * The underlying Logger implementation we are using. */ protected transient Logger logger; + + /** + * Name. + */ protected String name; + + /** Source class name. */ private String sourceClassName = "unknown"; + + /** Source method name. */ private String sourceMethodName = "unknown"; + + /** Class and method found flag. */ private boolean classAndMethodFound; /** @@ -194,6 +204,8 @@ public class Jdk13LumberjackLogger implements Log, Serializable { /** * Return the native Logger instance we are using. + * + * @return the native Logger instance we are using. */ public Logger getLogger() { if (logger == null) { diff --git a/src/main/java/org/apache/commons/logging/impl/Jdk14Logger.java b/src/main/java/org/apache/commons/logging/impl/Jdk14Logger.java index 034e4fb..58e5ce6 100644 --- a/src/main/java/org/apache/commons/logging/impl/Jdk14Logger.java +++ b/src/main/java/org/apache/commons/logging/impl/Jdk14Logger.java @@ -53,8 +53,6 @@ public class Jdk14Logger implements Log, Serializable { logger = getLogger(); } - // ----------------------------------------------------- Instance Variables - /** * The underlying Logger implementation we are using. */ @@ -65,9 +63,13 @@ public class Jdk14Logger implements Log, Serializable { */ protected String name; - // --------------------------------------------------------- Protected Methods - - protected void log( final Level level, final String msg, final Throwable ex ) { + /** + * Logs a message at the given level. + * @param level The level. + * @param msg The message. + * @param ex The exception. + */ + protected void log(final Level level, final String msg, final Throwable ex) { final Logger logger = getLogger(); if (logger.isLoggable(level)) { // Hack (?) to get the stack trace. @@ -77,20 +79,18 @@ public class Jdk14Logger implements Log, Serializable { final String cname = name; String method = "unknown"; // Caller will be the third element - if ( locations != null && locations.length > 2 ) { + if (locations != null && locations.length > 2) { final StackTraceElement caller = locations[2]; method = caller.getMethodName(); } - if ( ex == null ) { - logger.logp( level, cname, method, msg ); + if (ex == null) { + logger.logp(level, cname, method, msg); } else { - logger.logp( level, cname, method, msg, ex ); + logger.logp(level, cname, method, msg, ex); } } } - // --------------------------------------------------------- Public Methods - /** * Logs a message with {@code java.util.logging.Level.FINE}. * @@ -162,6 +162,8 @@ public class Jdk14Logger implements Log, Serializable { /** * Return the native Logger instance we are using. + * + * @return the native Logger instance we are using. */ public Logger getLogger() { if (logger == null) { diff --git a/src/main/java/org/apache/commons/logging/impl/Log4JLogger.java b/src/main/java/org/apache/commons/logging/impl/Log4JLogger.java index d069ff7..20b9446 100644 --- a/src/main/java/org/apache/commons/logging/impl/Log4JLogger.java +++ b/src/main/java/org/apache/commons/logging/impl/Log4JLogger.java @@ -90,14 +90,17 @@ public class Log4JLogger implements Log, Serializable { traceLevel = _traceLevel; } - // ------------------------------------------------------------ Constructor - + /** + * Constructs a new instance. + */ public Log4JLogger() { name = null; } /** * Base constructor. + * + * @param name name. */ public Log4JLogger(final String name) { this.name = name; @@ -106,6 +109,8 @@ public class Log4JLogger implements Log, Serializable { /** * For use with a log4j factory. + * + * @param logger Logger. */ public Log4JLogger(final Logger logger) { if (logger == null) { @@ -259,7 +264,9 @@ public class Log4JLogger implements Log, Serializable { } /** - * Return the native Logger instance we are using. + * Gets the native Logger instance we are using. + * + * @return the native Logger instance we are using. */ public Logger getLogger() { Logger result = logger; @@ -275,7 +282,7 @@ public class Log4JLogger implements Log, Serializable { } /** - * Check whether the Log4j Logger used is enabled for {@code DEBUG} priority. + * Tests whether the Log4j Logger used is enabled for {@code DEBUG} priority. */ @Override public boolean isDebugEnabled() { @@ -283,7 +290,7 @@ public class Log4JLogger implements Log, Serializable { } /** - * Check whether the Log4j Logger used is enabled for {@code ERROR} priority. + * Tests whether the Log4j Logger used is enabled for {@code ERROR} priority. */ @Override public boolean isErrorEnabled() { @@ -291,7 +298,7 @@ public class Log4JLogger implements Log, Serializable { } /** - * Check whether the Log4j Logger used is enabled for {@code FATAL} priority. + * Tests whether the Log4j Logger used is enabled for {@code FATAL} priority. */ @Override public boolean isFatalEnabled() { @@ -299,7 +306,7 @@ public class Log4JLogger implements Log, Serializable { } /** - * Check whether the Log4j Logger used is enabled for {@code INFO} priority. + * Tests whether the Log4j Logger used is enabled for {@code INFO} priority. */ @Override public boolean isInfoEnabled() { @@ -307,7 +314,7 @@ public class Log4JLogger implements Log, Serializable { } /** - * Check whether the Log4j Logger used is enabled for {@code TRACE} priority. + * Tests whether the Log4j Logger used is enabled for {@code TRACE} priority. * When using a log4j version that does not support the TRACE level, this call * will report whether {@code DEBUG} is enabled or not. */ @@ -317,7 +324,7 @@ public class Log4JLogger implements Log, Serializable { } /** - * Check whether the Log4j Logger used is enabled for {@code WARN} priority. + * Tests whether the Log4j Logger used is enabled for {@code WARN} priority. */ @Override public boolean isWarnEnabled() { diff --git a/src/main/java/org/apache/commons/logging/impl/LogFactoryImpl.java b/src/main/java/org/apache/commons/logging/impl/LogFactoryImpl.java index cec1e89..2a12bc8 100644 --- a/src/main/java/org/apache/commons/logging/impl/LogFactoryImpl.java +++ b/src/main/java/org/apache/commons/logging/impl/LogFactoryImpl.java @@ -78,7 +78,7 @@ public class LogFactoryImpl extends LogFactory { /** * An empty immutable {@code String} array. */ - private static final String[] EMPTY_STRING_ARRAY = new String[0]; + private static final String[] EMPTY_STRING_ARRAY = {}; // ----------------------------------------------------------- Constructors @@ -376,8 +376,10 @@ public class LogFactoryImpl extends LogFactory { // ------------------------------------------------------ /** - * Gets the context classloader. + * Gets the context ClassLoader. * This method is a workaround for a java 1.2 compiler bug. + * + * @return the context ClassLoader * @since 1.1 */ protected static ClassLoader getContextClassLoader() throws LogConfigurationException { @@ -386,15 +388,19 @@ public class LogFactoryImpl extends LogFactory { /** * Workaround for bug in Java1.2; in theory this method is not needed. - * See LogFactory.isDiagnosticsEnabled. + * + * @return Same as {@link LogFactory#isDiagnosticsEnabled()}. + * @see LogFactory#isDiagnosticsEnabled() */ protected static boolean isDiagnosticsEnabled() { return LogFactory.isDiagnosticsEnabled(); } /** - * Workaround for bug in Java1.2; in theory this method is not needed. - * See LogFactory.getClassLoader. + * Workaround for bug in Java1.2; in theory this method is not needed. {@link LogFactory#getClassLoader(Class)}. + * + * @param clazz See {@link LogFactory#getClassLoader(Class)}. + * @return See {@link LogFactory#getClassLoader(Class)}. * @since 1.1 */ protected static ClassLoader getClassLoader(final Class clazz) { @@ -454,11 +460,10 @@ public class LogFactoryImpl extends LogFactory { } /** - * Return the fully qualified Java classname of the {@link Log} - * implementation we will be using. + * Return the fully qualified Java classname of the {@link Log} implementation we will be using. * - * @deprecated Never invoked by this class; subclasses should not assume - * it will be. + * @return the fully qualified Java classname of the {@link Log} implementation we will be using. + * @deprecated Never invoked by this class; subclasses should not assume it will be. */ @Deprecated protected String getLogClassName() { @@ -471,19 +476,20 @@ public class LogFactoryImpl extends LogFactory { /** - * <p>Return the {@code Constructor} that can be called to instantiate - * new {@link org.apache.commons.logging.Log} instances.</p> + * <p> + * Return the {@code Constructor} that can be called to instantiate new {@link org.apache.commons.logging.Log} instances. + * </p> + * + * <p> + * <strong>IMPLEMENTATION NOTE</strong> - Race conditions caused by calling this method from more than one thread are ignored, because the same + * {@code Constructor} instance will ultimately be derived in all circumstances. + * </p> * - * <p><strong>IMPLEMENTATION NOTE</strong> - Race conditions caused by - * calling this method from more than one thread are ignored, because - * the same {@code Constructor} instance will ultimately be derived - * in all circumstances.</p> + * @return the {@code Constructor} that can be called to instantiate new {@link org.apache.commons.logging.Log} instances. * - * @throws LogConfigurationException if a suitable constructor - * cannot be returned + * @throws LogConfigurationException if a suitable constructor cannot be returned * - * @deprecated Never invoked by this class; subclasses should not assume - * it will be. + * @deprecated Never invoked by this class; subclasses should not assume it will be. */ @Deprecated protected Constructor getLogConstructor() @@ -498,10 +504,10 @@ public class LogFactoryImpl extends LogFactory { } /** - * Is <em>JDK 1.3 with Lumberjack</em> logging available? + * Tests whether <em>JDK 1.3 with Lumberjack</em> logging available. * - * @deprecated Never invoked by this class; subclasses should not assume - * it will be. + * @return whether <em>JDK 1.3 with Lumberjack</em> logging available. + * @deprecated Never invoked by this class; subclasses should not assume it will be. */ @Deprecated protected boolean isJdk13LumberjackAvailable() { @@ -511,42 +517,37 @@ public class LogFactoryImpl extends LogFactory { } /** - * Return {@code true} if <em>JDK 1.4 or later</em> logging - * is available. Also checks that the {@code Throwable} class - * supports {@code getStackTrace()}, which is required by - * Jdk14Logger. + * Tests {@code true} whether <em>JDK 1.4 or later</em> logging is available. Also checks that the {@code Throwable} class supports {@code getStackTrace()}, + * which is required by Jdk14Logger. * - * @deprecated Never invoked by this class; subclasses should not assume - * it will be. + * @return Whether <em>JDK 1.4 or later</em> logging is available. + * + * @deprecated Never invoked by this class; subclasses should not assume it will be. */ @Deprecated protected boolean isJdk14Available() { - return isLogLibraryAvailable( - "Jdk14", - "org.apache.commons.logging.impl.Jdk14Logger"); + return isLogLibraryAvailable("Jdk14", "org.apache.commons.logging.impl.Jdk14Logger"); } /** - * Is a <em>Log4J</em> implementation available? + * Tests whether a <em>Log4J</em> implementation available. * - * @deprecated Never invoked by this class; subclasses should not assume - * it will be. + * @return whether a <em>Log4J</em> implementation available. + * + * @deprecated Never invoked by this class; subclasses should not assume it will be. */ @Deprecated protected boolean isLog4JAvailable() { - return isLogLibraryAvailable( - "Log4J", - LOGGING_IMPL_LOG4J_LOGGER); + return isLogLibraryAvailable("Log4J", LOGGING_IMPL_LOG4J_LOGGER); } /** - * Create and return a new {@link org.apache.commons.logging.Log} - * instance for the specified name. + * Create and return a new {@link org.apache.commons.logging.Log} instance for the specified name. * * @param name Name of the new logger + * @return a new {@link org.apache.commons.logging.Log} * - * @throws LogConfigurationException if a new instance cannot - * be created + * @throws LogConfigurationException if a new instance cannot be created */ protected Log newInstance(final String name) throws LogConfigurationException { Log instance; @@ -609,12 +610,7 @@ public class LogFactoryImpl extends LogFactory { private static ClassLoader getContextClassLoaderInternal() throws LogConfigurationException { return (ClassLoader)AccessController.doPrivileged( - new PrivilegedAction() { - @Override - public Object run() { - return LogFactory.directGetContextClassLoader(); - } - }); + (PrivilegedAction) LogFactory::directGetContextClassLoader); } /** @@ -629,12 +625,7 @@ public class LogFactoryImpl extends LogFactory { private static String getSystemProperty(final String key, final String def) throws SecurityException { return (String) AccessController.doPrivileged( - new PrivilegedAction() { - @Override - public Object run() { - return System.getProperty(key, def); - } - }); + (PrivilegedAction) () -> System.getProperty(key, def)); } /** @@ -647,12 +638,7 @@ public class LogFactoryImpl extends LogFactory { private ClassLoader getParentClassLoader(final ClassLoader cl) { try { return (ClassLoader)AccessController.doPrivileged( - new PrivilegedAction() { - @Override - public Object run() { - return cl.getParent(); - } - }); + (PrivilegedAction) () -> cl.getParent()); } catch (final SecurityException ex) { logDiagnostic("[SECURITY] Unable to obtain parent classloader"); return null; diff --git a/src/main/java/org/apache/commons/logging/impl/LogKitLogger.java b/src/main/java/org/apache/commons/logging/impl/LogKitLogger.java index 05bf08f..11add6a 100644 --- a/src/main/java/org/apache/commons/logging/impl/LogKitLogger.java +++ b/src/main/java/org/apache/commons/logging/impl/LogKitLogger.java @@ -63,7 +63,9 @@ public class LogKitLogger implements Log, Serializable { // --------------------------------------------------------- Public Methods /** - * Return the underlying Logger we are using. + * Gets the underlying Logger we are using. + * + * @return the underlying Logger we are using. */ public Logger getLogger() { Logger result = logger; diff --git a/src/main/java/org/apache/commons/logging/impl/NoOpLog.java b/src/main/java/org/apache/commons/logging/impl/NoOpLog.java index c8eaabe..cf6b190 100644 --- a/src/main/java/org/apache/commons/logging/impl/NoOpLog.java +++ b/src/main/java/org/apache/commons/logging/impl/NoOpLog.java @@ -21,8 +21,7 @@ import java.io.Serializable; import org.apache.commons.logging.Log; /** - * Trivial implementation of Log that throws away all messages. No - * configurable system properties are supported. + * Trivial implementation of Log that throws away all messages. No configurable system properties are supported. */ public class NoOpLog implements Log, Serializable { @@ -30,45 +29,76 @@ public class NoOpLog implements Log, Serializable { private static final long serialVersionUID = 561423906191706148L; /** Convenience constructor */ - public NoOpLog() { } - /** Base constructor */ - public NoOpLog(final String name) { } + public NoOpLog() { + } + + /** + * Base constructor + * + * @param name unused. + */ + public NoOpLog(final String name) { + } + /** Do nothing */ @Override - public void trace(final Object message) { } + public void trace(final Object message) { + } + /** Do nothing */ @Override - public void trace(final Object message, final Throwable t) { } + public void trace(final Object message, final Throwable t) { + } + /** Do nothing */ @Override - public void debug(final Object message) { } + public void debug(final Object message) { + } + /** Do nothing */ @Override - public void debug(final Object message, final Throwable t) { } + public void debug(final Object message, final Throwable t) { + } + /** Do nothing */ @Override - public void info(final Object message) { } + public void info(final Object message) { + } + /** Do nothing */ @Override - public void info(final Object message, final Throwable t) { } + public void info(final Object message, final Throwable t) { + } + /** Do nothing */ @Override - public void warn(final Object message) { } + public void warn(final Object message) { + } + /** Do nothing */ @Override - public void warn(final Object message, final Throwable t) { } + public void warn(final Object message, final Throwable t) { + } + /** Do nothing */ @Override - public void error(final Object message) { } + public void error(final Object message) { + } + /** Do nothing */ @Override - public void error(final Object message, final Throwable t) { } + public void error(final Object message, final Throwable t) { + } + /** Do nothing */ @Override - public void fatal(final Object message) { } + public void fatal(final Object message) { + } + /** Do nothing */ @Override - public void fatal(final Object message, final Throwable t) { } + public void fatal(final Object message, final Throwable t) { + } /** * Debug is never enabled. @@ -76,7 +106,9 @@ public class NoOpLog implements Log, Serializable { * @return false */ @Override - public final boolean isDebugEnabled() { return false; } + public final boolean isDebugEnabled() { + return false; + } /** * Error is never enabled. @@ -84,7 +116,9 @@ public class NoOpLog implements Log, Serializable { * @return false */ @Override - public final boolean isErrorEnabled() { return false; } + public final boolean isErrorEnabled() { + return false; + } /** * Fatal is never enabled. @@ -92,7 +126,9 @@ public class NoOpLog implements Log, Serializable { * @return false */ @Override - public final boolean isFatalEnabled() { return false; } + public final boolean isFatalEnabled() { + return false; + } /** * Info is never enabled. @@ -100,7 +136,9 @@ public class NoOpLog implements Log, Serializable { * @return false */ @Override - public final boolean isInfoEnabled() { return false; } + public final boolean isInfoEnabled() { + return false; + } /** * Trace is never enabled. @@ -108,7 +146,9 @@ public class NoOpLog implements Log, Serializable { * @return false */ @Override - public final boolean isTraceEnabled() { return false; } + public final boolean isTraceEnabled() { + return false; + } /** * Warn is never enabled. @@ -116,5 +156,7 @@ public class NoOpLog implements Log, Serializable { * @return false */ @Override - public final boolean isWarnEnabled() { return false; } + public final boolean isWarnEnabled() { + return false; + } } diff --git a/src/main/java/org/apache/commons/logging/impl/SimpleLog.java b/src/main/java/org/apache/commons/logging/impl/SimpleLog.java index da9dd28..c78dd81 100644 --- a/src/main/java/org/apache/commons/logging/impl/SimpleLog.java +++ b/src/main/java/org/apache/commons/logging/impl/SimpleLog.java @@ -259,6 +259,8 @@ public class SimpleLog implements Log, Serializable { /** * Get logging level. + * + * @return logging level. */ public int getLevel() { return currentLogLevel; @@ -358,9 +360,10 @@ public class SimpleLog implements Log, Serializable { } /** - * Is the given log level currently enabled? + * Tests whether the given log level currently enabled. * * @param logLevel is this level enabled? + * @return whether the given log level currently enabled. */ protected boolean isLevelEnabled(final int logLevel) { // log level are numerically ordered so can use simple numeric diff --git a/src/main/java/org/apache/commons/logging/impl/WeakHashtable.java b/src/main/java/org/apache/commons/logging/impl/WeakHashtable.java index cf66955..751b8f5 100644 --- a/src/main/java/org/apache/commons/logging/impl/WeakHashtable.java +++ b/src/main/java/org/apache/commons/logging/impl/WeakHashtable.java @@ -124,9 +124,10 @@ public final class WeakHashtable extends Hashtable { */ private static final int PARTIAL_PURGE_COUNT = 10; - /* ReferenceQueue we check for gc'd keys */ + /** ReferenceQueue we check for GC'd keys. */ private final ReferenceQueue queue = new ReferenceQueue(); - /* Counter used to control how often we purge gc'd entries */ + + /** Counter used to control how often we purge gc'd entries. */ private int changeCount; /**
