commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robert burrell donkin <robertburrelldon...@blueyonder.co.uk>
Subject Re: cvs commit: jakarta-commons/digester/xdocs guide.xml
Date Sun, 15 Feb 2004 10:21:30 GMT
oops! based the new logging on the digester stuff but forgot to remove  
the CVS directory. Doh!

fixing now.

- robert

On 15 Feb 2004, at 09:59, robert burrell donkin wrote:

> darn.
>
> something went wrong here. i'm pretty sure that these were committed  
> from the logging directory. i'm looking into it now.
>
> - robert
>
> On 15 Feb 2004, at 09:39, rdonkin@apache.org wrote:
>
>> rdonkin     2004/02/15 01:39:02
>>
>>   Added:       digester/xdocs guide.xml
>>   Log:
>>   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.
>>
>>   Revision  Changes    Path
>>   1.1                  jakarta-commons/digester/xdocs/guide.xml
>>
>>   Index: guide.xml
>>   ===================================================================
>>   <?xml version="1.0"?>
>>
>>   <document>
>>
>>    <properties>
>>     <title>Users Guide : Jakarta Commons Logging</title>
>>     <author email="commons-dev@jakarta.apache.org">Commons  
>> Documentation Team</author>
>>    </properties>
>>
>>    <body>
>>
>>       <section name="Introduction">
>>           <p>
>>   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.
>>       </p>
>>
>>           <p>
>>   Familiarity with high-level details of various Logging  
>> implementations is presumed.
>>       </p>
>>
>>           <p>
>>   The Jakarta Commons Logging provides a Log interface with  
>> thin-wrapper implementations for
>>   other logging tools, including
>>   <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>,
>>   <a href="http://jakarta.apache.org/avalon/logkit/index.html">Avalon  
>> LogKit</a>,
>>   and
>>   <a>JDK 1.4</a>.
>>   The interface maps closely to Log4J and LogKit.
>>       </p>
>>
>>   </section>
>>       <section name="Users Quick Start">
>>           <p>
>>   As far as possible, <em>Commons-Logging</em> tries to be as  
>> unobtrusive as possible.
>>   In most cases, including the (full)  
>> <code>commons-logging.jar</code> in the classpath
>>   should result in <em>Commons-Logging</em> 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!
>>       </p>
>>           <subsection name='Configuration'>
>>               <p>
>>   There are two base abstractions used by <em>Commons-Logging</em>: 

>> <code>Log</code>
>>   (the basic logger) and <code>LogFactory</code> (which knows how to
 
>> create <code>Log</code>
>>   instances). Using <code>LogFactory</code> implementations other  
>> than the default is a
>>   subject for advanced users only, so let's concentrate on  
>> configuring the default
>>   implementation.
>>           </p>
>>               <p>
>>   The default <code>LogFactory</code> implementation uses the  
>> following discovery process
>>   to determine what type of <code>Log</code> implementation it should
 
>> use
>>   (the process terminates when the first positive match - in order -  
>> is found):
>>           </p>
>>
>>               <ol>
>>                   <li>
>>   Look for a configuration attribute of this factory named
>>   <code>org.apache.commons.logging.Log</code> (for backwards
>>   compatibility to pre-1.0 versions of this API, an attribute
>>   <code>org.apache.commons.logging.log</code> is also consulted).
>>               </li>
>>                   <li>
>>   Look for a system property named
>>   <code>org.apache.commons.logging.Log</code> (for backwards
>>   compatibility to pre-1.0 versions of this API, a system property
>>   <code>org.apache.commons.logging.log</code> is also consulted).
>>               </li>
>>                   <li>
>>   If the Log4J logging system is available in the application
>>   class path, use the corresponding wrapper class
>>   (<a  
>> href="http://jakarta.apache.org/commons/logging/api/org/apache/ 
>> commons/logging/impl/Log4JLogger.html">Log4JLogger</a>).
>>               </li>
>>                   <li>
>>   If the application is executing on a JDK 1.4 system, use
>>   the corresponding wrapper class
>>   (<a  
>> href="http://jakarta.apache.org/commons/logging/api/org/apache/ 
>> commons/logging/impl/Jdk14Logger.html">Jdk14Logger</a>).
>>               </li>
>>                   <li>
>>   Fall back to the default simple logging wrapper
>>   (<a  
>> href="http://jakarta.apache.org/commons/logging/api/org/apache/ 
>> commons/logging/impl/SimpleLog.html">SimpleLog</a>).
>>               </li>
>>           </ol>
>>               <p>
>>   Consult the <em>Commons-Logging</em> javadocs for details of the  
>> various <code>Log</code>
>>   implementations that ship with the component. (The discovery  
>> process is also covered in more
>>   detail there.)
>>           </p>
>>       </subsection>
>>   </section>
>>       <section name='Developers'>
>>           <p>
>>   To use the JCL SPI from a Java class,
>>   include the following import statements:
>>       </p>
>>           <ul>
>>               <code>
>>   import org.apache.commons.logging.Log;
>>   <br/>
>>   import org.apache.commons.logging.LogFactory;
>>   <br/>
>>           </code>
>>       </ul>
>>           <p>
>>   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.
>>       </p>
>>           <p>
>>   For each class definition, declare and initialize a
>>   <code>log</code> attribute as follows:
>>       </p>
>>           <ul>
>>               <source>
>>   public class CLASS
>>   {
>>       private static Log log = LogFactory.getLog(CLASS.class);
>>       ...
>>       ;
>>           </source>
>>       </ul>
>>           <p>
>>   Messages are logged to a <em>logger</em>, such as <code>log</code>
>>   by invoking a method corresponding to <em>priority</em>.
>>   The <code>org.apache.commons.logging.Log</code> interface defines 

>> the
>>   following methods for use
>>   in writing log/trace messages to the log:
>>       </p>
>>           <ul>
>>               <source>
>>       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);
>>           </source>
>>       </ul>
>>           <p>
>>   Semantics for these methods are such that it is expected
>>   that the severity, from highest to lowest, of messages is ordered  
>> as above.
>>       </p>
>>           <p>
>>   In addition to the logging methods, the following are provided for  
>> code guards:
>>       </p>
>>           <ul>
>>               <source>
>>       log.isFatalEnabled();
>>       log.isErrorEnabled();
>>       log.isWarnEnabled();
>>       log.isInfoEnabled();
>>       log.isDebugEnabled();
>>       log.isTraceEnabled();
>>           </source>
>>       </ul>
>>           <subsection name='Best Practices'>
>>               <p>
>>   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.
>>           </p>
>>               <p>
>>   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.
>>           </p>
>>               <subsection name='General - Code Guards'>
>>                   <p>
>>   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  
>> <code>log.is&lt;<i>Priority</i>>()</code> 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.
>>               </p>
>>           </subsection>
>>               <subsection name='General - Message Priorities/Levels'>
>>                   <p>
>>   It is important to ensure that log message are
>>   appropriate in content and severity.
>>   The following guidelines are suggested:
>>               </p>
>>                   <ul>
>>                       <li>
>>   <b>fatal</b> - Severe errors that cause premature termination.
>>   Expect these to be immediately visible on a status console.
>>   See also <a HREF="#Internationalization">Internationalization</a>.
>>                   </li>
>>                       <li>
>>   <b>error</b> - Other runtime errors or unexpected conditions.
>>   Expect these to be immediately visible on a status console.
>>   See also <a HREF="#Internationalization">Internationalization</a>.
>>                   </li>
>>                       <li>
>>   <b>warn</b> - 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 <a HREF="#Internationalization">Internationalization</a>.
>>                   </li>
>>                       <li>
>>   <b>info</b> - Interesting runtime events (startup/shutdown).
>>   Expect these to be immediately visible on a console,
>>   so be conservative and keep to a minimum.
>>   See also <a HREF="#Internationalization">Internationalization</a>.
>>                   </li>
>>                       <li>
>>   <b>debug</b> - detailed information on flow of through the system.
>>   Expect these to be written to logs only.
>>                   </li>
>>                       <li>
>>   <b>trace</b> - more detailed information.
>>   Expect these to be written to logs only.
>>                   </li>
>>               </ul>
>>           </subsection>
>>               <subsection name='General - Default Message  
>> Priority/Level'>
>>                   <p>
>>   By default the message priority should be no lower than <b>info</b>.
>>   That is, by default <b>debug</b> message should not be seen in the
 
>> logs.
>>               </p>
>>           </subsection>
>>               <subsection name='Enterprise - Logging Exceptions'>
>>                   <p>
>>   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:
>>               </p>
>>                   <ul>
>>                       <li>
>>   <b>External Boundaries - Expected Exceptions</b>.
>>   This classification includes exceptions such as  
>> <code>FileNotFoundException</code>
>>   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.
>>   <br/>
>>   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  
>> <b>debug</b> level,
>>   if they are caught at all by internal code.
>>   <br/>
>>   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 <b>info</b> level,
>>   and rethrown.
>>   The assures that the log contains a record of the root cause for
>>   future analysis <i>in the event that the exception is not caught  
>> and resolved
>>   as expected by the user's code</i>.
>>   <br/>
>>                   </li>
>>                       <li>
>>   <b>External Boundaries - Unexpected Exceptions</b>.
>>   This classification includes exceptions such as  
>> <code>NullPointerException</code>
>>   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.
>>   <br/>
>>   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  
>> <b>debug</b> level,
>>   if they are caught at all.
>>   <br/>
>>   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 <b>info</b> level,
>>   and rethrown/wrapped as <code><i>Component</i>InternalError</code>.
>>   The assures that the log contains a record of the root cause for
>>   future analysis <i>in the event that the exception is not caught and
>>   logged/reported as expected by the user's code</i>.
>>                   </li>
>>                       <li>
>>   <b>Internal Boundaries</b>.
>>   Exceptions that occur internally and are resolved internally.
>>   These should be logged when caught as <b>debug</b> or <b>info</b>
 
>> messages,
>>   at the programmer's discretion.
>>                   </li>
>>                       <li>
>>   <b>Significant Internal Boundaries</b>.
>>   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 <b>info</b> messages.
>>   Do not assume that such a (process/network) boundary will deliver  
>> exceptions to the 'other side'.
>>                   </li>
>>               </ul>
>>           </subsection>
>>               <subsection name='Why info level instead of debug?'>
>>                   <p>
>>   You want to have exception/problem information available for
>>   first-pass problem determination in a production level
>>   enterprise application without turning on <b>debug</b>
>>   as a default log level.  There is simply too much information
>>   in <b>debug</b> to be appropriate for day-to-day operations.
>>               </p>
>>           </subsection>
>>               <subsection name='More Control of Enterprise Exception  
>> Logging'>
>>                   <p>
>>   If more control is desired for the level of detail of these
>>   'enterprise' exceptions, then consider creating a special
>>   logger just for these exceptions:
>>               </p>
>>                   <ul>
>>   <source>
>>      Log log =  
>> LogFactory.getLog("org.apache.<i>component</i>.enterprise");
>>   </source>
>>               </ul>
>>                   <p>
>>   This allows the 'enterprise' level information to be turned on/off  
>> explicitly
>>   by most logger implementations.
>>               </p>
>>           </subsection>
>>       </subsection>
>>           <subsection name='Enterprise - National Language Support -  
>> Internationalization'>
>>               <p>
>>   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.
>>                   </p>
>>               <p>
>>   NLS enabled components are particularly appreciated
>>   (thats an open-source-correct term for 'required by corporate  
>> end-users' :-)
>>   for <strong>tooling</strong> and <strong>middleware</strong>
 
>> components.
>>                   </p>
>>               <p>
>>   NLS internationalization SHOULD be strongly considered for used for
>>   <b>fatal</b>, <b>error</b>, <b>warn</b>, and
<b>info</b> messages.
>>   It is generally considered optional for <b>debug</b> and  
>> <b>trace</b> messages.
>>                   </p>
>>               <p>
>>   Perhaps more direct support for internationalizing log messages
>>   can be introduced in a future or alternate version of the  
>> <code>Log</code> interface.
>>                   </p>
>>       </subsection>
>>   </section>
>>       <section name='Integration'>
>>           <p>
>>   The minimum requirement to integrate with another logger
>>   is to provide an implementation of the
>>   <code>org.apache.commons.logging.Log</code> interface.
>>   In addition, an implementation of the
>>   <code>org.apache.commons.logging.LogFactory</code> interface
>>   can be provided to meet
>>   specific requirements for connecting to, or instantiating, a logger.
>>       </p>
>>           <subsection name='org.apache.commons.logging.Log'>
>>               <p>
>>   The default <code>LogFactory</code> provided by JCL
>>   can be configured to instantiate a specific implementation of the
>>   <code>org.apache.commons.logging.Log</code> interface
>>   by setting the property of the same name  
>> (<code>org.apache.commons.logging.Log</code>).
>>   This property can be specified as a system property,
>>   or in the <code>commons-logging.properties</code> file,
>>   which must exist in the CLASSPATH.
>>           </p>
>>       </subsection>
>>           <subsection name='Default logger if not plugged'>
>>               <p>
>>   The Jakarta Commons Logging SPI uses the
>>   implementation of the <code>org.apache.commons.logging.Log</code>
>>   interface specified by the system property
>>   <code>org.apache.commons.logging.Log</code>.
>>   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:
>>           </p>
>>               <ul>
>>                   <li>
>>   <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>
>>               </li>
>>                   <li>
>>   JDK 1.4
>>               </li>
>>                   <li>
>>   JCL SimpleLog
>>               </li>
>>           </ul>
>>       </subsection>
>>           <subsection name='org.apache.commons.logging.LogFactory'>
>>               <p>
>>   If desired, the default implementation of the
>>   <code>org.apache.commons.logging.LogFactory</code>
>>   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 <code>LogFactoryImpl.java</code>
>>   for details.
>>           </p>
>>       </subsection>
>>           <subsection name='Mechanism'>
>>               <subsection name='Life cycle'>
>>                   <p>
>>   The JCL LogFactory implementation must assume responsibility for
>>   either connecting/disconnecting to a logging toolkit,
>>   or instantiating/initializing/destroying a logging toolkit.
>>               </p>
>>           </subsection>
>>               <subsection name='Exception handling'>
>>                   <p>
>>   The JCL Log interface doesn't specify any exceptions to be handled,
>>   the implementation must catch any exceptions.
>>               </p>
>>           </subsection>
>>               <subsection name='Multiple threads'>
>>                   <p>
>>   The JCL Log and LogFactory implementations must ensure
>>   that any synchronization required by the logging toolkit
>>   is met.
>>               </p>
>>           </subsection>
>>       </subsection>
>>           <subsection name='Configuring the Logger Implementation'>
>>               <p>
>>   The Jakarta Commons Logging (JCL) SPI
>>   can be configured to use different logging toolkits.
>>           </p>
>>               <p>
>>   Configuration of the behavior of the JCL ultimately depends upon the
>>   logging toolkit being used.
>>   The JCL SPI uses
>>   <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>
>>   by default if it is available (in the CLASSPATH).
>>           </p>
>>               <subsection name='Log4J'>
>>                   <p>
>>   As
>>   <a href="http://jakarta.apache.org/log4j/docs/index.html">Log4J</a>
>>   is the default logger,
>>   a <i>few</i> details are presented herein to get the  
>> developer/integrator going.
>>               </p>
>>                   <p>
>>   Configure Log4J using system properties and/or a properties file:
>>               </p>
>>                   <ul>
>>                       <li>
>>   <strong>log4j.configuration=<em>log4j.properties</em></strong>
>>   Use this system property to specify the name of a Log4J  
>> configuration file.
>>   If not specified, the default configuration file is  
>> <i>log4j.properties</i>.
>>                   </li>
>>                       <li>
>>   <strong>log4j.rootCategory=<i>priority</i> [,  
>> <i>appender</i>]*</strong>
>>                   </li>
>>   Set the default (root) logger priority.
>>                       <li>
>>   <strong>log4j.logger.<i>logger.name</i>=<i>priority</i></strong>
>>   Set the priority for the named logger
>>   and all loggers hierarchically lower than, or below, the
>>   named logger.
>>   <i>logger.name</i> corresponds to the parameter of
>>   <code>LogFactory.getLog(<i>logger.name</i>)</code>,
>>   used to create the logger instance.  Priorities are:
>>   <code>DEBUG</code>,
>>   <code>INFO</code>,
>>   <code>WARN</code>,
>>   <code>ERROR</code>,
>>   or <code>FATAL</code>.
>>   <br/>
>>   Log4J understands hierarchical names,
>>   enabling control by package or high-level qualifiers:
>>   <code>log4j.logger.org.apache.component=DEBUG</code>
>>   will enable debug messages for all classes in both
>>   <code>org.apache.component</code>
>>   and
>>   <code>org.apache.component.sub</code>.
>>   Likewise, setting
>>   <code>log4j.logger.org.apache.component=DEBUG</code>
>>   will enable debug message for all 'component' classes,
>>   but not for other Jakarta projects.
>>                   </li>
>>                       <li>
>>    
>> <strong>log4j.appender.<i>appender</i>.Threshold=<i>priority</i></

>> strong>
>>                   </li>
>>   Log4J <i>appenders</i> correspond to different output devices:
>>   console, files, sockets, and others.
>>   If appender's <i>threshold</i>
>>   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).
>>               </ul>
>>           </subsection>
>>       </subsection>
>>   </section>
>>       <section name='Frequently Asked Questions'>
>>           <subsection name='Is JCL Thread Safe?'>
>>               <p>
>>   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.
>>           </p>
>>               <p>
>>   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.
>>           </p>
>>       </subsection>
>>   </section>
>>   </body>
>>   </document>
>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
>> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>


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