Modified: logging/log4j/branches/v1_2-branch/src/site/apt/index.apt URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/apt/index.apt?view=diff&rev=537211&r1=537210&r2=537211 ============================================================================== --- logging/log4j/branches/v1_2-branch/src/site/apt/index.apt (original) +++ logging/log4j/branches/v1_2-branch/src/site/apt/index.apt Fri May 11 08:36:55 2007 @@ -1,135 +1,70 @@ +~~ Licensed to the Apache Software Foundation (ASF) under one or more +~~ contributor license agreements. See the NOTICE file distributed with +~~ this work for additional information regarding copyright ownership. +~~ The ASF licenses this file to You under the Apache License, Version 2.0 +~~ (the "License"); you may not use this file except in compliance with +~~ the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, software +~~ distributed under the License is distributed on an "AS IS" BASIS, +~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +~~ See the License for the specific language governing permissions and +~~ limitations under the License. ------ - What is Maven? + log4j 1.2 ------ - Jason van Zyl ------ - 12 October 2005 ------ -Introduction + Inserting log statements into your code is a low-tech method + for debugging it. It may also be the only way because + debuggers are not always available or applicable. This is + often the case for distributed applications. + + On the other hand, some people argue that log statements + pollute source code and decrease legibility. (We believe that + the contrary is true). In the Java language where a + preprocessor is not available, log statements increase the + size of the code and reduce its speed, even when logging is + turned off. Given that a reasonably sized application may + contain thousands of log statements, speed is of particular + importance. + + + With log4j it is possible to enable logging at runtime + without modifying the application binary. The log4j package is + designed so that these statements can remain in shipped code + without incurring a heavy performance cost. Logging behavior + can be controlled by editing a configuration file, without + touching the application binary. + + Logging equips the developer with detailed context for + application failures. On the other hand, testing provides + quality assurance and confidence in the application. Logging + and testing should not be confused. They are + complementary. When logging is wisely used, it can prove to be + an essential tool. + + One of the distinctive features of log4j is the notion of + inheritance in loggers. Using a logger + hierarchy it is possible to control which log + statements are output at arbitrarily fine granularity but also + great ease. This helps reduce the volume of logged output and + minimize the cost of logging. + + The target of the log output can be a file, an + OutputStream, a java.io.Writer, a + remote log4j server, a remote Unix Syslog daemon, or many other output targets. + + On an AMD Duron clocked at 800Mhz running JDK 1.3.1, it costs + about 5 nanoseconds to determine if a logging statement should + be logged or not. Actual logging is also quite fast, ranging + from 21 microseconds using the SimpleLayout, 37 + microseconds using the TTCCLayout. The performance of the + PatternLayout is almost as good as the dedicated layouts, + except that it is much more flexible. - Maven was originally started as an attempt to simplify the build - processes in the Jakarta Turbine project. There were several - projects each with their own Ant build files that were all slightly - different and JARs were checked into CVS. We wanted a standard way to - build the projects, a clear definition of what the project consisted - of, an easy way to publish project information and a way to share JARs - across several projects. - - The result is a tool that can now be used for building and managing - any Java-based project. We hope that we have created something that - will make the day-to-day work of Java developers easier and generally - help with the comprehension of any Java-based project. - -Maven's Objectives - - Maven's primary goal is to allow a developer to comprehend the - complete state of a development effort in the shortest period of - time. In order to attain this goal there are several areas of concern - that Maven attempts to deal with: - - * Making the build process easy - - * Providing a uniform build system - - * Providing quality project information - - * Providing guidelines for best practices development - - * Allowing transparent migration to new features - -* Making the build process easy - - While using Maven doesn't eliminate the need to know about the - underlying mechanisms, Maven does provide a lot of shielding - from the details. - -* Providing a uniform build system - - Maven allows a project to build using its project object model (POM) and - a set of plugins that are shared by all projects using - Maven, providing a uniform build system. Once you familiarize yourself - with how one Maven project builds you automatically know how all Maven - projects build saving you immense amounts of time when trying to - navigate many projects. - -* Providing quality project information - - Maven provides plenty of useful project information that is in - part taken from your POM and in part generated from your project's - sources. For example, Maven can provide: - - * Change log document created directly from source control - - * Cross referenced sources - - * Mailing lists - - * Dependency list - - * Unit test reports including coverage - - [] - - As Maven improves the information set provided will improve, all of - which will be transparent to users of Maven. - - Other products can also provide Maven plugins to allow their set of - project information alongside some of the standard information given by - Maven, all still based on the POM. - -* Providing guidelines for best practices development - - Maven aims to gather current principles for best practices development, and - make it easy to guide a project in that direction. - - For example, specification, execution, and reporting of unit tests are part of - the normal build cycle using Maven. - Current unit testing best practices were used as guidelines: - - * Keeping your test source code in a separate, but parallel source tree - - * Using test case naming conventions to locate and execute tests - - * Have test cases setup their environment and don't rely on customizing the build for test preparation. - - [] - - Maven also aims to assist in project workflow such as release management and - issue tracking. - - Maven also suggests some guidelines on how to layout your project's directory structure - so that once you learn the layout you can easily navigate any other project that uses - Maven and the same defaults. - -* Allowing transparent migration to new features - - Maven provides an easy way for Maven clients to update their installations - so that they can take advantage of any changes that been made to - Maven itself. - - Installation of new or updated plugins from third parties or Maven itself has - been made trivial for this reason. - -What is Maven Not? - - You may have heard some of the following things about Maven: - - * Maven is a site and documentation tool - - * Maven extends Ant to let you download dependencies - - * Maven is a set of reusable Ant scriptlets - - [] - - While Maven does these things, as you can read above in the "What is Maven?" section, - these are not the only features Maven has, and its objectives are quite different. - - Maven does encourage best practices, but we realise that some projects may not fit with - these ideals for historical reasons. While Maven is designed to be flexible, to an extent, in these - situations and to the needs of different projects, it can not cater to every situation without making - compromises to the integrity of its objectives. - - If you decide to use Maven, and have an unusual build structure that you cannot reorganise, you may - have to forgo some features or the use of Maven altogether. + The package is being constantly improved thanks to input from + users and code contributed by authors in the community.
Copied: logging/log4j/branches/v1_2-branch/src/site/apt/publications.apt (from r535385, logging/log4j/branches/v1_2-branch/src/site/apt/books.apt) URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/apt/publications.apt?view=diff&rev=537211&p1=logging/log4j/branches/v1_2-branch/src/site/apt/books.apt&r1=535385&p2=logging/log4j/branches/v1_2-branch/src/site/apt/publications.apt&r2=537211 ============================================================================== --- logging/log4j/branches/v1_2-branch/src/site/apt/books.apt (original) +++ logging/log4j/branches/v1_2-branch/src/site/apt/publications.apt Fri May 11 08:36:55 2007 @@ -1,61 +1,83 @@ +~~ Licensed to the Apache Software Foundation (ASF) under one or more +~~ contributor license agreements. See the NOTICE file distributed with +~~ this work for additional information regarding copyright ownership. +~~ The ASF licenses this file to You under the Apache License, Version 2.0 +~~ (the "License"); you may not use this file except in compliance with +~~ the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, software +~~ distributed under the License is distributed on an "AS IS" BASIS, +~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +~~ See the License for the specific language governing permissions and +~~ limitations under the License. ------ - Maven Features + log4j 1.2 Publications ------ - Jason van Zyl + Curt Arnold ------ - 12 October 2005 + 8 May 2007 ------ -Feature Summary - The following are the key features of Maven in a nutshell: +Books - * Simple project setup that follows best practices - get a new project or module started in seconds - - * Consistent usage across all projects means no ramp up time for new developers coming onto a project - - * Superior dependency management including automatic updating, dependency closures (also known as transitive dependencies) - - * Able to easily work with multiple projects at the same time - - * A large and growing repository of libraries and metadata to use out of the box, and arrangements in place with the largest Open Source projects for - real-time availability of their latest releases - - * Extensible, with the ability to easily write plugins in Java or scripting languages - - * Instant access to new features with little or no extra configuration - - * Ant tasks for dependency management and deployment outside of Maven - - * Model based builds: - Maven is able to build any number of projects into predefined output types - such as a JAR, WAR, or distribution based on metadata about the project, without - the need to do any scripting in most cases. - - * Coherent site of project information: - Using the same metadata as for the build process, Maven is able to generate a - web site or PDF including any documentation you care to add, and adds to that - standard reports about the state of development of the project. - Examples of this information can be seen at the bottom of the left-hand navigation of - this site under the "Project Information" and "Project Reports" submenus. - - * Release management and distribution publication: - Without much additional configuration, Maven will integrate with your source control - system such as CVS and manage the release of a project based on a certain tag. - It can also publish this to a distribution location for use by other projects. - Maven is able to publish individual outputs such as a JAR, an archive including other - dependencies and documentation, or as a source distribution. - - * Dependency management: - Maven encourages the use of a central repository of JARs and other dependencies. Maven - comes with a mechanism that your project's clients can use to - download any JARs required for building your project from a - central JAR repository much like Perl's CPAN. This allows users - of Maven to reuse JARs across projects and encourages communication - between projects to ensure that backward compatibility issues are - dealt with. We are collaborating with the folks at {{{http://www.ibiblio.org}Ibiblio}} who have graciously - allowed the central repository to live on their servers. + * Ceki G\xFClc\xFC. 2004. The complete log4j manual. QoS.ch. {{{http://www.qos.ch/shop/products/eclm/}http://www.qos.ch/shop/products/eclm/}}. + + * Samudra Gupta. 2007. Pro Apache log4j, Second Edition. APress. + +Articles: + + * Vipan Singla. Don't Use System.out.println! Use Log4j. + {{{http://www.vipan.com/htdocs/log4jhelp.html}http://www.vipan.com/htdocs/log4jhelp.html}}. + + * Vikran Goyal. Build Flexible Logs With log4j. + {{{http://www.onjava.com/pub/a/onjava/2002/08/07/log4j.html}http://www.onjava.com/pub/a/onjava/2002/08/07/log4j.html}}. + + * Ashley J.S. Mills. Log4J. + {{{http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/log4j/log4j.html}http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/log4j/log4j.html}}. + + * Kevin Brown. Add logging to your Java Applications. + {{{http://www.builder.com.com/article.jhtml?id=u00820020124kev01.htm} + http://www.builder.com.com/article.jhtml?id=u00820020124kev01.htm}} + + * Kevin Brown. How does the Java logging API stack up against log4j? + {{{http://www.builder.com.com/article.jhtml?id=u00220020724kev01.htm} + http://www.builder.com.com/article.jhtml?id=u00220020724kev01.htm}}. + + * Michael Canzoneri. Log4J FAQ. {{{http://www.jguru.com/faq/Log4j}http://www.jguru.com/faq/Log4j}}. + + * Ceki G\xFClc\xFC. Think Again. + {{{http://www.qos.ch/logging/thinkAgain.html}http://www.qos.ch/logging/thinkAgain.html}}. + + * Ceki G\xFClc\xFC. Supporting the log4j RepositorySelector. + {{{http://www.qos.ch/logging/sc.html}http://www.qos.ch/logging/sc.html}}. + + * Ceki G\xFClc\xFC. Log4j delivers control over logging. + {{{http://www.javaworld.com/jw-11-2000/jw-1122-log4j.html}http://www.javaworld.com/jw-11-2000/jw-1122-log4j.html}}. + + * Vikram Goyal. Understanding Classloaders: log4j in a J2EE Environment. + {{{http://www.onjava.com/pub/a/onjava/2003/04/02/log4j_ejb.html}http://www.onjava.com/pub/a/onjava/2003/04/02/log4j_ejb.html}}. + + * Ruth Zamorano and Rafeal Luque. Instant logging: Harness the power of log4j with Jabber. + {{{http://www-106.ibm.com/developerworks/java/library/j-instlog/}http://www-106.ibm.com/developerworks/java/library/j-instlog/}}. + + * Matthew Litkey, Jay Galvin, and Marina Sum. + Developer Tip: Adding the log4j API to Applications on Sun Java System Application Server 7 + {{{http://developers.sun.com/prodtech/appserver/reference/techart/log4j.html}http://developers.sun.com/prodtech/appserver/reference/techart/log4j.html}}. + + * Sean C. Sullivan. Reporting Application Errors by Email. + {{{http://www.onjava.com/pub/a/onjava/2004/09/29/smtp-logging.html}http://www.onjava.com/pub/a/onjava/2004/09/29/smtp-logging.html}}. + + +Presentations: - [] + * John Munsch. Log4J In 30 Minutes Or Less. + {{{http://www.johnmunsch.com/projects/Presentations/}http://www.johnmunsch.com/projects/Presentations/}}. -~~ this needs to be greatly expanded and is too detailed here ... jvz + * Ceki G\xFClc\xFC. Log4j, a logging package for the Java language. + {{{http://www.qos.ch/ac2001/F11-10.html}http://www.qos.ch/ac2001/F11-10.html}}. + + * Brent Twenter. Log4j. {{{http://www.ociweb.com/javasig/knowledgebase/January2001/Log4J.ppt}http://www.ociweb.com/javasig/knowledgebase/January2001/Log4J.ppt}}. + \ No newline at end of file Modified: logging/log4j/branches/v1_2-branch/src/site/apt/roadmap.apt URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/apt/roadmap.apt?view=diff&rev=537211&r1=537210&r2=537211 ============================================================================== --- logging/log4j/branches/v1_2-branch/src/site/apt/roadmap.apt (original) +++ logging/log4j/branches/v1_2-branch/src/site/apt/roadmap.apt Fri May 11 08:36:55 2007 @@ -1,61 +1,28 @@ +~~ Licensed to the Apache Software Foundation (ASF) under one or more +~~ contributor license agreements. See the NOTICE file distributed with +~~ this work for additional information regarding copyright ownership. +~~ The ASF licenses this file to You under the Apache License, Version 2.0 +~~ (the "License"); you may not use this file except in compliance with +~~ the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, software +~~ distributed under the License is distributed on an "AS IS" BASIS, +~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +~~ See the License for the specific language governing permissions and +~~ limitations under the License. ------ - Maven Features + log4j 1.2 Roadmap ------ - Jason van Zyl + Curt Arnold ------ - 12 October 2005 + 8 May 2007 ------ -Feature Summary +log4j 1.2 Roadmap - The following are the key features of Maven in a nutshell: - - * Simple project setup that follows best practices - get a new project or module started in seconds - - * Consistent usage across all projects means no ramp up time for new developers coming onto a project - - * Superior dependency management including automatic updating, dependency closures (also known as transitive dependencies) - - * Able to easily work with multiple projects at the same time - - * A large and growing repository of libraries and metadata to use out of the box, and arrangements in place with the largest Open Source projects for - real-time availability of their latest releases - - * Extensible, with the ability to easily write plugins in Java or scripting languages - - * Instant access to new features with little or no extra configuration - - * Ant tasks for dependency management and deployment outside of Maven - - * Model based builds: - Maven is able to build any number of projects into predefined output types - such as a JAR, WAR, or distribution based on metadata about the project, without - the need to do any scripting in most cases. - - * Coherent site of project information: - Using the same metadata as for the build process, Maven is able to generate a - web site or PDF including any documentation you care to add, and adds to that - standard reports about the state of development of the project. - Examples of this information can be seen at the bottom of the left-hand navigation of - this site under the "Project Information" and "Project Reports" submenus. - - * Release management and distribution publication: - Without much additional configuration, Maven will integrate with your source control - system such as CVS and manage the release of a project based on a certain tag. - It can also publish this to a distribution location for use by other projects. - Maven is able to publish individual outputs such as a JAR, an archive including other - dependencies and documentation, or as a source distribution. - - * Dependency management: - Maven encourages the use of a central repository of JARs and other dependencies. Maven - comes with a mechanism that your project's clients can use to - download any JARs required for building your project from a - central JAR repository much like Perl's CPAN. This allows users - of Maven to reuse JARs across projects and encourages communication - between projects to ensure that backward compatibility issues are - dealt with. We are collaborating with the folks at {{{http://www.ibiblio.org}Ibiblio}} who have graciously - allowed the central repository to live on their servers. - - [] - -~~ this needs to be greatly expanded and is too detailed here ... jvz + log4j 1.2 is mature and future development on the log4j 1.2 branch + is expected to be limited to bug fixes and minor enhancements. + Any major new features for log4j 1.2 are likely to be developed + as companion products for log4j 1.2. Modified: logging/log4j/branches/v1_2-branch/src/site/fml/faq.fml URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/fml/faq.fml?view=diff&rev=537211&r1=537210&r2=537211 ============================================================================== --- logging/log4j/branches/v1_2-branch/src/site/fml/faq.fml (original) +++ logging/log4j/branches/v1_2-branch/src/site/fml/faq.fml Fri May 11 08:36:55 2007 @@ -18,20 +18,764 @@ --> <faqs title="Frequently Asked Technical Questions"> <part id="faq"> - <faq id="scope-provided"> - <question>How do I prevent including JARs in WEB-INF/lib? I need a "compile only" scope!</question> + + <faq id="1.1"> + <question>What is log4j?</question> + <answer> <p>log4j is a tool to help the programmer output log statements to a + variety of output targets. + </p> + + <p>In case of problems with an application, it is helpful to + enable logging so that the problem can be located. With log4j + it is possible to enable logging at runtime without modifying + the application binary. The log4j package is designed so that + log statements can remain in <i>shipped</i> code without + incurring a high performance cost. It follows that the speed + of logging (or rather not logging) is capital. + </p> + + <p>At the same time, log output can be so voluminous that it quickly + becomes overwhelming. One of the distinctive features of log4j is the + notion of <i>hierarchical loggers</i>. Using loggers it is + possible to selectively control which log statements are output at + arbitrary granularity. + </p> + + <p>log4j is designed with two three goals in mind: + reliability, speed and flexibility. There is a tight balance + between these requirements. We believe that log4j strikes the + right balance. + </p> +</answer> + </faq> + + + <faq id="1.2"><question>Is log4j a reliable logging system?</question> + <answer><p>No. log4j is not reliable. It is a best-effort + <em>fail-stop</em> logging system. + </p> + + <p>By fail-stop, we mean that log4j will not throw unexpected + exceptions at run-time potentially causing your application to + crash. <b>If for any reason, log4j throws an uncaught exception, + please send an email to the <a href="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</a> + mailing list</b>. Uncaught exceptions are handled as serious bugs + requiring immediate attention. + </p> + + <p>Moreover, log4j will not revert to System.out or System.err + when its designated output stream is not opened, is not writable or + becomes full. This avoids corrupting an otherwise working program by + flooding the user's terminal because logging fails. However, log4j + will output a single message to System.err indicating that logging can + not be performed. + </p></answer></faq> + + <faq id="1.3"><question>What are the prerequisites for log4j?</question> <answer> + <p>Log4j versions upto and including 1.2.8 are + compatible with JDK 1.1.x and later. Log4j version 1.3 will + be compatilble with JDK 1.2 and later. + </p> + + <p>The DOMConfigurator is based on the DOM Level 1 + API. The DOMConfigurator.configure(Element) method will work + with any XML parser that will pass it a DOM tree. + </p> + <p>The DOMConfigurator.configure(String filename) method and its + variants require a JAXP compatible XML parser, for example <a href="http://xml.apache.org/";>Xerces</a> or Sun's + parser. Compiling the DOMConfigurator requires the presence of a + JAXP parser in the classpath. + </p> + + <p>The <code>org.apache.log4j.net.SMTPAppender</code> + relies on the <a href="http://java.sun.com/products/javamail/";>JavaMail + API</a>. It has been tested with JavaMail API version + 1.2. The JavaMail API requires the <a href="http://java.sun.com/beans/glasgow/jaf.html";>JavaBeans + Activation Framework</a> package. + </p> + + <p>The <code>org.apache.log4j.net.JMSAppender</code> + requires the presence of the JMS API as well as JNDI. + </p> + + <p>log4j test code relies on the <a href="http://www.junit.org";>JUnit</a> testing framework. + </p> + </answer></faq> + + <faq id="1.4"><question>What are the features of log4j?</question> + <answer> + <p>log4j is optimized for speed.</p> + + <p>log4j is based on a named logger hierarchy.</p> + + <p>log4j is fail-stop. However, altough it certainly + strives to ensure delivery, log4j does not guarantee that + each log statement will be delivered to its destination. + </p> + + <p>log4j is thread-safe.</p> + + <p>log4j is not restricted to a predefined set of + facilities.</p> + + <p>Logging behavior can be set at runtime using a + configuration file. Configuration files can be property + files or in XML format. </p> + + <p>log4j is designed to handle Java Exceptions from the + start.</p> + + <p>log4j can direct its output to a file, the console, + an <code>java.io.OutputStream</code>, + <code>java.io.Writer</code>, a remote server using TCP, a + remote Unix Syslog daemon, to a remote listener using JMS, + to the NT EventLog or even send e-mail. </p> + + <p>log4j uses 5 levels, namely DEBUG, INFO, WARN, ERROR and + FATAL. + </p> + + <p>The format of the log output can be easily changed by + extending the <code>Layout</code> + class. </p> + + <p>The target of the log output as well as the writing + strategy can be altered by implementations of the + <code>Appender</code> interface. </p> + + <p>log4j supports multiple output appenders per logger. + </p> + + <p>log4j supports internationalization.</p> + </answer></faq> + + <faq id="1.5"><question>Is there example code for using log4j?</question> + <answer> + <p>See the <code>examples/</code> directory.</p> + </answer> + </faq> + + <faq id="1.6"> + <question>What documentation should I read to learn more about + log4j?</question> + <answer><p>Make sure to read the <a href="manual.html">short + manual</a>. It is also recommended to you read <a href="https://www.qos.ch/shop/products/log4j/log4j-Manual.jsp";>The complete + log4j manual</a> which is much more detailed and up to + date. Both documents were written by Ceki Gülcü. + </p></answer> + </faq> + + <faq id="1.7"><question>Is log4j thread-safe?</question> + <answer> + <p>Yes, log4j is thread-safe. Log4j components are designed to + be used in heavily multithreaded systems.</p> + + </answer></faq> + + <faq id="1.8"><question>What does log output look like?</question> + <answer> + <p>The log output can be customized in many ways. Moreover, + one can completely override the output format by implementing + one's own Layout. + </p> + + <p>Here is an example output using <em>PatternLayout</em> with + the conversion pattern <b>"%r [%t] %-5p %c{2} %x - %m%n"</b> + </p> + + <pre class="screen_output"> +176 [main] INFO examples.Sort - Populating an array of 2 elements in reverse order. +225 [main] INFO examples.SortAlgo - Entered the sort method. +262 [main] DEBUG SortAlgo.OUTER i=1 - Outer loop. +276 [main] DEBUG SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0 +290 [main] DEBUG SortAlgo.OUTER i=0 - Outer loop. +304 [main] INFO SortAlgo.DUMP - Dump of interger array: +317 [main] INFO SortAlgo.DUMP - Element [0] = 0 +331 [main] INFO SortAlgo.DUMP - Element [1] = 1 +343 [main] INFO examples.Sort - The next log statement should be an error message. +346 [main] ERROR SortAlgo.DUMP - Tried to dump an uninitialized array. + at org.log4j.examples.SortAlgo.dump(SortAlgo.java:58) + at org.log4j.examples.Sort.main(Sort.java:64) +467 [main] INFO examples.Sort - Exiting main method. + </pre> + + <p>The first field is the number of milliseconds elapsed since + the start of the program. The second field is the thread + outputting the log statement. The third field is the level of + the log statement. The fourth field is the rightmost two + components of the logger making the log request. The fifth + field (just before the '-') is the <em>nested diagnostic + context</em> (NDC). Note the nested diagnostic context may be + empty as in the first two statements. The text after the '-' + is the message of the statement. + </p> + </answer></faq> + + <faq id="1.9"><question>Why should I use log4j when JDK 1.4 already ships with a + logging API?</question> + <answer> + <p> - The scope you should use for this is - <code>provided</code>. This indicates to Maven that the dependency will be - provided at run time by its container or the JDK, for example. + Although both APIs are conceptually similar, the log4j API is + significantly more flexible and offers many more features, too + numerous to be listed here. You will discover that the + additional features and flexibility turn out to be + indispensable in the context of a mission-critical + application. + </p> + + <p>The open and collaborative way in which log4j is developped + ensures that it continues to preserve and even widen its + competitive edge. At some point, input from bright developers + from all over the world is bound to make a difference. </p> + </answer> + </faq> + + + <faq id="2.1"><question>What are <em>Loggers</em>?</question> + <answer> + + <p>Lggers lie at the heart of log4j. Loggers define a hierarchy and give + the programmer <em>run-time</em> control on which statements are + printed or not. + </p> + + <p>Loggers are assigned levels. A log statement is printed + depending on its level <em>and</em> its logger. + </p> + + <p>Make sure to read the <a href="manual.html">log4j manual</a> + for more information. + </p> + </answer></faq> + +<faq id="2.2"><question>How can I change log behavior at runtime?</question> + <answer> + <p>Log behavior can be set using configuration files which are parsed + at runtime. Using configuration files the programmer can define + loggers and set their levels. + </p> + + <p>The <code>PropertyConfigurator</code> defines a particular format + of a configuration file. See also the <code>examples/Sort.java</code> + example and associated configuration files. + </p> + + <p>Configuration files can be specified in XML. See + <code>log4j.dtd</code> and + <code>org.log4j.xml.DOMConfigurator</code> for more details. + </p> + + <p>See the various Layout and Appender components for specific + configuration options. + </p> + + <p>In addition to configuration files, the user may disable all + messages belonging to a set of levels. See next item. + </p> + + </answer></faq> + + <faq id="2.3"><question>What is the fastest way of (not) logging?</question> + <answer> + <p> For some logger <code>l</code>, writing, + </p> + + <pre class="source"> + l.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); + </pre> + + <p>incurs the cost of constructing the message parameter, that is + converting both integer <code>i</code> and <code>entry[i]</code> to a + String, and concatenating intermediate strings. This, regardless of + whether the message will be logged or not. + </p> + + <p>If you are worried about speed, then write</p> + <pre class="source"> + if(l.isDebugEnabled()) { + l.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); + } + </pre> + + <p>This way you will not incur the cost of parameter + construction if debugging is disabled for logger + <code>l</code>. On the other hand, if the logger is debug + enabled, you will incur the cost of evaluating whether the + logger is enabled or not, twice: once in + <code>debugEnabled</code> and once in <code>debug</code>. + This is an insignificant overhead since evaluating a logger + takes less than 1% of the time it takes to actually log a + statement. + </p> +</answer></faq> + + <faq id="2.4"><question>Are there any suggested ways for naming loggers?</question> + <answer> + <p>Yes, there are.</p> + + <p>You can name loggers by <strong>locality</strong>. It turns out + that instantiating a logger in each class, with the logger name + equal to the fully-qualified name of the class, is a useful and + straightforward approach of defining loggers. This approach has + many benefits: + </p> + + <ul> + <li>It is very simple to implement.</li> + + <li>It is very simple to explain to new developers.</li> + + <li>It automatically mirrors your application's own modular design. + </li> + <li>It can be further refined at will.</li> + + <li>Printing the logger automatically gives information on the locality + of the log statement. </li> + </ul> + + <p>However, this is not the only way for naming loggers. A + common alternative is to name loggers by <strong>functional + areas</strong>. For example, the "database" logger, "RMI" + logger, "security" logger, or the "XML" logger. + </p> + + <p>You may choose to name loggers by functionality and + subcategorize by locality, as in "DATABASE.com.foo.some.package.someClass" or + "DATABASE.com.foo.some.other.package.someOtherClass". + </p> + + <p><em>You are totally free in choosing the names of your + loggers.</em> The log4j package merely allows you to manage your + names in a hierarchy. However, it is your responsibility to define + this hierarchy. + </p> + + <p>Note by naming loggers by locality one tends to name things by + functionality, since in most cases the locality relates closely to + functionality. + </p> + </answer></faq> + + <faq id="2.5"><question>How do I get the fully-qualified name of a class in a static block?</question> + <answer> + <p>You can easily retrieve the fully-qualified name of a class in a + static block for class X, with the statement + <code>X.class.getName()</code>. Note that <code>X</code> is the class + name and not an instance. The <code>X.class</code> statement does + <i>not</i> create a new instance of class <code>X</code>. + </p> + + <p>Here is the suggested usage template:</p> + + <pre class="source"> +package a.b.c; + +public class Foo { + final static Logger logger = Logger.getLogger(Foo.class); + ... other code + +} + </pre> + </answer></faq> + + <faq id="2.6"><question>Can the log output format be customized? </question> + <answer> + <p>Yes, you can extend the <code>Layout</code> class to create + you own customized log format. Appenders can be parameterized + to use the layout of your choice. + </p> +</answer></faq> + + <faq id="2.7"><question>What are the configurable options for <code>FooBarAppender</code>?</question> + <answer> + <p>Log4j uses JavaBeans style configuration.</p> + + <p>Thus, any setter method in <code>FooBarAppender</code> + corresponds to a configurable option. For example, in <a href="apidocs\org\apache\log4j\RollingFileAppender.html"><code>RollingFileAppender</code></a> + the <a href="apidocs/org/apache/log4j/RollingFileAppender.html#setMaxBackupIndex(int)"><code>setMaxBackupIndex(int + maxBackups)</code></a> method corresponds to the + <code>maxBackupIndex</code> option. The first letter of the + option can be upper case, i.e. <code>MaxBackupIndex</code> + and <code>maxBackupIndex</code> are equivalent but not + <code>MAXBACKUPIndex</code> nor <code>mAXBackupIndex</code>. + </p> + + <p>Layouts options are also defined by their setter methods. The same goes + for most other log4j components. + </p> + </answer></faq> + + <faq id="2.8"><question>What is the recommended way of migrating from + java.util.logging to log4j?</question> + <answer> + + <p>We suggest to just use global file search/replace. You should be able + to replace all the "java.util.Logger" references with + "org.apache.log4j.Logger", and you should be on your way. + </p> + + <p>If you're on a Win32 platform, we recommend <a href="http://www.textpad.com/";>Textpad</a>. You can use the + CTRL+SHIFT+O to open all *.java files from a directory including all + its sub-directories, and then use the search/replace function to + replace in all files, and then CTRL+SHIFT+S to save all. Should take + about 60 seconds! :) + </p> + </answer></faq> + + <faq id="2.9"><question>Is it possible to direct log output to + different appenders by level? </question><answer> + <p>Yes it is. Setting the <b>Threshold</b> option of any appender + extending <a href="api/org/apache/log4j/AppenderSkeleton.html">AppenderSkeleton</a>, + (most log4j appenders extend AppenderSkeleton) to filter out all log + events with <em>lower</em> level than the value of the threshold + option. + </p> + + <p>For example, setting the threshold of an appender to DEBUG + also allow INFO, WARN, ERROR and FATAL messages to log along + with DEBUG messages. This is usually acceptable as there is + little use for DEBUG messages without the surrounding INFO, + WARN, ERROR and FATAL messages. Similarly, setting the + threshold of an appender to ERROR will filter out DEBUG, INFO + and WARN messages but not ERROR or FATAL messages. + </p> + + <p>This policy usually best encapsulates what the user + actually wants to do, as opposed to her mind-projected + solution. + </p> + <p>See <i>examples/sort4.lcf</i> for an example threshold + configuration.</p> + + <p>If you must filter events by exact level match, then you can + attach a <a href="apidocs/org/apache/log4j/varia/LevelMatchFilter.html">LevelMatchFilter</a> + to any appender to filter out logging events by exact level match. + </p> + </answer></faq> + + + <faq id="2.10"><question>What does the Windows NT Event Viewer complain about + missing descriptions for my event messages when I use the + <code>NTEventLogAppender</code>?</question> + + <answer> + <p>The NT Event Viewer relies on <i>message resource</i> DLLs + to properly view an event message. The NTEventLogAppender.dll + contains these message resources, but that DLL must be copied + to %SYSTEMROOT%\SYSTEM32 for it to work properly. + </p> + </answer></faq> + + <faq id="2.11"><question>Why can't I map my logger names to the loggers that + appear in the NT Event Log when I use the + NTEventLogAppender?</question> + + <answer> + <p>Unfotunately, the logger names are hardcoded within the + message resource DLL (see previous question about + NTEventLogAppender), so there isn't any easy way to override + those dynamically... in fact, I don't think it's possible to + do it, as you'd have to modify the DLL resources for every + application. Since most native applications don't use the + Logger column anyway... + </p> + </answer></faq> + + <faq id="2.12"><question>Are there suggested approaches for logging in JSP pages?</question> + <answer> <p> - Dependencies with this scope will not be passed on transitively, nor will they be bundled in an package such - as a WAR, or included in the runtime classpath. + The suggested approach depends on your design requirements. If you or + your organization has no constraints on the use of Java in JSP pages, + simply use log4j normally in <code><% ... %></code> statements + as indicated in the Short Manual and the rest of the documentation. </p> - </answer> + <p> + However, if your design calls for a minimum amount of Java in your JSP + pages, consider using the + <a href="http://jakarta.apache.org/taglibs/doc/log-doc/intro.html";>Log Taglib</a> + from the Jakarta Taglibs project. It provides logging JSP tags that invoke + log4j. + </p> + </answer> </faq> + <faq id="3.1"><question>Can the outputs of multiple client request go to + different log files?</question> + <answer> + <p>Many developers are confronted with the problem of + distinguishing the log output originating from the same class + but different client requests. They come up with ingenious + mechanisms to fan out the log output to different files. In + most cases, this is not the right approach. + </p> + + <p>It is simpler to use a nested diagnostic context + (NDC). Typically, one would <em>NDC.push()</em> client + specific information, such as the client's hostname, ID or any + other distinguishing information when starting to handle the + client's request. Thereafter, log output will automatically + include the nested diagnostic context so that you can + distinguish logs from different client requests even if they + are output to the same file. + </p> + + <p>See the <code>NDC</code> and the <code>PatternLayout</code> + classes for more information. The <code>NumberCruncher</code> + example shows how the NDC can be used to distinguish the log + output from multiple clients even if they share the same log + file. + </p> + + <p>For select applications, such as virtual hosting + web-servers, the NDC solution is not sufficient. As of version + 0.9.0, log4j supports multiple hierarchy trees. Thus, it is + possible to log to different targets from the same logger + depending on the current context. + </p> + </answer></faq> + + + <faq id="3.2"><question>Logger instances seem to be create only. Why isn't + there a method to remove logger instances?</question> + <answer> + <p>It is quite nontrivial to define the semantics of a + "removed" logger escecially if it is still referenced by the + user. Future releases <em>may</em> include a remove method in + the Logger class.</p></answer></faq> + + <faq id="3.3"><question>How do I get multiple process to log to the same file?</question> + <answer> + <p>You may have each process log to a + <a href="apidocs/org/apache/log4j/net/SocketAppender.html"><code>SocketAppender</code></a>. + The receiving + <a href="apidocs/org/apache/log4j/net/SocketServer.html"><code>SocketServer</code></a> + (or + <a href="apidocs/org/apache/log4j/net/SimpleSocketServer.html"><code>SimpleSocketServer</code></a>) + can receive all the events and send them to a single + log file. + </p> + </answer></faq> + + <faq id="3.4"><question>How about the timesamps of events generated by multiple + processes across multiple hosts (possibly across multiple + timezones)?</question> + <answer> + <p>The timestamp is created when the logging event is created. + That is so say, when the <code>debug</code>, + <code>info</code>, <code>warn</code>, <code>error</code> or + <code>fatal</code> method is invoked. Thus, the timestamp is + unaffected by the time at which event arrive at a remote + socket server. + </p> + + <p>Timestamps are stored in UTC format inside the + event. Consequently, when displayed or written to a log file, + timestamps appear in the same timezone as the host displaying + or creating the logfile. Note that because the clocks of + various machines may not be synchronized, there may be + timestamp inconsistencies between events generated on + different hosts. + </p> + </answer></faq> + + <faq id="3.5"><question>Why can't log4j find my properties file in a J2EE or WAR + application?</question><answer> + <p>The short answer: the log4j classes and the properties file + are not within the scope of the same classloader. + </p> + + <p>The long answer (and what to do about it): J2EE or Servlet + containers utilize Java's class loading system. Sun changed + the way classloading works with the release of Java 2. In + Java 2, classloaders are arranged in a hierarchial + parent-child relationship. When a child classloader needs to + find a class or a resource, it first delegates the request to + the parent. + </p> + + <p>Log4j only uses the default <code>Class.forName()</code> + mechanism for loading classes. Resources are handled + similarly. See the documentation for + <code>java.lang.ClassLoader</code> for more details. + </p> + + <p>So, if you're having problems, try loading the class or + resource yourself. If you can't find it, neither will + log4j. ;) + </p></answer></faq> + + + <faq id="3.6"><question>Is there a way to get log4j to automatically reload a + configuration file if it changes?</question><answer> + + <p>Yes. Both the DOMConfigurator and the PropertyConfigurator support + automatic reloading through the <code>configureAndWatch</code> method. + See the API documentation for more details. + </p> + + + <p>Because the <code>configureAndWatch</code> launches a + separate wathdog thread, and because there is no way to stop + this thread in log4j 1.2, the <code>configureAndWatch</code> + method is unsafe for use in J2EE envrironments where + applications are recycled. + </p></answer></faq> + + + <faq id="4.1"><question>Why should I donate my extensions to log4j back to the + project?</question><answer> + <p>Contrary to the GNU Public License (GPL) the Apache + Software License does not make any claims over your + extensions. By extensions, we mean totally new code that + invokes existing log4j classes. <em>You are free to do + whatever you wish with your proprietary log4j extensions.</em> + In particular, you may choose to never release your extensions + to the wider public. + </p> + + <p>We are very careful not to change the log4j client API so + that newer log4j releases are backward compatible with + previous versions. We are a lot less scrupulous with the + internal log4j API. Thus, if your extension is designed to + work with log4j version <code>n</code>, then when log4j + release version <code>n+1</code> comes out, you will probably + need to adapt your proprietary extensions to the new release. + </p> + + <p>Thus, you will be forced to spend precious resources in + order to keep up with log4j changes. This is commonly referred + to as the "stupid-tax." By donating the code and making it + part of the standard distribution, you save yourself the + unnecessary maintenance work. + </p> + + <p>If your extensions are useful then someone will eventually + write an extension providing the same or very similar + functionality. Your development effort will be wasted. Unless + the proprietary log4j extension is business critical, there is + little reason for not donating your extensions back to the + project. + </p></answer></faq> + + <faq id="4.2"><question>What should I keep in mind when contributing code?</question> + <answer> + <ol> + + <li> + <p>Write a test case for your contribution.</p> + + <p>There is nothing more irritating than finding the bugs + in debugging (i.e. logging) code. Writing a test case + takes some effort but is crucial for a widely used library + such as log4j. Writing a test case will go a long way in + earning you the respect of fellow developers. See the + tests/ directory for exiting test cases. + </p> + </li> + + + <li> + <p>Stick to the existing indentation style even if you hate it.</p> + + <p>Alternating between indentation styles makes it hard to + understand the source code. Make it a little harder on + yourself but easier on others. + </p> + + <p>Log4j has adopted a rather conservative approach by + following the <a href="http://java.sun.com/docs/codeconv/";>Code Conventions + for the JavaTM Programming Language</a>. <b>We use 2 (two) + spaces for indentation and no tabs.</b> + </p> + </li> + + <li> + <p>Please do not both modify the code and change the + indentation in a single commit.</p> + + <p>If you change the code and reformat it at the same time + and then commit, the commit notification message will be + hard to read. It will contain many diffs associated with + the reformatting in addition to logical changes. + </p> + + <p>If you must reformat and change the code, then perform + each step separately. For example, reformat the code and + commit. Following that, you can change the logic and + commit. The two steps can be performed in the reverse + order just as well. You can first change the logic and + commit and only later reformat and commit. + </p> + + </li> + <li> + <p>Make every effort to stick to the JDK 1.1 API.</p> + + <p>One of the important advantages of log4j is its + compatibility with JDK 1.1.x. + </p> + </li> + + <li> + <p>Always keep it simple, small and fast when + possible.</p> + + <p>It's all about the application not about logging.</p> + </li> + + <li> + <p>Identify yourself as a contributor at the top of the + relevant file. + </p> + </li> + <li> + <p>Take responsibility for your code.</p> + + <p>Authoring software is very much like running a marathon. It + takes time and endurance. + </p> + </li> + <li> + <p>Did we mention sticking with the indentation style? </p> + </li> + <li><p>Did we mention writing test cases? </p> + </li> + + </ol> + </answer></faq> + + + <faq id="duplicate-messages"> + <question>Why am I getting multiple copies of messages in my log file?</question> + <answer> + <p>There are several reasons this can occur: + <ul> + <li>Repeated configuration of log4j: By default, each call to + PropertyConfigurator.configure or DOMConfigurator.configure is + culmulative. If your configuration file defines a file appender, + calling PropertyConfigurator.configure three times will create + three distinct instances and connect each of them to the specified logger.</li> + <li>Attaching the same appender to multiple loggers: if an appender is + attached to the root logger and child logger, then any message + sent to the child logger will go to the appender twice (unless + additivity is set to false).</li> + </ul></p> + </answer> + </faq> + <faq id="custom-level"> + <question>How do I add a custom level?</question> + <answer> + <p>It is possible, but rarely appropriate. The + request is commonly for a level named something like "audit" + that doesn't obviously fit in the progression "trace", "debug", + "info", "warn", "error" and "fatal". In that case, the request + for a level is really a request for a mechanism to specify + a different audience. The appropriate mechanism is to use a distinct + logger name (or tree) for "audit" related messages.</p> + </answer> + </faq> </part> </faqs> Modified: logging/log4j/branches/v1_2-branch/src/site/site.xml URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/site.xml?view=diff&rev=537211&r1=537210&r2=537211 ============================================================================== --- logging/log4j/branches/v1_2-branch/src/site/site.xml (original) +++ logging/log4j/branches/v1_2-branch/src/site/site.xml Fri May 11 08:36:55 2007 @@ -19,7 +19,7 @@ <bannerLeft> <name>Apache log4j 1.2</name> <src>images/ls-logo.jpg</src> - <href>http://logging.apache.org/log4j/1.2</href> + <href>http://logging.apache.org/test/log4j/1.2</href> </bannerLeft> <bannerRight> <src>images/logo.jpg</src> @@ -27,9 +27,9 @@ <body> <breadcrumbs> <item name="Apache" href="http://www.apache.org/"/> - <item name="Logging Services" href="http://logging.apache.org/"/> - <item name="log4j" href="http://logging.apache.org/log4j/"/> - <item name="1.2" href="http://logging.apache.org/log4j/1.2/"/> + <item name="Logging Services" href="http://logging.apache.org/test/"/> + <item name="log4j" href="http://logging.apache.org/test/log4j/"/> + <item name="1.2" href="http://logging.apache.org/test/log4j/1.2/"/> </breadcrumbs> <menu name="Get log4j 1.2"> @@ -59,13 +59,13 @@ <menu name="Documentation"> <item name="Introduction" href="/manual.html"/> <item name="JavaDoc" href="/apidocs/index.html"/> - <item name="Books" href="/books.html"/> + <item name="Publications" href="/publications.html"/> </menu> <menu name="Resources"> - <item name="Sandbox" href="http://logging.apache.org/sandbox"/> - <item name="Catalog" href="http://logging.apache.org/catalog.html"/> - <item name="Wiki" href="http://wiki.apache.org/logging/log4j"/> + <item name="Sandbox" href="http://logging.apache.org/test/sandbox"/> + <item name="Catalog" href="http://logging.apache.org/test/catalog.html"/> + <item name="Wiki" href="http://wiki.apache.org/logging-log4j"/> </menu> </body> </project> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
