From 028cb876a402f13f742a6950ba0d61bc3313289d Mon Sep 17 00:00:00 2001 From: Robert Burrell Donkin Date: Sun, 15 Feb 2004 10:28:56 +0000 Subject: [PATCH] Added maven build (aimed at documentation). This isn't totally satisfactory (for example, I've stripped out the unit tests) and the user guide formatting isn't brilliant. But i feel that i want to be able to get some feedback and there are some other priorities. i'll try to get to this work later. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/logging/trunk@139001 13f79535-47bb-0310-9956-ffa450edef68 --- xdocs/.cvsignore | 1 + xdocs/guide.xml | 526 +++++++++++++++++++++++++++++++++++++++++++ xdocs/index.xml | 77 +++++++ xdocs/navigation.xml | 31 +++ 4 files changed, 635 insertions(+) create mode 100644 xdocs/.cvsignore create mode 100644 xdocs/guide.xml create mode 100644 xdocs/index.xml create mode 100755 xdocs/navigation.xml diff --git a/xdocs/.cvsignore b/xdocs/.cvsignore new file mode 100644 index 0000000..cb6131b --- /dev/null +++ b/xdocs/.cvsignore @@ -0,0 +1 @@ +stylesheets diff --git a/xdocs/guide.xml b/xdocs/guide.xml new file mode 100644 index 0000000..c52daa4 --- /dev/null +++ b/xdocs/guide.xml @@ -0,0 +1,526 @@ + + + + + + Users Guide : Jakarta Commons Logging + Commons Documentation Team + + + + +
+

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

+ +

+Familiarity with high-level details of various Logging implementations is presumed. +

+ +

+The Jakarta Commons Logging provides a Log interface with thin-wrapper implementations for +other logging tools, including +Log4J, +Avalon LogKit, +and +JDK 1.4. +The interface maps closely to Log4J and LogKit. +

+ +
+
+

+As far as possible, Commons-Logging tries to be as unobtrusive as possible. +In most cases, including the (full) commons-logging.jar in the classpath +should result in Commons-Logging 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! +

+ +

+There are two base abstractions used by Commons-Logging: 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. +
  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. +
  3. +If the Log4J logging system is available in the application +class path, use the corresponding wrapper class +(Log4JLogger). +
    4. +
  4. +If the application is executing on a JDK 1.4 system, use +the corresponding wrapper class +(Jdk14Logger). +
    5. +
  5. +Fall back to the default simple logging wrapper +(SimpleLog). +
    6. +
+

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

+ +
+
+

+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 commons-logging 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(); + +
+ +

+Best practices for programming/planning 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. +

+ +

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

+ + +

+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 flow of through the system. +Expect these to be written to logs only. +
    • +
  • +trace - more detailed information. +Expect these to be written to logs only. +
    • +
+ + +

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

+ + +

+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 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'. +
    • +
+ + +

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

+ + +

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

+ + + +

+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 +(thats 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. +

+ +
+
+

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

+ + +

+The Jakarta Commons Logging SPI uses the +implementation of the org.apache.commons.logging.Log +interface specified by the system property +org.apache.commons.logging.Log. +If the property is not specified or the class is not available then the JCL +provides access to a default logging toolkit by searching the CLASSPATH +for the following toolkits, in order of preference: +

+
    +
  • +Log4J +
    • +
  • +JDK 1.4 +
    • +
  • +JCL SimpleLog +
    • +
+ + +

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

+ + + +

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

+ + +

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

+ + +

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

+ + + +

+The Jakarta Commons Logging (JCL) SPI +can be configured to use different logging toolkits. +

+

+Configuration of the behavior of the JCL ultimately depends upon the +logging toolkit being used. +The JCL SPI uses +Log4J +by default if it is available (in the CLASSPATH). +

+ +

+As +Log4J +is the default logger, +a few details are presented herein to get the developer/integrator going. +

+

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

+JCL doesn't (and cannot) impose any requirement on thread safety on the underlying implementation +and thus its SPI contract doesn't guarantee thread safety. +However, JCL can be safely used a multi-threaded environment +as long as the underlying implementation is thread-safe. +

+

+It would be very unusual for a logging system to be thread unsafe. +Certainly, JCL is thread safe when used with the distributed Log implementations. +

+ +
+ + diff --git a/xdocs/index.xml b/xdocs/index.xml new file mode 100644 index 0000000..6923d96 --- /dev/null +++ b/xdocs/index.xml @@ -0,0 +1,77 @@ + + + + + + Commons + Commons Documentation Team + + + + +
+ +

There is a great need for debugging and logging information inside of +Commons components such as HTTPClient and DBCP. However, there are many +logging APIs out there and it is difficult to choose among them.

+ +

The Logging package is an ultra-thin bridge between different logging +libraries. Commons components may use the Logging API to remove +compile-time and run-time dependencies on any particular logging package, +and contributors may write Log implementations for the library of +their choice.

+ +
+ + +
+ +

The +Release Notes document the new features and bug fixes that have been +included in the latest release.

+ +

The +JavaDoc API documents for the latest release are available online. +In particular, you should read the package overview of the org.apache.commons.logging +package. In addition, there is a (short) +User Guide.

+ +
+ + +
+ +

+Releases after 1.0.2 should be downloaded from a mirror. Please remember to verify the +sigature of the release from the +main apache site +when downloading from a mirror. +

+

+ Binary releases are available + here. + Source releases are available + here +

+

+

    +
  • Version 1.0.3 (latest) - 7 Apr 2003
    • +
+

+ + +

+

+

+ +
+ + + + diff --git a/xdocs/navigation.xml b/xdocs/navigation.xml new file mode 100755 index 0000000..5e6fcf0 --- /dev/null +++ b/xdocs/navigation.xml @@ -0,0 +1,31 @@ + + + +]> + + + + Logging + + Jakarta + + + + + + + + + + + + + &commons-nav; + + + +