|
Keel 2.1RC2 | ||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||||
See:
Description
| Interface Summary | |
| Log | A simple logging interface abstracting logging APIs. |
| Class Summary | |
| AbstractLogTest | |
| LoadTest | testcase to emulate container and application isolated from container |
| LoadTest.AppClassLoader | |
| LogFactory | Factory for creating Log instances, with discovery and configuration features similar to that employed by standard Java APIs such as JAXP. |
| LogSource | Deprecated. Use LogFactory instead - The default factory implementation performs exactly the same algorithm as this class did |
| LogTest | |
| NoOpLogTest | |
| SimpleLogTest | |
| TestAll | The build script calls just one TestSuite - this one! All tests should be written into separate TestSuite's and added to this. |
| UserClass | |
| Wrapper | Wrapper around test cases that need to have a custom class loader hierarchy assembled. |
| Exception Summary | |
| LogConfigurationException | An exception that is thrown only if a suitable LogFactory or Log instance cannot be created by the corresponding factory methods. |
Simple wrapper API around multiple logging APIs.
This package provides an API for logging in server-based applications that can be used around a variety of different logging implementations, including prebuilt support for the following:
java.util.logging.Logger instance.Logger.For those impatient to just get on with it, the following example illustrates the typical declaration and use of a logger that is named (by convention) after the calling class:
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
public class Foo {
static Log log = LogFactory.getLog(this.class);
public void foo() {
...
try {
if (log.isDebugEnabled()) {
log.debug("About to do something to object " + name);
}
name.bar();
} catch (IllegalStateException e) {
log.error("Something bad happened to " + name, e);
}
...
}
Unless you configure things differently, all log output will be written to System.err. Therefore, you really will want to review the remainder of this page in order to understand how to configure logging for your application.
LogFactory ImplementationFrom an application perspective, the first requirement is to retrieve an object reference to the LogFactory instance that will be used to create Log instances for this application. This is normally accomplished by calling the static getFactory() method. This method implements the following discovery algorithm to select the name of the LogFactory implementation class this application wants to use:
org.apache.commons.logging.LogFactory.META-INF/services/org.apache.commons.logging.LogFactory whose first line is assumed to contain the desired class name.commons-logging.properties visible in the application class path, with a property named org.apache.commons.logging.LogFactory defining the desired implementation class name.If a commons-logging.properties file is found, all of the properties defined there are also used to set configuration attributes on the instantiated LogFactory instance.
Once an implementation class name is selected, the corresponding class is loaded from the current Thread context class loader (if there is one), or from the class loader that loaded the LogFactory class itself otherwise. This allows a copy of commons-logging.jar to be shared in a multiple class loader environment (such as a servlet container), but still allow each web application to provide its own LogFactory implementation, if it so desires. An instance of this class will then be created, and cached per class loader.
LogFactory ImplementationThe Logging Package APIs include a default LogFactory implementation class ( org.apache.commons.logging.impl.LogFactoryImpl) that is selected if no other implementation class name can be discovered. Its primary purpose is to create (as necessary) and return Log instances in response to calls to the getInstance() method. The default implementation uses the following rules:
Log instance of the same name will be created. Subsequent getInstance() calls to the same LogFactory instance, with the same name or Class parameter, will return the same Log instance.Log instance must be created, the default LogFactory implementation uses the following discovery process is used:
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)..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).LogFactory class otherwise.Log implementation class, passing the specified name as the single argument to its constructor.See the SimpleLog JavaDocs for detailed configuration information for this default implementation.
The basic principle is that the user is totally responsible for the configuration of the underlying logging system. Commons-logging should not change the existing configuration.
Each individual Log implementation may support its own configuration properties. These will be documented in the class descriptions for the corresponding implementation class.
Finally, some Log implementations (such as the one for Log4J) require an external configuration file for the entire logging environment. This file should be prepared in a manner that is specific to the actual logging technology being used.
Use of the Logging Package APIs, from the perspective of an application component, consists of the following steps:
debug(), info(), warn(), error, and fatal()).For convenience, LogFactory also offers a static method getLog() that combines the typical two-step pattern:
Log log = LogFactory.getFactory().getInstance("Foo");
into a single method call:
Log log = LogFactory.getLog("Foo");
For example, you might use the following technique to initialize and use a Log instance in an application component:
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
public class MyComponent {
protected static Log log =
LogFactory.getLog("my.component");
// Called once at startup time
public void start() {
...
log.info("MyComponent started");
...
}
// Called once at shutdown time
public void stop() {
...
log.info("MyComponent stopped");
...
}
// Called repeatedly to process a particular argument value
// which you want logged if debugging is enabled
public void process(String value) {
...
// Do the string concatenation only if logging is enabled
if (log.isDebugEnabled())
log.debug("MyComponent processing " + value);
...
}
}
|
Keel 2.1RC2 | ||||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | ||||||||||