From 1529c02432fdc9c3a8b54bd12932caf9a40ec8a0 Mon Sep 17 00:00:00 2001 From: Gary Gregory Date: Tue, 30 Jul 2024 08:24:43 -0400 Subject: [PATCH] Use Javadoc @code - Javadoc and comments: Distinguish 'hash table' the concept versus 'Hashtable' the class - Use generics in test - Close HTML tags --- .../apache/commons/logging/LogFactory.java | 10 +-- .../commons/logging/impl/AvalonLogger.java | 2 +- .../commons/logging/impl/LogFactoryImpl.java | 2 +- .../commons/logging/impl/WeakHashtable.java | 2 +- .../apache/commons/logging/package-info.java | 74 +++++++++---------- .../logging/impl/WeakHashtableTestCase.java | 2 +- .../security/SecurityAllowedTestCase.java | 2 +- .../security/SecurityForbiddenTestCase.java | 16 ++-- 8 files changed, 57 insertions(+), 53 deletions(-) diff --git a/src/main/java/org/apache/commons/logging/LogFactory.java b/src/main/java/org/apache/commons/logging/LogFactory.java index d908857..bcf0983 100644 --- a/src/main/java/org/apache/commons/logging/LogFactory.java +++ b/src/main/java/org/apache/commons/logging/LogFactory.java @@ -159,7 +159,7 @@ public abstract class LogFactory { * Note: {@code LogFactory} will print: *

* 
-     * [ERROR] LogFactory: Load of custom hashtable failed
+     * [ERROR] LogFactory: Load of custom hash table failed
      *
*

* to system error and then continue using a standard Hashtable. @@ -192,7 +192,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. */ + /** Name used to load the weak hash table implementation by names. */ private static final String WEAK_HASHTABLE_CLASSNAME = "org.apache.commons.logging.impl.WeakHashtable"; @@ -229,7 +229,7 @@ public abstract class LogFactory { * class loader (only likely for embedded systems work). * * Note that {@code factories} is a Hashtable (not a HashMap), - * and hashtables don't allow null as a key. + * and hash tables don't allow null as a key. * @deprecated since 1.1.2 */ @Deprecated @@ -440,7 +440,7 @@ public abstract class LogFactory { } /** - * Create the hashtable which will be used to store a map of + * Create the hash table which will be used to store a map of * (context class loader -> logfactory-object). Version 1.2+ of Java * supports "weak references", allowing a custom Hashtable class * to be used which uses only weak references to its keys. Using weak @@ -462,7 +462,7 @@ public abstract class LogFactory { storeImplementationClass = getSystemProperty(HASHTABLE_IMPLEMENTATION_PROPERTY, null); } catch (final SecurityException ex) { // Permissions don't allow this to be accessed. Default to the "modern" - // weak hashtable implementation if it is available. + // weak hash table implementation if it is available. storeImplementationClass = null; } diff --git a/src/main/java/org/apache/commons/logging/impl/AvalonLogger.java b/src/main/java/org/apache/commons/logging/impl/AvalonLogger.java index b180261..ae711a5 100644 --- a/src/main/java/org/apache/commons/logging/impl/AvalonLogger.java +++ b/src/main/java/org/apache/commons/logging/impl/AvalonLogger.java @@ -82,7 +82,7 @@ public class AvalonLogger implements Log { /** * Constructs an {@code AvalonLogger} that will log to a child - * of the Logger set by calling {@link #setDefaultLogger}. + * of the {@code Logger} set by calling {@link #setDefaultLogger}. * * @param name the name of the avalon logger implementation to delegate to */ 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 ed1ea27..e52d465 100644 --- a/src/main/java/org/apache/commons/logging/impl/LogFactoryImpl.java +++ b/src/main/java/org/apache/commons/logging/impl/LogFactoryImpl.java @@ -50,7 +50,7 @@ import org.apache.commons.logging.LogFactory; * *

* If the selected {@link Log} implementation class has a - * setLogFactory() method that accepts a {@link LogFactory} + * {@code setLogFactory()} method that accepts a {@link LogFactory} * parameter, this method will be called on each newly created instance * to identify the associated factory. This makes factory configuration * attributes available to the Log instance, if it so desires. 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 8157f88..6df1ff5 100644 --- a/src/main/java/org/apache/commons/logging/impl/WeakHashtable.java +++ b/src/main/java/org/apache/commons/logging/impl/WeakHashtable.java @@ -216,7 +216,7 @@ public final class WeakHashtable extends Hashtable { result = result && hashCode() == otherKey.hashCode(); // In any case, as our c'tor does not allow null referants // and Hashtable does not do equality checks between - // existing keys, normal hashtable operations should never + // existing keys, normal hash table operations should never // result in an equals comparison between null referants } else diff --git a/src/main/java/org/apache/commons/logging/package-info.java b/src/main/java/org/apache/commons/logging/package-info.java index db99125..f2d078a 100644 --- a/src/main/java/org/apache/commons/logging/package-info.java +++ b/src/main/java/org/apache/commons/logging/package-info.java @@ -29,10 +29,10 @@ *

  • * JDK Logging API, included in JDK 1.4 or later systems. Each named * Log instance is connected to a corresponding - * java.util.logging.Logger instance.
    • + * {@code java.util.logging.Logger} instance. *
  • LogKit from Apache's * Avalon project. Each named Log instance is - * connected to a corresponding LogKit Logger.
    • + * connected to a corresponding LogKit {@code Logger}. *
  • NoOpLog implementation that simply swallows * all log output, for all named Log instances.
    • *
  • SimpleLog implementation that writes all @@ -66,66 +66,66 @@ * this page in order to understand how to configure logging for your * application.

    *

    Configuring the Commons Logging Package

    - *

    Choosing a LogFactory Implementation

    + *

    Choosing a {@code LogFactory} Implementation

    *

    From an application perspective, the first requirement is to retrieve an - * object reference to the LogFactory instance that will be used - * to create Log instances for this + * object reference to the {@code LogFactory} instance that will be used + * to create {@code Log} instances for this * application. This is normally accomplished by calling the static - * getFactory() method. This method implements the following - * discovery algorithm to select the name of the LogFactory + * {@code getFactory()} method. This method implements the following + * discovery algorithm to select the name of the {@code LogFactory} * implementation class this application wants to use:

    * - *

    If a commons-logging.properties file is found, all of the + *

    If a {@code commons-logging.properties} file is found, all of the * properties defined there are also used to set configuration attributes on - * the instantiated LogFactory instance.

    + * the instantiated {@code LogFactory} instance.

    *

    Once an implementation class name is selected, the corresponding class is * loaded from the current Thread context class loader (if there is one), or - * from the class loader that loaded the LogFactory class itself - * otherwise. This allows a copy of commons-logging.jar to be + * from the class loader that loaded the {@code LogFactory} class itself + * otherwise. This allows a copy of {@code commons-logging.jar} to be * shared in a multiple class loader environment (such as a servlet container), - * but still allow each web application to provide its own LogFactory + * but still allow each web application to provide its own {@code LogFactory} * implementation, if it so desires. An instance of this class will then be * created, and cached per class loader. - *

    The Default LogFactory Implementation

    - *

    The Logging Package APIs include a default LogFactory + *

    The Default {@code LogFactory} Implementation

    + *

    The Logging Package APIs include a default {@code LogFactory} * implementation class ( * org.apache.commons.logging.impl.LogFactoryImpl) that is selected if no * other implementation class name can be discovered. Its primary purpose is * to create (as necessary) and return Log instances - * in response to calls to the getInstance() method. The default + * in response to calls to the {@code getInstance()} method. The default * implementation uses the following rules:

    * @@ -151,7 +151,7 @@ *

    Each individual Log implementation may * support its own configuration properties. These will be documented in the * class descriptions for the corresponding implementation class.

    - *

    Finally, some Log implementations (such as the one for Log4J) + *

    Finally, some {@code Log} implementations (such as the one for Log4J) * require an external configuration file for the entire logging environment. * This file should be prepared in a manner that is specific to the actual logging * technology being used.

    @@ -168,12 +168,12 @@ * purposes. A typical scenario for a server application is to have each * major component of the server use its own Log instance.
    • *
  • Cause messages to be logged (if the corresponding detail level is enabled) - * by calling appropriate methods (trace(), debug(), - * info(), warn(), error, and - * fatal()).
    • + * by calling appropriate methods ({@code trace()}, {@code debug()}, + * {@code info()}, {@code warn()}, {@code error}, and + * {@code fatal()}). * - *

    For convenience, LogFactory also offers a static method - * getLog() that combines the typical two-step pattern:

    + *

    For convenience, {@code LogFactory} also offers a static method + * {@code getLog()} that combines the typical two-step pattern:

    * 
      * Log log = LogFactory.getFactory().getInstance(Foo.class);
  *
    diff --git a/src/test/java/org/apache/commons/logging/impl/WeakHashtableTestCase.java b/src/test/java/org/apache/commons/logging/impl/WeakHashtableTestCase.java index 6e082d0..ea6ad98 100644 --- a/src/test/java/org/apache/commons/logging/impl/WeakHashtableTestCase.java +++ b/src/test/java/org/apache/commons/logging/impl/WeakHashtableTestCase.java @@ -212,7 +212,7 @@ public class WeakHashtableTestCase extends TestCase { assertEquals(Long.valueOf(1066), weakHashtable.get(anotherKey)); - // Test compliance with the hashtable API re nulls + // Test compliance with the Hashtable API re nulls Exception caught = null; try { weakHashtable.put(null, new Object()); diff --git a/src/test/java/org/apache/commons/logging/security/SecurityAllowedTestCase.java b/src/test/java/org/apache/commons/logging/security/SecurityAllowedTestCase.java index fe4e5ff..28c0ba4 100644 --- a/src/test/java/org/apache/commons/logging/security/SecurityAllowedTestCase.java +++ b/src/test/java/org/apache/commons/logging/security/SecurityAllowedTestCase.java @@ -43,7 +43,7 @@ import org.apache.commons.logging.PathableTestSuite; */ public class SecurityAllowedTestCase extends TestCase { - // Dummy special hashtable, so we can tell JCL to use this instead of + // Dummy special Hashtable, so we can tell JCL to use this instead of // the standard one. public static class CustomHashtable extends Hashtable { diff --git a/src/test/java/org/apache/commons/logging/security/SecurityForbiddenTestCase.java b/src/test/java/org/apache/commons/logging/security/SecurityForbiddenTestCase.java index ee1afb8..a940ec0 100644 --- a/src/test/java/org/apache/commons/logging/security/SecurityForbiddenTestCase.java +++ b/src/test/java/org/apache/commons/logging/security/SecurityForbiddenTestCase.java @@ -39,24 +39,28 @@ import org.apache.commons.logging.PathableTestSuite; * Performing tests with security permissions disabled is tricky, as building error * messages on failure requires certain security permissions. If the security manager * blocks these, then the test can fail without the error messages being output. + *

    *

    * This class has only one unit test, as we are (in part) checking behavior in * the static block of the LogFactory class. As that class cannot be unloaded after * being loaded into a class loader, the only workaround is to use the * PathableClassLoader approach to ensure each test is run in its own * class loader, and use a separate test class for each test. + *

    */ public class SecurityForbiddenTestCase extends TestCase { - // Dummy special hashtable, so we can tell JCL to use this instead of - // the standard one. - public static class CustomHashtable extends Hashtable { + /** + * Dummy special Hashtable, so we can tell JCL to use this instead of the standard one. + */ + public static class CustomHashtable extends Hashtable { /** * Generated serial version ID. */ private static final long serialVersionUID = 7224652794746236024L; } + /** * Return the tests included in this test suite. */ @@ -112,7 +116,7 @@ public class SecurityForbiddenTestCase extends TestCase { } /** - * Test what happens when JCL is run with absolutely no security + * Tests what happens when JCL is run with absolutely no security * privileges at all, including reading system properties. Everything * should fall back to the built-in defaults. */ @@ -148,7 +152,7 @@ public class SecurityForbiddenTestCase extends TestCase { final Object factoryTable = factoryField.get(null); assertNotNull(factoryTable); final String ftClassName = factoryTable.getClass().getName(); - assertNotEquals("Custom hashtable unexpectedly used", + assertNotEquals("Custom Hashtable unexpectedly used", CustomHashtable.class.getName(), ftClassName); assertEquals(0, mySecurityManager.getUntrustedCodeCount()); @@ -165,7 +169,7 @@ public class SecurityForbiddenTestCase extends TestCase { } /** - * Test what happens when JCL is run with absolutely no security + * Tests what happens when JCL is run with absolutely no security * privileges at all and a class loaded with a different class loader * than the context class loader of the current thread tries to log something. */