LogFactory (Apache Tomcat 7.0.104 API Documentation)

org.apache.juli.logging

## Class LogFactory

- java.lang.Object
- - org.apache.juli.logging.LogFactory

-     public class LogFactory
      extends Object

  Modified LogFactory: removed all discovery, hardcode a specific implementation If you like a different logging implementation - use either the discovery-based commons-logging, or better - another implementation hardcoded to your favourite logging impl. Why ? Each application and deployment can choose a logging implementation - that involves configuration, installing the logger jar and optional plugins, etc. As part of this process - they can as well install the commons-logging implementation that corresponds to their logger of choice. This completely avoids any discovery problem, while still allowing the user to switch. Note that this implementation is not just a wrapper around JDK logging (like the original commons-logging impl). It adds 2 features - a simpler configuration (which is in fact a subset of log4j.properties) and a formatter that is less ugly. The removal of 'abstract' preserves binary backward compatibility. It is possible to preserve the abstract - and introduce another (hardcoded) factory - but I see no benefit. Since this class is not intended to be extended - all protected methods are removed. This can be changed - but again, there is little value in keeping dead code. Just take a quick look at the removed code ( and it's complexity). -------------- Original comment:

  Factory for creating `Log` instances, with discovery and configuration features similar to that employed by standard Java APIs 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.

  Author:
    Craig R. McClanahan, Costin Manolache, Richard A. Sitze

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `FACTORY_DEFAULT` The fully qualified class name of the fallback `LogFactory` implementation class to use, if no other can be found.
    `static String` | `FACTORY_PROPERTIES` The name of the properties file to search for.
    `static String` | `FACTORY_PROPERTY` The name of the property used to identify the LogFactory implementation class name.
    `static String` | `HASHTABLE_IMPLEMENTATION_PROPERTY` Setting this system property value allows the `Hashtable` used to store classloaders to be substituted by an alternative implementation.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `getAttribute(String name)` Return the configuration attribute with the specified name (if any), or `null` if there is no such attribute.
    `String[]` | `getAttributeNames()` Return an array containing the names of all currently defined configuration attributes.
    `static LogFactory` | `getFactory()` 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.
    `Log` | `getInstance(Class<?> clazz)` Convenience method to derive a name from the specified class and call `getInstance(String)` with it.
    `Log` | `getInstance(String name)` Construct (if necessary) and return a `Log` instance, using the factory's current set of configuration attributes.
    `static Log` | `getLog(Class<?> clazz)` Convenience method to return a named logger, without the application having to care about factories.
    `static Log` | `getLog(String name)` Convenience method to return a named logger, without the application having to care about factories.
    `static String` | `objectId(Object o)` Returns a string that uniquely identifies the specified object, including its class.
    `void` | `release()` Release any internal references to previously created `Log` instances returned by this factory.
    `static void` | `release(ClassLoader classLoader)` Release any internal references to previously created `LogFactory` instances that have been associated with the specified class loader (if any), after calling the instance method `release()` on each of them.
    `static void` | `releaseAll()` Release any internal references to previously created `LogFactory` instances, after calling the instance method `release()` on each of them.
    `void` | `removeAttribute(String name)` Remove any configuration attribute associated with the specified name.
    `void` | `setAttribute(String name, Object value)` Set the configuration attribute with the specified name.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### FACTORY_PROPERTY

          public static final String FACTORY_PROPERTY

      The name of the property used to identify the LogFactory implementation class name.
      See Also:
        Constant Field Values

    - #### FACTORY_DEFAULT

          public static final String FACTORY_DEFAULT

      The fully qualified class name of the fallback `LogFactory` implementation class to use, if no other can be found.
      See Also:
        Constant Field Values

    - #### FACTORY_PROPERTIES

          public static final String FACTORY_PROPERTIES

      The name of the properties file to search for.
      See Also:
        Constant Field Values

    - #### HASHTABLE_IMPLEMENTATION_PROPERTY

          public static final String HASHTABLE_IMPLEMENTATION_PROPERTY

      Setting this system property value allows the `Hashtable` used to store classloaders to be substituted by an alternative implementation.

      Note: `LogFactory` will print:

           [ERROR] LogFactory: Load of custom hashtable failed

      to system error and then continue using a standard Hashtable.

      Usage: Set this property when Java is invoked and `LogFactory` will attempt to load a new instance of the given implementation class. For example, running the following ant scriptlet:

            <java classname="${test.runner}" fork="yes" failonerror="${test.failonerror}">
               ...
               <sysproperty
                  key="org.apache.commons.logging.LogFactory.HashtableImpl"
                  value="org.apache.commons.logging.AltHashtable"/>
            </java>

      will mean that `LogFactory` will load an instance of `org.apache.commons.logging.AltHashtable`.

      A typical use case is to allow a custom Hashtable implementation using weak references to be substituted. This will allow classloaders to be garbage collected without the need to release them (on 1.3+ JVMs only, of course ;)

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getInstance

          public Log getInstance(String name)
                          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 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.

      Parameters:
        `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)
      Returns:
        A log instance with the requested name
      Throws:
        `LogConfigurationException` - if a suitable `Log` instance cannot be returned

    - #### release

          public void release()

      Release any internal references to previously created `Log` instances returned by this factory. This is useful in environments like servlet containers, which implement application reloading by throwing away a ClassLoader. Dangling references to objects in that class loader would prevent garbage collection.

    - #### getAttribute

          public Object getAttribute(String name)

      Return the configuration attribute with the specified name (if any), or `null` if there is no such attribute.
      Parameters:
        `name` - Name of the attribute to return

    - #### getAttributeNames

          public String[] getAttributeNames()

      Return an array containing the names of all currently defined configuration attributes. If there are no such attributes, a zero length array is returned.

    - #### removeAttribute

          public void removeAttribute(String name)

      Remove any configuration attribute associated with the specified name. If there is no such attribute, no action is taken.
      Parameters:
        `name` - Name of the attribute to remove

    - #### setAttribute

          public void setAttribute(String name,
                          Object value)

      Set the configuration attribute with the specified name. Calling this with a `null` value is equivalent to calling `removeAttribute(name)`.
      Parameters:
        `name` - Name of the attribute to set
        `value` - Value of the attribute to set, or `null` to remove any setting for this attribute

    - #### getInstance

          public Log getInstance(Class<?> clazz)
                          throws LogConfigurationException

      Convenience method to derive a name from the specified class and call `getInstance(String)` with it.
      Parameters:
        `clazz` - Class for which a suitable Log name will be derived
      Returns:
        A log instance with a name of clazz.getName()
      Throws:
        `LogConfigurationException` - if a suitable `Log` instance cannot be returned

    - #### getFactory

          public static LogFactory getFactory()
                                       throws LogConfigurationException

      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 `org.apache.commons.logging.LogFactory` system property.
      - The JDK 1.3 Service Discovery mechanism
      - Use the properties file `commons-logging.properties` file, if found in the class path of this class. The configuration file is in standard `java.util.Properties` format and contains the fully qualified name of the implementation class with the key being the system property defined above.
      - Fall back to a default implementation class (`org.apache.commons.logging.impl.LogFactoryImpl`).

      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.

      Returns:
        The singleton LogFactory instance
      Throws:
        `LogConfigurationException` - if the implementation class is not available or cannot be instantiated.

    - #### getLog

          public static Log getLog(Class<?> clazz)
                            throws LogConfigurationException

      Convenience method to return a named logger, without the application having to care about factories.
      Parameters:
        `clazz` - Class from which a log name will be derived
      Returns:
        A log instance with a name of clazz.getName()
      Throws:
        `LogConfigurationException` - if a suitable `Log` instance cannot be returned

    - #### getLog

          public static Log getLog(String name)
                            throws LogConfigurationException

      Convenience method to return a named logger, without the application having to care about factories.
      Parameters:
        `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)
      Returns:
        A log instance with the requested name
      Throws:
        `LogConfigurationException` - if a suitable `Log` instance cannot be returned

    - #### release

          public static void release(ClassLoader classLoader)

      Release any internal references to previously created `LogFactory` instances that have been associated with the specified class loader (if any), after calling the instance method `release()` on each of them.
      Parameters:
        `classLoader` - ClassLoader for which to release the LogFactory

    - #### releaseAll

          public static void releaseAll()

      Release any internal references to previously created `LogFactory` instances, after calling the instance method `release()` on each of them. This is useful in environments like servlet containers, which implement application reloading by throwing away a ClassLoader. Dangling references to objects in that class loader would prevent garbage collection.

    - #### objectId

          public static String objectId(Object o)

      Returns a string that uniquely identifies the specified object, including its class.

      The returned string is of form "classname@hashcode", ie is the same as the return value of the Object.toString() method, but works even when the specified object's class has overridden the toString method.

      Parameters:
        `o` - may be null.
      Returns:
        a string of form classname@hashcode, or "null" if param o is null.

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.