Asktalk

JCL(Jakarta Commons Logging)和log4j不都是做log的嗎，怎么在jcl的源碼包中，還有個(gè)log4j的包？倒底怎么回事？看了jcl的用戶指南，就明白了。

 1、Commons-Loggin簡(jiǎn)介

　　Jakarta Commons Logging (JCL)提供的是一個(gè)日志(Log)接口(interface)，同時(shí)兼顧輕量級(jí)和不依賴于具體的日志實(shí)現(xiàn)工具。 它提供給中間件/日志工具開發(fā)者一個(gè)簡(jiǎn)單的日志操作抽象，允許程序開發(fā)人員使用不同的具體日志實(shí)現(xiàn)工具。用戶被假定已熟悉某種日志實(shí)現(xiàn)工具的更高級(jí)別的細(xì)節(jié)。JCL提供的接口，對(duì)其它一些日志工具，包括Log4J, Avalon LogKit, and JDK 1.4等，進(jìn)行了簡(jiǎn)單的包裝，此接口更接近于Log4J和LogKit的實(shí)現(xiàn).

2、快速入門

　　JCL有兩個(gè)基本的抽象類：Log(基本記錄器)和LogFactory(負(fù)責(zé)創(chuàng)建Log實(shí)例)。當(dāng)commons-logging.jar被加入到CLASSPATH之后，它會(huì)心可能合理地猜測(cè)你喜歡的日志工具，然后進(jìn)行自我設(shè)置，用戶根本不需要做任何設(shè)置。默認(rèn)的LogFactory是按照下列的步驟去發(fā)現(xiàn)并決定那個(gè)日志工具將被使用的（按照順序，尋找過程會(huì)在找到第一個(gè)工具時(shí)中止）:

1. 尋找當(dāng)前factory中名叫org.apache.commons.logging.Log配置屬性的值

2. 尋找系統(tǒng)中屬性中名叫org.apache.commons.logging.Log的值

3. 如果應(yīng)用程序的classpath中有log4j,則使用相關(guān)的包裝(wrapper)類(Log4JLogger)

4. 如果應(yīng)用程序運(yùn)行在jdk1.4的系統(tǒng)中，使用相關(guān)的包裝類(Jdk14Logger)

5. 使用簡(jiǎn)易日志包裝類(SimpleLog)

3、開發(fā)使用logging

日志信息被送往記錄器，如上例中的log。這個(gè)發(fā)送過程，是通過調(diào)用Log接口中定義的方法完成的，不同方法跟不同的級(jí)別聯(lián)系在一起，日志信息通過哪個(gè)級(jí)別的方法發(fā)送，就標(biāo)明了日志信息的級(jí)別。org.apache.commons.logging.Log接口中定義的方法,按嚴(yán)重性由高到低的順序有：

除此以外，還提供下列方法以便代碼保護(hù).

　　信息級(jí)別
　　確保日志信息在內(nèi)容上和反應(yīng)問題的嚴(yán)重程度上的恰當(dāng)，是非常重要的。

1. fatal非常嚴(yán)重的錯(cuò)誤，導(dǎo)致系統(tǒng)中止。期望這類信息能立即顯示在狀態(tài)控制臺(tái)上。

2. error其它運(yùn)行期錯(cuò)誤或不是預(yù)期的條件。期望這類信息能立即顯示在狀態(tài)控制臺(tái)上。

3. warn使用了不贊成使用的API、非常拙劣使用API, '幾乎就是'錯(cuò)誤, 其它運(yùn)行時(shí)不合需要和不合預(yù)期的狀態(tài)但還沒必要稱為 "錯(cuò)誤"。期望這類信息能立即顯示在狀態(tài)控制臺(tái)上。

4. info運(yùn)行時(shí)產(chǎn)生的有意義的事件。期望這類信息能立即顯示在狀態(tài)控制臺(tái)上。

5. debug系統(tǒng)流程中的細(xì)節(jié)信息。期望這類信息僅被寫入log文件中。

6. trace更加細(xì)節(jié)的信息。期望這類信息僅被寫入log文件中。

通常情況下，記錄器的級(jí)別不應(yīng)低于info.也就是說，通常情況下debug的信息不應(yīng)被寫入log文件中。
　　工作機(jī)理

1. 生命周期
   JCL LogFactory必須實(shí)現(xiàn)建立/斷開到日志工具的連接，實(shí)例化/初始化/解構(gòu)一個(gè)日志工具.

2. 異常處理
   JCL Log 接口沒有指定任何異常處理,對(duì)接口的實(shí)現(xiàn)必須捕獲并處理異常。

3.  

4. 多線程
   JCL Log 和 LogFactory 的實(shí)現(xiàn)，必須確保任何日志工具對(duì)并行的要求.

 

 

下面是官方文檔：以備參考

Introduction

The Jakarta Commons Logging (JCL) provides a Log interface that is intended to be both light-weight and an independent abstraction of other logging toolkits. It provides the middleware/tooling developer with a simple logging abstraction, that allows the user (application developer) to plug in a specific logging implementation.

JCL provides thin-wrapper Log implementations for other logging tools, including Log4J , Avalon LogKit , the Avalon Framework's logging infrastructure, JDK 1.4, and an implementation of JDK 1.4 logging APIs (JSR-47) for pre-1.4 systems. The interface maps closely to Log4J and LogKit.

Familiarity with high-level details of the relevant Logging implementations is presumed.

Quick Start

As far as possible, JCL tries to be as unobtrusive as possible. In most cases, including the (full) commons-logging.jar in the classpath should result in JCL configuring itself in a reasonable manner. There's a good chance that it'll guess your preferred logging system and you won't need to do any configuration at all!

Configuration

There are two base abstractions used by JCL: Log (the basic logger) and LogFactory (which knows how to create Log instances). Using LogFactory implementations other than the default is a subject for advanced users only, so let's concentrate on configuring the default implementation.

The default LogFactory implementation uses the following discovery process to determine what type of Log implementation it should use (the process terminates when the first positive match - in order - is found):

1.       Look for a configuration attribute of this factory named org.apache.commons.logging.Log (for backwards compatibility to pre-1.0 versions of this API, an attribute org.apache.commons.logging.log is also consulted).

2.       Look for a system property named org.apache.commons.logging.Log (for backwards compatibility to pre-1.0 versions of this API, a system property org.apache.commons.logging.log is also consulted).

3.       If the Log4J logging system is available in the application class path, use the corresponding wrapper class ( Log4JLogger ).

4.       If the application is executing on a JDK 1.4 system, use the corresponding wrapper class ( Jdk14Logger ).

5.       Fall back to the default simple logging wrapper ( SimpleLog ).

Consult the JCL javadocs for details of the various Log implementations that ship with the component. (The discovery process is also covered in more detail there.)

Configuring The Underlying Logging System

The JCL SPI can be configured to use different logging toolkits (see above ). JCL provides only a bridge for writing log messages. It does not (and will not) support any sort of configuration API for the underlying logging system.

Configuration of the behavior of the JCL ultimately depends upon the logging toolkit being used. Please consult the documentation for the chosen logging system.

Configuring Log4J

Log4J is a very commonly used logging implementation (as well as being the JCL primary default), so a few details are presented herein to get the developer/integrator going. Please see the Log4J Home for more details on Log4J and it's configuration.

Configure Log4J using system properties and/or a properties file:

• log4j.configuration=log4j.properties Use this system property to specify the name of a Log4J configuration file. If not specified, the default configuration file is log4j.properties.

• log4j.rootCategory=priority [, appender]* Set the default (root) logger priority.

• log4j.logger.logger.name=priority Set the priority for the named logger and all loggers hierarchically lower than, or below, the named logger. logger.name corresponds to the parameter of LogFactory.getLog(logger.name), used to create the logger instance. Priorities are: DEBUG, INFO, WARN, ERROR, or FATAL.
  
  Log4J understands hierarchical names, enabling control by package or high-level qualifiers: log4j.logger.org.apache.component=DEBUG will enable debug messages for all classes in both org.apache.component and org.apache.component.sub. Likewise, setting log4j.logger.org.apache.component=DEBUG will enable debug message for all 'component' classes, but not for other Jakarta projects.

• log4j.appender.appender.Threshold=priority Log4J appenders correspond to different output devices: console, files, sockets, and others. If appender's threshold is less than or equal to the message priority then the message is written by that appender. This allows different levels of detail to be appear at different log destinations. For example: one can capture DEBUG (and higher) level information in a logfile, while limiting console output to INFO (and higher).

Developing With JCL

To use the JCL SPI from a Java class, include the following import statements:

import org.apache.commons.logging.Log;

import org.apache.commons.logging.LogFactory;

Note that some components using JCL may either extend Log, or provide a component-specific LogFactory implementation. Review the component documentation for guidelines on how commons-logging should be used in such components.

For each class definition, declare and initialize a log attribute as follows:

public class CLASS

{

    private static Log log = LogFactory.getLog(CLASS.class);

    ...

    ;

       

Messages are logged to a logger, such as log by invoking a method corresponding to priority. The org.apache.commons.logging.Log interface defines the following methods for use in writing log/trace messages to the log:

    log.fatal(Object message);

    log.fatal(Object message, Throwable t);

    log.error(Object message);

    log.error(Object message, Throwable t);

    log.warn(Object message);

    log.warn(Object message, Throwable t);

    log.info(Object message);

    log.info(Object message, Throwable t);

    log.debug(Object message);

    log.debug(Object message, Throwable t);

    log.trace(Object message);

    log.trace(Object message, Throwable t);

       

Semantics for these methods are such that it is expected that the severity, from highest to lowest, of messages is ordered as above.

In addition to the logging methods, the following are provided for code guards:

    log.isFatalEnabled();

    log.isErrorEnabled();

    log.isWarnEnabled();

    log.isInfoEnabled();

    log.isDebugEnabled();

    log.isTraceEnabled();

       

JCL Best Practices

Best practices for JCL are presented in two categories: General and Enterprise. The general principles are fairly clear.Enterprise practices are a bit more involved and it is not always as clear as to why they are important.

Enterprise best-practice principles apply to middleware components and tooling that is expected to execute in an "Enterprise" level environment. These issues relate to Logging as Internationalization, and fault detection. Enterprise requires more effort and planning, but are strongly encouraged (if not required) in production level systems. Different corporate enterprises/environments have different requirements, so being flexible always helps.

Best Practices (General)

Code Guards

Code guards are typically used to guard code that only needs to execute in support of logging, that otherwise introduces undesirable runtime overhead in the general case (logging disabled). Examples are multiple parameters, or expressions (i.e. string + " more") for parameters. Use the guard methods of the form log.is<Priority>() to verify that logging should be performed, before incurring the overhead of the logging method call. Yes, the logging methods will perform the same check, but only after resolving parameters.

Message Priorities/Levels

It is important to ensure that log message are appropriate in content and severity. The following guidelines are suggested:

• fatal - Severe errors that cause premature termination. Expect these to be immediately visible on a status console. See also Internationalization .

• error - Other runtime errors or unexpected conditions. Expect these to be immediately visible on a status console. See also Internationalization .

• warn - Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". Expect these to be immediately visible on a status console. See also Internationalization .

• info - Interesting runtime events (startup/shutdown). Expect these to be immediately visible on a console, so be conservative and keep to a minimum. See also Internationalization .

• debug - detailed information on the flow through the system. Expect these to be written to logs only.

• trace - more detailed information. Expect these to be written to logs only.

Default Message Priority/Level

By default the message priority should be no lower than info. That is, by default debug message should not be seen in the logs.

Best Practices (Enterprise)

Logging Exceptions

The general rule in dealing with exceptions is to assume that the user (developer using a tooling/middleware API) isn't going to follow the rules. Since any problems that result are going to be assigned to you, it's in your best interest to be prepared with the proactive tools necessary to demonstrate that your component works correctly, or at worst that the problem can be analyzed from your logs. For this discussion, we must make a distinction between different types of exceptions based on what kind of boundaries they cross:

• External Boundaries - Expected Exceptions. This classification includes exceptions such as FileNotFoundException that cross API/SPI boundaries, and are exposed to the user of a component/toolkit. These are listed in the 'throws' clause of a method signature.
  
  Appropriate handling of these exceptions depends upon the type of code you are developing. API's for utility functions and tools should log these at the debug level, if they are caught at all by internal code.
  
  For higher level frameworks and middleware components, these exceptions should be caught immediatly prior to crossing the API/SPI interface back to user code-space, logged with full stack trace at info level, and rethrown. The assures that the log contains a record of the root cause for future analysis in the event that the exception is not caught and resolved as expected by the user's code.

• External Boundaries - Unexpected Exceptions. This classification includes exceptions such as NullPointerException that cross API/SPI boundaries, and are exposed to the user of a component/toolkit. These are runtime exceptions/error that are NOT listed in the 'throws' clause of a method signature.
  
  Appropriate handling of these exceptions depends upon the type of code you are developing. API's for utility functions and tools should log these at the debug level, if they are caught at all.
  
  For higher level frameworks and middleware components, these exceptions should be caught immediatly prior to crossing the API/SPI interface back to user code-space, logged with full stack trace at info level, and rethrown/wrapped as ComponentInternalError. The assures that the log contains a record of the root cause for future analysis in the event that the exception is not caught and logged/reported as expected by the user's code.

• Internal Boundaries. Exceptions that occur internally and are resolved internally. These should be logged when caught as debug or info messages, at the programmer's discretion.

• Significant Internal Boundaries. This typically only applies to middleware components that span networks or runtime processes. Exceptions that cross over significant internal component boundaries, such as networks. These should be logged when caught as info messages. Do not assume that such a (process/network) boundary will deliver exceptions to the 'other side'.

When Info Level Instead of Debug?

You want to have exception/problem information available for first-pass problem determination in a production level enterprise application without turning on debug as a default log level. There is simply too much information in debug to be appropriate for day-to-day operations.

More Control of Enterprise Exception Logging

If more control is desired for the level of detail of these 'enterprise' exceptions, then consider creating a special logger just for these exceptions:

   Log log = LogFactory.getLog("org.apache.component.enterprise");

This allows the 'enterprise' level information to be turned on/off explicitly by most logger implementations.

National Language Support And Internationalization

NLS internationalization involves looking up messages from a message file by a message key, and using that message for logging. There are various tools in Java, and provided by other components, for working with NLS messages.

NLS enabled components are particularly appreciated (that's an open-source-correct term for 'required by corporate end-users' :-) for tooling and middleware components.

NLS internationalization SHOULD be strongly considered for used for fatal, error, warn, and info messages. It is generally considered optional for debug and trace messages.

Perhaps more direct support for internationalizing log messages can be introduced in a future or alternate version of the Log interface.

Extending Commons Logging

JCL is designed to encourage extensions to be created that add functionality. Typically, extensions to JCL fall into two categories:

• new Log implementations that provide new bridges to logging systems

• new LogFactory implementations that provide alternative discovery strategies

Contract

When creating new implementations for Log and LogFactory, it is important to understand the implied contract between the factory and the log implementations:

• Life cycle

The JCL LogFactory implementation must assume responsibility for either connecting/disconnecting to a logging toolkit, or instantiating/initializing/destroying a logging toolkit.

• Exception handling

The JCL Log interface doesn't specify any exceptions to be handled, the implementation must catch any exceptions.

• Multiple threads

The JCL Log and LogFactory implementations must ensure that any synchronization required by the logging toolkit is met.

Creating a Log Implementation

The minimum requirement to integrate with another logger is to provide an implementation of the org.apache.commons.logging.Log interface. In addition, an implementation of the org.apache.commons.logging.LogFactory interface can be provided to meet specific requirements for connecting to, or instantiating, a logger.

The default LogFactory provided by JCL can be configured to instantiate a specific implementation of the org.apache.commons.logging.Log interface by setting the property of the same name (org.apache.commons.logging.Log). This property can be specified as a system property, or in the commons-logging.properties file, which must exist in the CLASSPATH.

Creating A LogFactory Implementation

If desired, the default implementation of the org.apache.commons.logging.LogFactory interface can be overridden, allowing the JDK 1.3 Service Provider discovery process to locate and create a LogFactory specific to the needs of the application. Review the Javadoc for the LogFactoryImpl.java for details.