commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Richard Sitze <rsi...@us.ibm.com>
Subject [logging] Common Logging 2.0? EnterpriseLogFactory.java
Date Thu, 09 Dec 2004 20:28:30 GMT
[Looks like the attachments got lost...  Let's try them separately]


package org.apache.commons.logging;


/**
 * <p>Factory for creating {@link Log} and {@link EnterpriseLog} 
instances, 
 * with discovery and configuration features similar to that employed by 
 * standard Java APIs such as JAXP.</p>
 *
 * <p>Please note that a specific implementation of Commons Logging can 
choose 
 * to support either the simple logging interface defined by {@link Log}) 
or 
 * the advanced logging interface defined by {@link EnterpriseLog}.  A 
user 
 * of a Common Logging implementation that supports only the simple 
logging 
 * interface will not be able to instantiate a <code>EnterpriseLog</code>. 
 
 * Conversely, a user of a Common Logging implementation that supports the 

 * advanced logging interface will be able to instantiate either a 
<code>Log</code>
 * or <code>EnterpriseLog</code>.
 *
 */
public abstract class EnterpriseLogFactory extends LogFactory{


    // ----------------------------------------------------- Manifest 
Constants

    // ----------------------------------------------------------- 
Constructors


    /**
     * Protected constructor that is not available for public use.
     */
    protected EnterpriseLogFactory()
    {
        // TBD
    }


    // --------------------------------------------------------- Public 
Methods

    /**
     * <p>Construct (if necessary) and return a <code>EnterpriseLog</code>

instance,
     * using the factory's current set of configuration attributes.</p>
     *
     * <p><strong>NOTE</strong> - Depending upon the implementation of
     * the <code>EnterpriseLogFactory</code> you are using, the 
     * <code>EnterpriseLog</code> 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>EnterpriseLog</code> instance 
to be
     *  returned (the meaning of this name is only known to the underlying
     *  logging implementation that is being wrapped)
     * 
     * @param resourceBundleName Logical name of the repository to use 
when
     *  retrieving internationalized message text (the meaning of this 
name is 
     *  only known to the underlying logging implementation that is being 
wrapped,
     *  but a common usage would be the name of a Java resources bundle)
     *
     * @exception LogConfigurationException if a suitable <code>Log</code>
     *  instance cannot be returned
     */
    public abstract EnterpriseLog getEnterpriseInstance(String name,
         String resourceBundleName) throws LogConfigurationException;


    // --------------------------------------------------------- Static 
Methods


    /**
     * <p>Construct (if necessary) and return a 
<code>EnterpriseLogFactory</code>
     * instance, using the following ordered lookup procedure to determine
     * the name of the implementation class to be loaded.</p>
     * <ul>
     * <li>The <code>org.apache.commons.logging.LogFactory</code> system
     *     property.</li>
     * <li>The JDK 1.3 Service Discovery mechanism</li>
     * <li>Use the properties file <code>commons-logging.properties</code>
     *     file, if found in the class path of this class.  The 
configuration
     *     file is in standard <code>java.util.Properties</code> 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.EnterpriseLogFactoryImpl</code>).</li>
     * </ul>
     *
     * <p><em>NOTE</em> - If the properties file method of identifying the
     * <code>EnterpriseLogFactory</code> implementation class is utilized, 
all of the
     * properties defined in this file will be set as configuration 
attributes
     * on the corresponding <code>EnterpriseLogFactory</code> 
instance.</p>
     *
     * @exception LogConfigurationException if the implementation class is 
not
     *  available or cannot be instantiated.
     */
    public static EnterpriseLogFactory getEnterpriseFactory() 
          throws LogConfigurationException
    {
        // TBD
    }


    /**
     * Convenience method to return a named enterprise logger, without the 

     * application having to care about factories.
     *
     * @param name Logical name of the <code>EnterpriseLog</code> instance 
to be
     *  returned (the meaning of this name is only known to the underlying
     *  logging implementation that is being wrapped)
     * 
     * 
     * @param resourceBundleName Logical name of the repository to use 
when
     *  retrieving internationalized message text (the meaning of this 
name is 
     *  only known to the underlying logging implementation that is being 
wrapped,
     *  but a common usage would be the name of a Java resources bundle)
     *
     * @exception LogConfigurationException if a suitable <code>Log</code>
     *  instance cannot be returned
     */
    public static EnterpriseLog getEnterpriseLog(String name, String 
resourceBundleName)
        throws LogConfigurationException
    {

        return (getEnterpriseFactory().getEnterpriseInstance(name, 
resourceBundleName));
    }


    // ------------------------------------------------------ Protected 
Methods

    // TBD
}


*******************************************
Richard A. Sitze
IBM WebSphere WebServices Development

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message