Return-Path: Delivered-To: apmail-jakarta-commons-dev-archive@www.apache.org Received: (qmail 45466 invoked from network); 15 Feb 2004 10:21:53 -0000 Received: from daedalus.apache.org (HELO mail.apache.org) (208.185.179.12) by minotaur-2.apache.org with SMTP; 15 Feb 2004 10:21:53 -0000 Received: (qmail 57138 invoked by uid 500); 15 Feb 2004 10:21:23 -0000 Delivered-To: apmail-jakarta-commons-dev-archive@jakarta.apache.org Received: (qmail 57088 invoked by uid 500); 15 Feb 2004 10:21:23 -0000 Mailing-List: contact commons-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Jakarta Commons Developers List" Reply-To: "Jakarta Commons Developers List" Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 57068 invoked from network); 15 Feb 2004 10:21:22 -0000 Received: from unknown (HELO smtp-out3.blueyonder.co.uk) (195.188.213.6) by daedalus.apache.org with SMTP; 15 Feb 2004 10:21:22 -0000 Received: from [10.0.0.2] ([82.38.65.173]) by smtp-out3.blueyonder.co.uk with Microsoft SMTPSVC(5.0.2195.5600); Sun, 15 Feb 2004 10:21:33 +0000 Mime-Version: 1.0 (Apple Message framework v612) In-Reply-To: References: <20040215093902.36607.qmail@minotaur.apache.org> Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed Message-Id: Content-Transfer-Encoding: 7bit From: robert burrell donkin Subject: Re: cvs commit: jakarta-commons/digester/xdocs guide.xml Date: Sun, 15 Feb 2004 10:21:30 +0000 To: "Jakarta Commons Developers List" X-Mailer: Apple Mail (2.612) X-OriginalArrivalTime: 15 Feb 2004 10:21:33.0525 (UTC) FILETIME=[7C351050:01C3F3AD] X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N 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 >> =================================================================== >> >> >> >> >> >> 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 >> (> href="http://jakarta.apache.org/commons/logging/api/org/apache/ >> commons/logging/impl/Log4JLogger.html">Log4JLogger). >>
    4. >>
  4. >> If the application is executing on a JDK 1.4 system, use >> the corresponding wrapper class >> (> href="http://jakarta.apache.org/commons/logging/api/org/apache/ >> commons/logging/impl/Jdk14Logger.html">Jdk14Logger). >>
    5. >>
  5. >> Fall back to the default simple logging wrapper >> (> href="http://jakarta.apache.org/commons/logging/api/org/apache/ >> commons/logging/impl/SimpleLog.html">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> strong> >>
    • >> 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. >>

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