1. 程式人生 > >APACHE COMMONS LOGGING

APACHE COMMONS LOGGING

Contents

  1. Introduction
  2. Quick Start
    1. Configuration
    2. Configuring The Underlying Logging System
    3. Configuring Log4J
  3. Developing With JCL
    1. Obtaining a Log Object
    2. Logging a Message
    3. Serialization Issues
  4. Jars Included in the Standard Distribution
    1. commons-logging.jar
    2. commons-logging-api.jar
    3. commons-logging-adapters.jar
  5. JCL Best Practices
  6. Best Practices (General)
    1. Code Guards
    2. Message Priorities/Levels
    3. Default Message Priority/Level
  7. Best Practices (Enterprise)
    1. Logging Exceptions
    2. When Info Level Instead of Debug?
    3. More Control of Enterprise Exception Logging
    4. National Language Support And Internationalization
    5. Classloader and Memory Management
  8. Extending Commons Logging
    1. Contract
    2. Creating a Log Implementation
    3. Creating A LogFactory Implementation
  9. A Quick Guide To Simple Log
  10. Frequently Asked Questions

Introduction

The Apache 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 Log4JAvalon 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 (discover) your preferred logging system and you won't need to do any configuration of JCL at all!

Note, however, that if you have a particular preference then providing a simple commons-logging.properties file which specifies the concrete logging library to be used is recommended, since (in this case) JCL will log only to that system and will report any configuration problems that prevent that system being used.

When no particular logging library is specified then JCL will silently ignore any logging library that it finds but cannot initialise and continue to look for other alternatives. This is a deliberate design decision; no application should fail to run because a "guessed" logging library cannot be used. To ensure an exception is reported when a particular logging library cannot be used, use one of the available JCL configuration mechanisms to force that library to be selected (ie disable JCL's discovery process).

Configuration

There are two base abstractions used by JCL: Log (the basic logger) and LogFactory (which knows how to create Log instances). Specifying a particular Log implementation is very useful (whether that is one provided by commons-logging or a user-defined one). Specifying a LogFactoryimplementation other than the default is a subject for advanced users only, so will not be addressed here.

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

    Configuration attributes can be set explicitly by java code, but they are more commonly set by placing a file named commons-logging.properties in the classpath. When such a file exists, every entry in the properties file becomes an "attribute" of the LogFactory. When there is more than one such file in the classpath, releases of commons-logging prior to 1.1 simply use the first one found. From release 1.1, each file may define a prioritykey, and the file with the highest priority is used (no priority definition implies priority of zero). When multiple files have the same priority, the first one found is used.

    Defining this property in a commons-logging.properties file is the recommended way of explicitly selecting a Log implementation.

  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.

JCL is NOT responsible for initialisation, configuration or shutdown of the underlying logging library. In many cases logging libraries will automatically initialise/configure themselves when first used, and need no explicit shutdown process. In these situations an application can simply use JCL and not depend directly on the API of the underlying logging system in any way. However if the logging library being used requires special initialisation, configuration or shutdown then some logging-library-specific code will be required in the application. JCL simply forwards logging method calls to the correct underlying implementation. When writing library code this issue is of course not relevant as the calling application is responsible for handling such issues.

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,INFOWARNERROR, or FATAL
    Log4J understands hierarchical names, enabling control by package or high-level qualifiers: log4j.logger.org.apache.component=DEBUGwill enable debug messages for all classes in both org.apache.component and org.apache.component.sub. Likewise, settinglog4j.logger.org.apache.component=DEBUG will enable debug message for all 'component' classes, but not for other Apache projects.
  • log4j.appender.appender.Threshold=priorityLog4J 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

Obtaining a Log Object

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 Log log = LogFactory.getLog(CLASS.class);
    ...
    ;
        

Note that for application code, declaring the log member as "static" is more efficient as one Log object is created per class, and is recommended. However this is not safe to do for a class which may be deployed via a "shared" classloader in a servlet or j2ee container or similar environment. If the class may end up invoked with different thread-context-classloader values set then the member must not be declared static. The use of "static" should therefore be avoided in code within any "library" type project.

Logging a Message

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();
        

Serialization Issues

Prior to release 1.0.4, none of the standard Log implementations were Serializable. If you are using such a release and have a Serializable class with a member that is of type Log then it is necessary to declare that member to be transient and to ensure that the value is restored on deserialization. The recommended approach is to define a custom readObject method on the class which reinitializes that member.

In release 1.0.4, all standard Log implementations are Serializable. This means that class members of type Log do not need to be declared transient; on deserialization the Log object will "rebind" to the same category for the same logging library. Note that the same underlying logging library will be used on deserialization as was used in the original object, even if the application the object was deserialized into is using a different logging library. There is one exception; LogKitLogger (adapter for the Avalon LogKit library) is not Serializable for technical reasons.

Custom Log implementations not distributed with commons-logging may or may not be Serializable. If you wish your code to be compatible with any arbitrary log adapter then you should follow the advice given above for pre-1.0.4 releases.

Jars Included in the Standard Distribution

commons-logging.jar

The commons-logging.jar file includes the JCL API, the default LogFactory implementation and thin-wrapper Log implementations for Log4J,Avalon LogKit, the Avalon Framework's logging infrastructure, JDK 1.4, as well as an implementation of JDK 1.4 logging APIs (JSR-47) for pre-1.4 systems.

In most cases, including commons-logging.jar and your preferred logging implementation in the classpath should be all that is required to use JCL.

commons-logging-api.jar

The commons-logging-api.jar file includes the JCL API and the default LogFactory implementation as well as the built-in Logimplementations SimpleLog and NoOpLog. However it does not include the wrapper Log implementations that require additional libraries such asLog4jAvalon and Lumberjack.

This jar is intended for use by projects that recompile the commons-logging source using alternate java environments, and cannot compile against all of the optional libraries that the Apache release of commons-logging supports. Because of the reduced dependencies of this jarfile, such projects should be able to create an equivalent of this library with fewer difficulties.

This jar is also useful for build environments that automatically track dependencies, and thus have difficulty with the concept that the main commons-logging.jar has "optional" dependencies on various logging implementations that can safely go unsatisfied at runtime.

commons-logging-adapters.jar

The commons-logging-adapters.jar file includes only adapters to third-party logging implementations, and none of the core commons-logging framework. As such, it cannot be used alone; either commons-logging.jar or commons-logging-api.jar must also be present in the classpath.

This library will not often be used; it is only intended for situations where a container has deployed commons-logging-api.jar in a shared classpath but a webapp wants to bind logging to one of the external logging implementations that the api jar does not include. In this situation, deploying the commons-logging.jar file within the webapp can cause problems as this leads to duplicates of the core commons-logging classes (Log, LogFactory, etc) in the classpath which in turn can cause unpleasant ClassCastException exceptions to occur. Deploying only the adapters avoids this problem.

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 (e.g. 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 immediately 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. APIs 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 immediately 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. This ensures 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 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 andmiddleware components.

NLS internationalization SHOULD be strongly considered for used for fatalerrorwarn, and info messages. It is generally considered optional for debugand trace messages.

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

Classloader and Memory Management

The LogFactory discovery process (see Configuration above) is a fairly expensive operation, so JCL certainly should not perform it each time user code invokes:


LogFactory.getLog()

Instead JCL caches the LogFactory implementation created as a result of the discovery process and uses the cached factory to return Log objects. Since in J2EE and similar multi-classloader environments, the result of the discovery process can vary depending on the thread context classloader (e.g. one webapp in a web container may be configured to use Log4j and another to use JDK 1.4 logging), JCL internally caches the LogFactory instances in a static hashtable, keyed by classloader.

While this approach is efficient, it can lead to memory leaks if container implementors are not careful to call


LogFactory.release()

whenever a classloader that has utilized JCL is undeployed. If release() is not called, a reference to the undeployed classloader (and thus to all the classes loaded by it) will be held in LogFactory's static hashtable.

Beginning with JCL 1.1, LogFactory caches factory implementations in a "WeakHashtable". This class is similar to java.util.WeakHashMap in that it holds a WeakReference to each key (but a strong reference to each value), thus allowing classloaders to be GC'd even ifLogFactory.release() is never invoked.

Because WeakHashtable depends on JDK 1.3+ features, it is dynamically loaded depending on the JVM version; when commons-logging is run on java versions prior to 1.3 the code defaults to a standard Hashtable instead.

If a custom LogFactory implementation is used, however, then a WeakHashtable alone can be insufficient to allow garbage collection of a classloader without a call to release. If the abstract class LogFactory is loaded by a parent classloader and a concrete subclass implementation ofLogFactory is loaded by a child classloader, the WeakHashtable's key is a weak reference to the TCCL (child classloader), but the value is a strong reference to the LogFactory instance, which in turn contains a strong reference to its class and thus loading classloader - the child classloader. This chain of strong references prevents the child loader from being garbage collected.

If use of a custom LogFactory subclass is desired, ensuring that the custom subclass is loaded by the same classloader as LogFactory will prevent problems. In normal deployments, the standard implementations of LogFactory found in package org.apache.commons.logging.implwill be loaded by the same classloader that loads LogFactory itself, so use of the standard LogFactory implementation should not pose problems. Alternatively, use the provided ServletContextCleaner to ensure this reference is explicitly released on webapp unload.

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

相關推薦

Caused by: java.lang.ClassNotFoundException: org.apache.commons.logging.LogFactory

pro .com spa exception nbsp build 下載 .org col 運行一個Spring程序的時候,一直報錯,如下: 解決辦法: 下載 :commons-logging-1.2.jar包 地址:http://commons

APACHE COMMONS LOGGING

Contents Introduction Quick Start Configuration Configuring The Underlying Logging System Configuring Log4J

【Java筆記】java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory解決方法

解決方法:匯入commons-logging.jar包 如果用的是maven直接用: <dependency>         <groupId>commons-logging</g

“org/apache/commons/logging/LogFactory”錯誤的解決方式

用spring-framework-4.2.6.RELEASE-dist時,發生瞭如下的錯誤:Exception in thread "main" java.lang.NoClassDefFoundE

java lang NoClassDefFoundError org/apache/commons/logging/L

                Exception in thread "main" java.lang.NoClassDefFo

java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory解決方法

解決方法:匯入commons-logging.jar包 如果用的是maven直接用: <dependency>         <groupId>commons-logging</groupId>         <artifact

org.apache.commons.logging的用法(上)

類: import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; 1)private static Log testLogger = LogFactory.getL

Apache Commons Digester 二(規則模塊綁定-RulesModule、異步解析-asyncParse、xml變量Substitutor、帶參構造方法)

對象 property 解決 space getclass bool trace throw object 前言 上一篇對Digester做了基本介紹,也已經了解了Digester的基本使用方法,接下來將繼續學習其相關特性,本篇主要涉及以下幾個內容: 規則模塊綁定,

【FTP】org.apache.commons.net.ftp.FTPClient實現復雜的上傳下載,操作目錄,處理編碼

ttr hide working log 登錄 有一個 ima spl att 和上一份簡單 上傳下載一樣 來,任何的方法不懂的,http://commons.apache.org/proper/commons-net/apidocs/org/apache/commons/

java.lang.NoClassDefFoundError: org/apache/commons/lang3/StringUtils

apache con ont test oca action error esp iat 1.java.lang.NoClassDefFoundError: org/apache/commons/lang3/StringUtils 缺少類 2. There is no Ac

commons-logging日誌實現解耦

truct illegal 工廠 man int 行為 efault context buffered 一、需要解耦 日誌是實際應用中的一個重要部分,日誌系統也有許多開源的實現,如java.util.logging, logback, log4j系列等。

java.lang.ClassNotFoundException: org.apache.commons.dbutils.QueryRunner

ica ror server acc dwr comm erro tor reads 七月 28, 2017 11:06:33 下午 org.apache.catalina.core.StandardWrapperValve invoke嚴重: Servlet.serv

log4j+logback+slf4j+commons-logging的關系與調試

參數化 超過 日誌組 roo imp years config faq ase 參考鏈接:http://www.cnblogs.com/zhuawang/p/3999235.html 一、問題背景 由於現在開源框架日益豐富,好多開源框架使用的日誌組件不盡相同。存在著

【Java】日誌知識總結和經常使用組合配置(commons-logging,log4j,slf4j,logback)

ng- binder mono leading black auto erb param 1.2 Log4j Apache的一個開放源碼項目,通過使用Log4j,我們能夠控制日誌信息輸送的目的地是控制臺、文件、GUI組件、甚至是套接口服務 器

jar包下載步驟 commons-logging

資源 jar包下載 tca 好好學習 下載網址 block 項目 開發 org 禮悟: 好好學習多思考,尊師重道存感恩。葉見尋根三返一,活水清源藏於零。 虛懷若谷良心主,皓月當空自在王。願給最苦行無悔,誠勸且行且珍惜。   

使用Apache Commons IO組件讀取大文件

utils apache 普通 out right ack close 一次 solid Apache Commons IO讀取文件代碼如下: Files.readLines(new File(path), Charsets.UTF_8); FileUtils.readLi

Apache commons-vfs2

vfs java 依賴:<dependencies> <!-- https://mvnrepository.com/artifact/org.apache.commons/commons-vfs2 --> <dependency> &

NoClassDefFoundError: org/apache/juli/logging/LogFactory

gin class gpo ont png blog col noclass 添加 將 apache-tomcat-7.0.8\lib 下的 tomcat-util.jar添加到 註:不是 直接在 configure build path 中添加 jar NoC

Java中的日誌——Java.util.logging、log4j、commons-logging

mark svg pen xtra pat sstream ogg package ice Java中給項目程序添加log主要有三種方式,一使用JDK中的java.util.logging包,一種是log4j,一種是commons-logging。其中log4j和co

Apache commons(Java常用工具包)簡介

機制 encode 解析 help IT PE tom base cit Apache Commons是一個非常有用的工具包,解決各種實際的通用問題,下面是一個簡述表,詳細信息訪問http://jakarta.apache.org/commons/index.html Be