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 - and provides no plugin for other LogFactory implementation - 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
`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
`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)
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
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.

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
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)
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.