You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-dev@logging.apache.org by ca...@apache.org on 2007/05/04 23:32:37 UTC
svn commit: r535385 [2/2] - in /logging/log4j/branches/v1_2-branch: ./
src/changes/ src/site/ src/site/apt/ src/site/fml/ src/site/resources/
src/site/resources/images/ src/site/xdoc/
Copied: logging/log4j/branches/v1_2-branch/src/site/apt/download.apt (from r535281, maven/site/trunk/src/site/apt/download.apt)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/apt/download.apt?view=diff&rev=535385&p1=maven/site/trunk/src/site/apt/download.apt&r1=535281&p2=logging/log4j/branches/v1_2-branch/src/site/apt/download.apt&r2=535385
==============================================================================
--- maven/site/trunk/src/site/apt/download.apt (original)
+++ logging/log4j/branches/v1_2-branch/src/site/apt/download.apt Fri May 4 14:32:31 2007
@@ -1,79 +1,44 @@
+~~ 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.
------
-Download Maven $project.version
+Download Apache log4j 1.2
------
-Brett Porter
-Jason van Zyl
------
-4 October 2005
------
-Download Maven ${currentVersion}
+Download Apache log4j 1.2.14
- Maven is distributed in several formats for your convenience.
-
- You will be prompted for a mirror - if the file is not found on yours, please be patient, as it may take 24
- hours to reach all mirrors.
-
- Maven ${currentVersion} is distributed under the {{{http://maven.apache.org/license.html} Apache License, version 2.0}}.
-
- We <<strongly>> encourage our users to configure a Maven repository mirror closer to their location, please read {{{guides/mini/guide-mirror-settings.html} How to Use Mirrors for Repositories}}.
+ Apache log4j 1.2.14 is distributed under the {{{http://www.apache.org/licenses/LICENSE-2.0.html} Apache License, version 2.0}}.
+ The link in the Mirrors column should display a list of available mirrors with a
+ default selection based on your inferred location. If you do not see that page,
+ try a different browser. The checksum and signature are links to
+ the originals on the main distribution server.
+
*-------------------------+---------+----------+-----------+
| | Mirrors | Checksum | Signature |
*-------------------------+---------+----------+-----------+
-| Maven ${currentVersion} (tar.bz2) | {{{http://www.apache.org/dyn/closer.cgi/maven/binaries/maven-${currentVersion}-bin.tar.bz2} maven-${currentVersion}-bin.tar.bz2}} | {{{http://www.apache.org/dist/maven/binaries/maven-${currentVersion}-bin.tar.bz2.md5} maven-${currentVersion}-bin.tar.bz2.md5}} | {{{http://www.apache.org/dist/maven/binaries/maven-${currentVersion}-bin.tar.bz2.asc} maven-${currentVersion}-bin.tar.bz2.asc}} |
-*-------------------------+---------+----------+-----------+
-| Maven ${currentVersion} (tar.gz) | {{{http://www.apache.org/dyn/closer.cgi/maven/binaries/maven-${currentVersion}-bin.tar.gz} maven-${currentVersion}-bin.tar.gz}} | {{{http://www.apache.org/dist/maven/binaries/maven-${currentVersion}-bin.tar.gz.md5} maven-${currentVersion}-bin.tar.gz.md5}} | {{{http://www.apache.org/dist/maven/binaries/maven-${currentVersion}-bin.tar.gz.asc} maven-${currentVersion}-bin.tar.gz.asc}} |
-*-------------------------+---------+----------+-----------+
-| Maven ${currentVersion} (zip) | {{{http://www.apache.org/dyn/closer.cgi/maven/binaries/maven-${currentVersion}-bin.zip} maven-${currentVersion}-bin.zip}} | {{{http://www.apache.org/dist/maven/binaries/maven-${currentVersion}-bin.zip.md5} maven-${currentVersion}-bin.zip.md5}} | {{{http://www.apache.org/dist/maven/binaries/maven-${currentVersion}-bin.zip.asc} maven-${currentVersion}-bin.zip.asc}} |
+| Apache log4j 1.2.14 (tar.gz) | {{{http://www.apache.org/dyn/closer.cgi/logging/log4j/1.2.14/logging-log4j-1.2.14.tar.gz} logging-log4j-1.2.14.tar.gz}} | {{{http://www.apache.org/dist/logging/log4j/1.2.14/logging-log4j-1.2.14.tar.gz.md5} logging-log4j-1.2.14.tar.gz.md5}} | {{{http://www.apache.org/dist/logging/log4j/1.2.14/logging-log4j-1.2.14.tar.gz.asc} logging-log4j-1.2.14.tar.gz.asc}} |
*-------------------------+---------+----------+-----------+
-| Maven 2.0.4 Tasks for Ant | {{{http://www.apache.org/dyn/closer.cgi/maven/binaries/maven-artifact-ant-2.0.4-dep.jar} maven-artifact-ant-2.0.4-dep.jar}} | {{{http://www.apache.org/dist/maven/binaries/maven-artifact-ant-2.0.4-dep.jar.md5} maven-artifact-ant-2.0.4-dep.jar.md5}} | {{{http://www.apache.org/dist/maven/binaries/maven-artifact-ant-2.0.4-dep.jar.asc} maven-artifact-ant-2.0.4-dep.jar.asc}} |
+| Apache log4j 1.2.14 (zip) | {{{http://www.apache.org/dyn/closer.cgi/logging/log4j/1.2.14/logging-log4j-1.2.14.zip} logging-log4j-1.2.14.zip}} | {{{http://www.apache.org/dist/logging/log4j/1.2.14/logging-log4j-1.2.14.zip.md5} logging-log4j-1.2.14.zip.md5}} | {{{http://www.apache.org/dist/logging/log4j/1.2.14/logging-log4j-1.2.14.zip.asc} logging-log4j-1.2.14.zip.asc}} |
*-------------------------+---------+----------+-----------+
-* Previous Releases
-
- All previous releases of Maven can be found in the {{{http://www.apache.org/dyn/closer.cgi/maven/binaries}distribution repository}}.
-
-* System {Requirements}
-
-*----------------------+---------------------------------------------------------------------------------------------+
-| <<JDK>> | 1.4 or above (this is to execute Maven - it still allows you to build against 1.3 and prior JDK's)
-*----------------------+---------------------------------------------------------------------------------------------+
-| <<Memory>> | No minimum requirement
-*----------------------+---------------------------------------------------------------------------------------------+
-| <<Disk>> | No minimum requirement. Approximately 100MB will be used for your local repository, however this will vary depending on usage and can be removed and redownloaded at any time.
-*----------------------+---------------------------------------------------------------------------------------------+
-| <<Operating System>> | No minimum requirement. On Windows, Windows NT and above or Cygwin is required for the startup scripts. Tested on Windows XP, Fedora Core and Mac OS X.
-*----------------------+---------------------------------------------------------------------------------------------+
-
-* {Installation} Instructions
+ Please read {{{http://httpd.apache.org/dev/verification.html}Verifying Apache HTTP Server Releases}}
+ for more information on why you should verify our releases.
-** Windows 2000/XP
- [[1]] Unzip <<<maven-${currentVersion}-bin.zip>>> to the directory you wish to install Maven ${currentVersion}. These instructions
- assume you chose <<<C:\Program Files\Apache Software Foundation\maven-${currentVersion}>>>
-
- [[2]] Add the <<<bin>>> directory to your path, by opening up the system properties (WinKey + Pause),
- selecting the "Advanced" tab, and the "Environment Variables" button, then editing the <<<PATH>>>
- variable in the user variables. eg.
- <<<"C:\Program Files\Apache Software Foundation\maven-${currentVersion}\bin";%PATH%>>>
-
- [[3]] In the same dialog, make sure that <<<JAVA_HOME>>> is set to the location of your JDK,
- eg. <<<C:\Program Files\Java\jdk1.5.0_02>>>
-
- [[4]] Run <<<mvn --version>>> to verify that it is correctly installed.
-
-** Unix-based Operating Systems (Linux, Solaris and Mac OS X)
-
- [[1]] Extract the distribution archive to the directory you wish to install Maven ${currentVersion}. These instructions
- assume you chose <<</usr/local/maven-${currentVersion}>>>. The directory <<<maven-${currentVersion}>>> will be created from
- the archive.
-
- [[2]] Add the <<<bin>>> directory to your path, eg. <<<export
-PATH=/usr/local/maven-${currentVersion}/bin:$PATH>>>
-
- [[3]] Make sure that <<<JAVA_HOME>>> is set to the location of your JDK, eg.
- <<<export JAVA_HOME=/usr/java/jdk1.5.0_02>>>
-
- [[4]] Run <<<mvn --version>>> to verify that it is correctly installed.
+* Previous Releases
+ All previous releases of Apache log4j can be found in the {{{http://archive.apache.org/dist/logging/log4j}archive repository}}.
Added: 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=auto&rev=535385
==============================================================================
--- logging/log4j/branches/v1_2-branch/src/site/apt/index.apt (added)
+++ logging/log4j/branches/v1_2-branch/src/site/apt/index.apt Fri May 4 14:32:31 2007
@@ -0,0 +1,135 @@
+ ------
+ What is Maven?
+ ------
+ Jason van Zyl
+ ------
+ 12 October 2005
+ ------
+
+Introduction
+
+ 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.
Added: 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=auto&rev=535385
==============================================================================
--- logging/log4j/branches/v1_2-branch/src/site/apt/roadmap.apt (added)
+++ logging/log4j/branches/v1_2-branch/src/site/apt/roadmap.apt Fri May 4 14:32:31 2007
@@ -0,0 +1,61 @@
+ ------
+ Maven Features
+ ------
+ Jason van Zyl
+ ------
+ 12 October 2005
+ ------
+
+Feature Summary
+
+ 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
Added: 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=auto&rev=535385
==============================================================================
--- logging/log4j/branches/v1_2-branch/src/site/fml/faq.fml (added)
+++ logging/log4j/branches/v1_2-branch/src/site/fml/faq.fml Fri May 4 14:32:31 2007
@@ -0,0 +1,37 @@
+<?xml version="1.0"?>
+<!--
+ 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.
+
+-->
+<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>
+ <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.
+ </p>
+ <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.
+ </p>
+ </answer>
+ </faq>
+
+ </part>
+</faqs>
Copied: logging/log4j/branches/v1_2-branch/src/site/site.xml (from r535280, logging/site/trunk/src/site/site.xml)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/site.xml?view=diff&rev=535385&p1=logging/site/trunk/src/site/site.xml&r1=535280&p2=logging/log4j/branches/v1_2-branch/src/site/site.xml&r2=535385
==============================================================================
--- logging/site/trunk/src/site/site.xml (original)
+++ logging/log4j/branches/v1_2-branch/src/site/site.xml Fri May 4 14:32:31 2007
@@ -15,43 +15,57 @@
limitations under the License.
-->
-<project name="Apache Logging Services Project">
+<project name="Apache log4j 1.2">
<bannerLeft>
- <name>Apache Logging Services Project</name>
+ <name>Apache log4j 1.2</name>
<src>images/ls-logo.jpg</src>
- <href>http://logging.apache.org/</href>
+ <href>http://logging.apache.org/log4j/1.2</href>
</bannerLeft>
+ <bannerRight>
+ <src>images/logo.jpg</src>
+ </bannerRight>
<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/"/>
</breadcrumbs>
- <menu name="Logging Services">
- <item name="Welcome" href="/index.html"/>
- <item name="News" href="/news.html"/>
- <item name="Charter" href="/charter.html"/>
- <item name="Guidelines" href="/guidelines.html"/>
- <item name="PMC" href="/team-list.html"/>
- <item name="Mailing List" href="/mail-lists.html"/>
+ <menu name="Get log4j 1.2">
+ <item name="Download" href="/download.html"/>
+ <item name="Changes" href="/changes-report.html"/>
<item name="License" href="/license.html"/>
</menu>
- <menu name="Products">
- <item name="chainsaw" href="/chainsaw"/>
- <item name="log4cxx" href="/log4cxx"/>
- <item name="log4j" collapse="false">
- <item name="1.2" href="/log4j"/>
- <item name="1.3" href="/log4j/1.3"/>
- <item name="2.0" href="/log4j/2.0"/>
- <item name="companions" href="/log4j/companions"/>
- </item>
- <item name="log4net" href="/log4net"/>
+ <menu name="About log4j 1.2">
+ <item name="What is log4j?" href="/index.html"/>
+ <item name="FAQ" href="/faq.html"/>
+ <item name="Roadmap" href="/roadmap.html"/>
+ </menu>
+
+ <menu name="Community">
+ <item name="Mailing Lists" href="/mail-lists.html"/>
+ <item name="Issue Tracking" href="/issue-tracking.html"/>
+ </menu>
+
+ <menu name="Development">
+ <item name="Repository" href="/source-repository.html"/>
+ <item name="Cross Reference" href="/jxr.html"/>
+ <item name="Dependencies" href="/dependencies.html"/>
+ <item name="Continuous Integration" href="/integration.html"/>
+ </menu>
+
+ <menu name="Documentation">
+ <item name="Introduction" href="/manual.html"/>
+ <item name="JavaDoc" href="/apidocs/index.html"/>
+ <item name="Books" href="/books.html"/>
</menu>
<menu name="Resources">
- <item name="Sandbox" href="/sandbox"/>
- <item name="Catalog" href="/catalog.html"/>
+ <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"/>
</menu>
</body>
</project>
Copied: logging/log4j/branches/v1_2-branch/src/site/xdoc/manual.xml (from r535272, logging/log4j/branches/v1_2-branch/docs/manual.html)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/v1_2-branch/src/site/xdoc/manual.xml?view=diff&rev=535385&p1=logging/log4j/branches/v1_2-branch/docs/manual.html&r1=535272&p2=logging/log4j/branches/v1_2-branch/src/site/xdoc/manual.xml&r2=535385
==============================================================================
--- logging/log4j/branches/v1_2-branch/docs/manual.html (original)
+++ logging/log4j/branches/v1_2-branch/src/site/xdoc/manual.xml Fri May 4 14:32:31 2007
@@ -1,21 +1,30 @@
-<html>
-<head>
-<title>log4j manual</title>
-</head>
+<!--
+ 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.
-<body bgcolor="white">
-
-<center>
-<h1>Short introduction to log4j</h1>
-
- <font size="+2">Ceki Gülcü</font>
- <br><br>
- March 2002
- <br>
-</center>
+-->
+<document>
+ <properties>
+ <author email="not@disclosed">Ceki Gülcü</author>
+ <title>Short introduction to log4j</title>
+ </properties>
+ <body>
+<section name="Short introduction to log4j: Ceki Gülcü, March 2002">
<p>
- Copyright © 2000-2002 The Apache Software Foundation. All
+ Copyright © 2000-2002 The Apache Software Foundation. All
rights reserved. This software is published under the terms of
the Apache Software License version 2.0, a copy of which has
been included in the LICENSE file shipped with the log4j
@@ -27,7 +36,7 @@
also borrows some text from <a
href="https://www.qos.ch/shop/products/eclm/">"<em>The
complete log4j manual</em>"</a> by the same author (yours
- truly).
+ truly).</p>
<h2>Abstract</h2>
@@ -37,7 +46,7 @@
are output with arbitrary granularity. It is fully configurable at
runtime using external configuration files. Best of all, log4j has a
gentle learning curve. Beware: judging from user feedback, it is also
-quite addictive.
+quite addictive.</p>
<h2>Introduction</h2>
@@ -47,19 +56,19 @@
own tracing API. This was in early 1996. After countless enhancements,
several incarnations and much work that API has evolved to become
log4j, a popular logging package for Java. The package is distributed
-under the <a href=../LICENSE>Apache Software License</a>, a
+under the <a href="../LICENSE">Apache Software License</a>, a
fully-fledged open source license certified by the <a
href="http://www.opensource.org">open source</a> initiative. The
latest log4j version, including full-source code, class files and
documentation can be found at <a
href="http://logging.apache.org/log4j/"><b>http://logging.apache.org/log4j/</b></a>.
By the way, log4j has been ported to the C, C++, C#, Perl, Python,
-Ruby, and Eiffel languages.
+Ruby, and Eiffel languages.</p>
<p>Inserting log statements into 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 usually the case for
-multithreaded applications and distributed applications at large.
+multithreaded applications and distributed applications at large.</p>
<p>Experience indicates that logging was an important component of the
development cycle. It offeres several advantages. It provides precise
@@ -68,7 +77,7 @@
intervention. Moreover, log output can be saved in persistent medium
to be studied at a later time. In addition to its use in the
development cycle, a sufficiently rich logging package can also be
-viewed as an auditing tool.
+viewed as an auditing tool.</p>
<p>As Brian W. Kernighan and Rob Pike put it in their truly excellent
book <i>"The Practice of Programming"</i>
@@ -84,13 +93,13 @@
the critical section of code, even assuming we know where that
is. More important, debugging statements stay with the program;
debugging sessions are transient.
-</pre>
+</pre></p>
<p>Logging does have its drawbacks. It can slow down an
application. If too verbose, it can cause scrolling blindness. To
alleviate these concerns, log4j is designed to be reliable, fast and
extensible. Since logging is rarely the main focus of an application,
-the log4j API strives to be simple to understand and to use.
+the log4j API strives to be simple to understand and to use.</p>
<h2>Loggers, Appenders and Layouts</h2>
@@ -98,7 +107,7 @@
<em>appenders</em> and <em>layouts</em>. These three types of
components work together to enable developers to log messages according
to message type and level, and to control at runtime how these
-messages are formatted and where they are reported.
+messages are formatted and where they are reported.</p>
<h3>Logger hierarchy</h3>
@@ -112,50 +121,50 @@
package. However, since log4j version 1.2, <code>Logger</code> class
has replaced the <code>Category</code> class. For those familiar with
earlier versions of log4j, the <code>Logger</code> class can be
-considered as a mere alias to the <code>Category</code> class.
+considered as a mere alias to the <code>Category</code> class.</p>
<p>Loggers are named entities. Logger names are case-sensitive and
-they follow the hierarchical naming rule:
+they follow the hierarchical naming rule:</p>
<p>
<table bgcolor="#EEEE99">
<tr>
<td>
<dl>
- <dt><b>Named Hierarchy</b>
+ <dt><b>Named Hierarchy</b></dt>
- <dd><p>A logger is said to be an <em>ancestor</em> of another
+ <dd>A logger is said to be an <em>ancestor</em> of another
logger if its name followed by a dot is a prefix of the
<em>descendant</em> logger name. A logger is said to be a
<em>parent</em> of a <em>child</em> logger if there are no
- ancestors between itself and the descendant logger.
+ ancestors between itself and the descendant logger.</dd>
</dl>
-</table>
+</td></tr></table></p>
<p>For example, the logger named <code>"com.foo"</code> is a parent
of the logger named <code>"com.foo.Bar"</code>. Similarly,
<code>"java"</code> is a parent of <code>"java.util"</code> and an
ancestor of <code>"java.util.Vector"</code>. This naming scheme
-should be familiar to most developers.
+should be familiar to most developers.</p>
<p>The root logger resides at the top of the logger hierarchy. It
is exceptional in two ways:
<ol>
-<li> it always exists,
-<li> it cannot be retrieved by name.
-</ol>
+<li> it always exists,</li>
+<li> it cannot be retrieved by name.</li>
+</ol></p>
<p>Invoking the class static <a
-href="api/org/apache/log4j/Logger.html#getRootLogger()">Logger.getRootLogger</a>
+href="apidocs/org/apache/log4j/Logger.html#getRootLogger()">Logger.getRootLogger</a>
method retrieves it. All other loggers are instantiated and
retrieved with the class static <a
-href="api/org/apache/log4j/Logger.html#getLogger()">Logger.getLogger</a>
+href="apidocs/org/apache/log4j/Logger.html#getLogger()">Logger.getLogger</a>
method. This method takes the name of the desired logger as a
parameter. Some of the basic methods in the Logger class are listed
-below.
+below.</p>
<p><table>
<tr bgcolor="CCCCCC">
@@ -165,7 +174,7 @@
public class <b>Logger</b> {
- // Creation & retrieval methods:
+ // Creation & retrieval methods:
public static Logger getRootLogger();
public static Logger getLogger(String name);
@@ -182,27 +191,29 @@
}
</pre>
</td>
-</table>
+</tr>
+</table></p>
<p>Loggers <em>may</em> be assigned levels. The set of possible
-levels, that is
+levels, that is:<br/><br/>
-<a href="api/org/apache/log4j/Level.html#TRACE">TRACE</a>,
-<a href="api/org/apache/log4j/Level.html#DEBUG">DEBUG</a>,
-<a href="api/org/apache/log4j/Level.html#INFO">INFO</a>,
-<a href="api/org/apache/log4j/Level.html#WARN">WARN</a>,
-<a href="api/org/apache/log4j/Level.html#ERROR">ERROR</a> and
-<a href="api/org/apache/log4j/Level.html#FATAL">FATAL</a>
+<a href="apidocs/org/apache/log4j/Level.html#TRACE">TRACE</a>,<br/>
+<a href="apidocs/org/apache/log4j/Level.html#DEBUG">DEBUG</a>,<br/>
+<a href="apidocs/org/apache/log4j/Level.html#INFO">INFO</a>,<br/>
+<a href="apidocs/org/apache/log4j/Level.html#WARN">WARN</a>,<br/>
+<a href="apidocs/org/apache/log4j/Level.html#ERROR">ERROR</a> and<br/>
+<a href="apidocs/org/apache/log4j/Level.html#FATAL">FATAL</a><br/>
+<br/>
are defined in the <code><a
-href="api/org/apache/log4j/Level.html">org.apache.log4j.Level</a></code>
+href="apidocs/org/apache/log4j/Level.html">org.apache.log4j.Level</a></code>
class. Although we do not encourage you to do so, you may define
your own levels by sub-classing the <code>Level</code> class. A
-perhaps better approach will be explained later on.
+perhaps better approach will be explained later on.</p>
<p>If a given logger is not assigned a level, then it inherits
one from its closest ancestor with an assigned level. More
-formally:
+formally:</p>
<p>
@@ -210,130 +221,132 @@
<tr>
<td>
<dl>
- <dt><b>Level Inheritance</b>
+ <dt><b>Level Inheritance</b></dt>
<dd><p>The <em>inherited level</em> for a given logger
<i>C</i>, is equal to the first non-null level in the logger
hierarchy, starting at <i>C</i> and proceeding upwards in the
-hierarchy towards the <code>root</code> logger.
+hierarchy towards the <code>root</code> logger.</p></dd>
</dl>
-</table>
+ </td>
+ </tr>
+</table></p>
<p>To ensure that all loggers can eventually inherit a level,
-the root logger always has an assigned level.
+the root logger always has an assigned level.</p>
<p>Below are four tables with various assigned level values and the
-resulting inherited levels according to the above rule.
+resulting inherited levels according to the above rule.</p>
<p>
<table border="1" >
- <tr><th>Logger<br>name</th><th>Assigned<br>level</th>
- <th>Inherited<br>level</th></tr>
- <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr>
- <tr align=left><td>X </td> <td>none</td> <td>Proot</td></tr>
- <tr align=left><td>X.Y </td> <td>none</td> <td>Proot</td></tr>
- <tr align=left><td>X.Y.Z</td> <td>none</td> <td>Proot</td></tr>
- <caption align=bottom>Example 1</caption>
-</table>
+ <tr><th>Logger<br/>name</th><th>Assigned<br/>level</th>
+ <th>Inherited<br/>level</th></tr>
+ <tr align="left"><td>root</td> <td>Proot</td> <td>Proot</td></tr>
+ <tr align="left"><td>X </td> <td>none</td> <td>Proot</td></tr>
+ <tr align="left"><td>X.Y </td> <td>none</td> <td>Proot</td></tr>
+ <tr align="left"><td>X.Y.Z</td> <td>none</td> <td>Proot</td></tr>
+ <caption align="bottom">Example 1</caption>
+</table></p>
<p>In example 1 above, only the root logger is assigned a
level. This level value, <code>Proot</code>, is inherited by the
other loggers <code>X</code>, <code>X.Y</code> and
-<code>X.Y.Z</code>.
+<code>X.Y.Z</code>.</p>
<p>
<table border="1">
- <tr><th>Logger<br>name</th><th>Assigned<br>level</th>
- <th>Inherited<br>level</th></tr>
- <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr>
- <tr align=left><td>X </td> <td>Px</td> <td>Px</td></tr>
- <tr align=left><td>X.Y </td> <td>Pxy</td> <td>Pxy</td></tr>
- <tr align=left><td>X.Y.Z</td> <td>Pxyz</td> <td>Pxyz</td></tr>
- <caption align=bottom>Example 2</caption>
- </table>
+ <tr><th>Logger<br/>name</th><th>Assigned<br/>level</th>
+ <th>Inherited<br/>level</th></tr>
+ <tr align="left"><td>root</td> <td>Proot</td> <td>Proot</td></tr>
+ <tr align="left"><td>X </td> <td>Px</td> <td>Px</td></tr>
+ <tr align="left"><td>X.Y </td> <td>Pxy</td> <td>Pxy</td></tr>
+ <tr align="left"><td>X.Y.Z</td> <td>Pxyz</td> <td>Pxyz</td></tr>
+ <caption align="bottom">Example 2</caption>
+ </table></p>
<p>In example 2, all loggers have an assigned level value. There
-is no need for level inheritence.
+is no need for level inheritence.</p>
<p><table border="1">
- <tr><th>Logger<br>name</th><th>Assigned<br>level</th>
- <th>Inherited<br>level</th></tr>
- <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr>
- <tr align=left><td>X </td> <td>Px</td> <td>Px</td></tr>
- <tr align=left><td>X.Y </td> <td>none</td> <td>Px</td></tr>
- <tr align=left><td>X.Y.Z</td> <td>Pxyz</td> <td>Pxyz</td></tr>
- <caption align=bottom>Example 3</caption>
-</table>
+ <tr><th>Logger<br/>name</th><th>Assigned<br/>level</th>
+ <th>Inherited<br/>level</th></tr>
+ <tr align="left"><td>root</td> <td>Proot</td> <td>Proot</td></tr>
+ <tr align="left"><td>X </td> <td>Px</td> <td>Px</td></tr>
+ <tr align="left"><td>X.Y </td> <td>none</td> <td>Px</td></tr>
+ <tr align="left"><td>X.Y.Z</td> <td>Pxyz</td> <td>Pxyz</td></tr>
+ <caption align="bottom">Example 3</caption>
+</table></p>
<p>In example 3, the loggers <code>root</code>, <code>X</code> and
<code>X.Y.Z</code> are assigned the levels <code>Proot</code>,
<code>Px</code> and <code>Pxyz</code> respectively. The logger
<code>X.Y</code> inherits its level value from its parent
-<code>X</code>.
+<code>X</code>.</p>
-<table border=1>
- <tr><th>Logger<br>name</th><th>Assigned<br>level</th>
- <th>Inherited<br>level</th></tr>
- <tr align=left><td>root</td> <td>Proot</td> <td>Proot</td></tr>
- <tr align=left><td>X </td> <td>Px</td> <td>Px</td></tr>
- <tr align=left><td>X.Y </td> <td>none</td> <td>Px</td></tr>
- <tr align=left><td>X.Y.Z</td> <td>none</td> <td>Px</td></tr>
- <caption align=bottom>Example 4</caption>
+<table border="1">
+ <tr><th>Logger<br/>name</th><th>Assigned<br/>level</th>
+ <th>Inherited<br/>level</th></tr>
+ <tr align="left"><td>root</td> <td>Proot</td> <td>Proot</td></tr>
+ <tr align="left"><td>X </td> <td>Px</td> <td>Px</td></tr>
+ <tr align="left"><td>X.Y </td> <td>none</td> <td>Px</td></tr>
+ <tr align="left"><td>X.Y.Z</td> <td>none</td> <td>Px</td></tr>
+ <caption align="bottom">Example 4</caption>
</table>
<p>In example 4, the loggers <code>root</code> and <code>X</code>
and are assigned the levels <code>Proot</code> and <code>Px</code>
respectively. The loggers <code>X.Y</code> and <code>X.Y.Z</code>
inherits their level value from their nearest parent <code>X</code>
-having an assigned level..
+having an assigned level..</p>
<p>Logging requests are made by invoking one of the printing methods
of a logger instance. These printing methods are
<code>
-<a href="api/org/apache/log4j/Logger.html#debug(java.lang.Object)">debug</a>,
+<a href="apidocs/org/apache/log4j/Logger.html#debug(java.lang.Object)">debug</a>,
-<a href="api/org/apache/log4j/Logger.html#info(java.lang.Object)">info</a>,
+<a href="apidocs/org/apache/log4j/Logger.html#info(java.lang.Object)">info</a>,
-<a href="api/org/apache/log4j/Logger.html#warn(java.lang.Object)">warn</a>,
-<a href="api/org/apache/log4j/Logger.html#error(java.lang.Object)">error</a>,
-<a href="api/org/apache/log4j/Logger.html#fatal(java.lang.Object)">fatal</a>
- and <a href="api/org/apache/log4j/Logger.html#log(org.apache.log4j.Level, java.lang.Object)">log</a></code>.
+<a href="apidocs/org/apache/log4j/Logger.html#warn(java.lang.Object)">warn</a>,
+<a href="apidocs/org/apache/log4j//Logger.html#error(java.lang.Object)">error</a>,
+<a href="apidocs/org/apache/log4j/Logger.html#fatal(java.lang.Object)">fatal</a>
+ and <a href="apidocs/org/apache/log4j/Logger.html#log(org.apache.log4j.Level, java.lang.Object)">log</a></code>.</p>
<p>By definition, the printing method determines the level of a
logging request. For example, if <code>c</code> is a logger
instance, then the statement <code>c.info("..")</code> is a logging
-request of level INFO.
+request of level INFO.</p>
<p>A logging request is said to be <em>enabled</em> if its level is
higher than or equal to the level of its logger. Otherwise, the
request is said to be <em>disabled</em>. A logger without an
assigned level will inherit one from the hierarchy. This rule is
-summarized below.
+summarized below.</p>
<p>
-<a name="selectionRule"><table bgcolor="#EEEE99">
+<a name="selectionRule"/><table bgcolor="#EEEE99">
<tr>
<td>
<dl>
- <dt><b>Basic Selection Rule</b>
+ <dt><b>Basic Selection Rule</b></dt>
<dd><p>A log request of level <i>p</i> in a logger with
(either assigned or inherited, whichever is appropriate) level <i>q</i>, is enabled if <i> p >=
- q</i>.
+ q</i>.</p></dd>
</dl>
-</table>
+</td></tr></table></p>
<p>This rule is at the heart of log4j. It assumes that levels are
ordered. For the standard levels, we have <code>DEBUG < INFO
-< WARN < ERROR < FATAL</code>.
+< WARN < ERROR < FATAL</code>.</p>
-<p>Here is an example of this rule.
+<p>Here is an example of this rule.</p>
<p><table bgcolor="CCCCCC">
<tr><td>
@@ -365,10 +378,11 @@
// This request is disabled, because <font color="00AA00"><strong>DEBUG</strong></font> < <font color="0000AA"><strong>INFO</strong></font>.
barlogger.<font color="00AA00"><strong>debug</strong></font>("Exiting gas station search");
</pre>
-</table>
+</td></tr>
+</table></p>
<p>Calling the <code>getLogger</code> method with the same name will
-always return a reference to the exact same logger object.
+always return a reference to the exact same logger object.</p>
<p>For example, in
@@ -377,10 +391,10 @@
<pre>
Logger x = Logger.getLogger("wombat");
Logger y = Logger.getLogger("wombat");</pre>
-</td>
+</td></tr>
</table>
<code>x</code> and <code>y</code> refer to <em>exactly</em> the same
-logger object.
+logger object.</p>
<p>Thus, it is possible to configure a logger and then to retrieve
the same instance somewhere else in the code without passing around
@@ -388,11 +402,11 @@
where parents always preceed their children, log4j loggers can be
created and configured in any order. In particular, a "parent"
logger will find and link to its descendants even if it is
-instantiated after them.
+instantiated after them.</p>
<p>Configuration of the log4j environment is typically done at
application initialization. The preferred way is by reading a
-configuration file. This approach will be discussed shortly.
+configuration file. This approach will be discussed shortly.</p>
<p>Log4j makes it easy to name loggers by <em>software
component</em>. This can be accomplished by statically instantiating
@@ -403,10 +417,10 @@
the origin of a log message. However, this is only one possible,
albeit common, strategy for naming loggers. Log4j does not restrict
the possible set of loggers. The developer is free to name the
-loggers as desired.
+loggers as desired.</p>
<p>Nevertheless, naming loggers after the class where they are
-located seems to be the best strategy known so far.
+located seems to be the best strategy known so far.</p>
<h2>Appenders and Layouts</h2>
@@ -414,22 +428,22 @@
on their logger is only part of the picture. Log4j allows logging
requests to print to multiple destinations. In log4j speak, an output
destination is called an <em>appender</em>. Currently, appenders exist
-for the <a href="api/org/apache/log4j/ConsoleAppender.html">console</a>, <a
-href="api/org/apache/log4j/FileAppender.html">files</a>, GUI
+for the <a href="apidocs/org/apache/log4j/ConsoleAppender.html">console</a>, <a
+href="apidocs/org/apache/log4j/FileAppender.html">files</a>, GUI
components, <a
-href="api/org/apache/log4j/net/SocketAppender.html">remote socket</a>
+href="apidocs/org/apache/log4j/net/SocketAppender.html">remote socket</a>
servers, <a
-href="api/org/apache/log4j/net/JMSAppender.html">JMS</a>,
+href="apidocs/org/apache/log4j/net/JMSAppender.html">JMS</a>,
-<a href="api/org/apache/log4j/nt/NTEventLogAppender.html"> NT
+<a href="apidocs/org/apache/log4j/nt/NTEventLogAppender.html"> NT
Event Loggers</a>, and remote UNIX <a
-href="api/org/apache/log4j/net/SyslogAppender.html">Syslog</a>
-daemons. It is also possible to log <a href="api/org/apache/log4j/AsyncAppender.html">asynchronously</a>.
+href="apidocs/org/apache/log4j/net/SyslogAppender.html">Syslog</a>
+daemons. It is also possible to log <a href="apidocs/org/apache/log4j/AsyncAppender.html">asynchronously</a>.</p>
-<p>More than one appender can be attached to a logger.
+<p>More than one appender can be attached to a logger.</p>
<p>The <a
-href="api/org/apache/log4j/Logger.html#addAppender(org.apache.log4j.Appender)">addAppender</a>
+href="apidocs/org/apache/log4j/Logger.html#addAppender(org.apache.log4j.Appender)">addAppender</a>
method adds an appender to a given logger.
<b>Each enabled logging
@@ -443,64 +457,64 @@
<em>C</em>'s children will print on a file <em>and</em> on the
console. It is possible to override this default behavior so that
appender accumulation is no longer additive by <a
-href="api/org/apache/log4j/Logger.html#setAdditivity(boolean)">setting
-the additivity flag</a> to <code>false</code>.
+href="apidocs/org/apache/log4j/Logger.html#setAdditivity(boolean)">setting
+the additivity flag</a> to <code>false</code>.</p>
-<p>The rules governing appender additivity are summarized below.
+<p>The rules governing appender additivity are summarized below.</p>
<p>
-<a name="additivity"><table bgcolor="#EEEE99">
+<a name="additivity"/><table bgcolor="#EEEE99">
<tr>
<td>
<dl>
- <dt><b>Appender Additivity</b>
+ <dt><b>Appender Additivity</b></dt>
<dd><p>The output of a log statement of logger <i>C</i> will
go to all the appenders in <i>C</i> and its ancestors. This is
- the meaning of the term "appender additivity".
+ the meaning of the term "appender additivity".</p>
<p>However, if an ancestor of logger <i>C</i>, say <i>P</i>,
has the additivity flag set to <code>false</code>, then
<i>C</i>'s output will be directed to all the appenders in
<i>C</i> and it's ancestors upto and including <i>P</i> but
- not the appenders in any of the ancestors of <i>P</i>.
+ not the appenders in any of the ancestors of <i>P</i>.</p>
<p>Loggers have their additivity flag set to
- <code>true</code> by default.
- </dl>
-</table>
+ <code>true</code> by default.</p></dd>
+ </dl></td></tr>
+</table></p>
-<p>The table below shows an example:
+<p>The table below shows an example:</p>
-<p><table align=center border=3 cellpadding=10>
+<p><table align="center" border="3" cellpadding="10">
<tr rowspan="2">
- <th>Logger<br>Name <th>Added<br>Appenders <th>Additivity<br>Flag <th>Output Targets <th>Comment
-
-<tr><td>root <td>A1 <td>not applicable <td>A1
+ <th>Logger<br/>Name </th><th>Added<br/>Appenders</th> <th>Additivity<br/>Flag</th> <th>Output Targets</th> <th>Comment</th>
+ </tr>
+<tr><td>root </td><td>A1 </td><td>not applicable </td><td>A1</td>
<td>The root logger is anonymous but can be accessed with the
Logger.getRootLogger() method. There is no default appender
- attached to root.
+ attached to root.</td></tr>
-<tr><td>x <td>A-x1, A-x2 <td>true <td>A1, A-x1, A-x2
- <td>Appenders of "x" and root.
+<tr><td>x </td><td>A-x1, A-x2 </td><td>true </td><td>A1, A-x1, A-x2</td>
+ <td>Appenders of "x" and root.</td></tr>
-<tr><td>x.y <td>none <td>true <td>A1, A-x1, A-x2
- <td>Appenders of "x" and root.
+<tr><td>x.y </td><td>none </td><td>true </td><td>A1, A-x1, A-x2</td>
+ <td>Appenders of "x" and root.</td></tr>
-<tr><td>x.y.z <td>A-xyz1 <td>true <td>A1, A-x1, A-x2, A-xyz1
- <td>Appenders in "x.y.z", "x" and root.
+<tr><td>x.y.z </td><td>A-xyz1 </td><td>true </td><td>A1, A-x1, A-x2, A-xyz1</td>
+ <td>Appenders in "x.y.z", "x" and root.</td></tr>
-<tr><td>security <td>A-sec <td><font color="blue">false</font>
- <td>A-sec
+<tr><td>security </td><td>A-sec </td><td><font color="blue">false</font></td>
+ <td>A-sec</td>
<td>No appender accumulation since the additivity flag is set to
- <code>false</code>.
+ <code>false</code>.</td></tr>
-<tr><td>security.access <td>none <td> true <td> A-sec <td>Only
+<tr><td>security.access </td><td>none </td><td> true </td><td> A-sec </td><td>Only
appenders of "security" because the additivity flag in "security" is
- set to <code>false</code>.
+ set to <code>false</code>.</td></tr>
</table>
@@ -510,43 +524,43 @@
associating a <em>layout</em> with an appender. The layout is
responsible for formatting the logging request according to the user's
wishes, whereas an appender takes care of sending the formatted output
-to its destination.
+to its destination.</p>
The <a
-href="api/org/apache/log4j/PatternLayout.html">PatternLayout</a>, part
+href="apidocs/org/apache/log4j/PatternLayout.html">PatternLayout</a>, part
of the standard log4j distribution, lets the user specify the output
format according to conversion patterns similar to the C language
-<code>printf</code> function.
+<code>printf</code> function.</p>
<p>For example, the PatternLayout with the conversion pattern "%r [%t]
-%-5p %c - %m%n" will output something akin to:
+%-5p %c - %m%n" will output something akin to:<br/>
<pre>
176 [main] INFO org.foo.Bar - Located nearest gas station.
-</pre>
+</pre></p>
<p>The first field is the number of milliseconds elapsed since the
start of the program. The second field is the thread making the log
request. The third field is the level of the log statement. The
fourth field is the name of the logger associated with the log
-request. The text after the '-' is the message of the statement.
+request. The text after the '-' is the message of the statement.</p>
<p>Just as importantly, log4j will render the content of the log
message according to user specified criteria. For example, if you
frequently need to log <code>Oranges</code>, an object type used in
your current project, then you can register an
<code>OrangeRenderer</code> that will be invoked whenever an orange
-needs to be logged.
+needs to be logged.</p>
<p>Object rendering follows the class hierarchy. For example, assuming
oranges are fruits, if you register an <code>FruitRenderer</code>, all
fruits including oranges will be rendered by the
<code>FruitRenderer</code>, unless of course you registered an orange
-specific <code>OrangeRenderer</code>.
+specific <code>OrangeRenderer</code>.</p>
<p>Object renderers have to implement the
-<a href="api/org/apache/log4j/or/ObjectRenderer.html">ObjectRenderer</a>
-interface.
+<a href="apidocs/org/apache/log4j/or/ObjectRenderer.html">ObjectRenderer</a>
+interface.</p>
<h2>Configuration</h2>
@@ -556,15 +570,15 @@
percent of code is dedicated to logging. Consequently, even moderately
sized applications will have thousands of logging statements embedded
within their code. Given their number, it becomes imperative to
-manage these log statements without the need to modify them manually.
+manage these log statements without the need to modify them manually.</p>
<p>The log4j environment is fully configurable programmatically.
However, it is far more flexible to configure log4j using
configuration files. Currently, configuration files can be written in
-XML or in Java properties (key=value) format.
+XML or in Java properties (key=value) format.</p>
<p>Let us give a taste of how this is done with the help of an
-imaginary application <code>MyApp</code> that uses log4j.
+imaginary application <code>MyApp</code> that uses log4j.</p>
<p><table bgcolor="CCCCCC"><tr><td>
<pre>
@@ -592,15 +606,16 @@
}
}
</pre>
-</table>
+</td></tr>
+</table></p>
<p><code>MyApp</code> begins by importing log4j related classes. It
then defines a static logger variable with the name
<code>MyApp</code> which happens to be the fully qualified name of the
-class.
+class.</p>
<p><code>MyApp</code> uses the <code>Bar</code> class defined in the
-package <code>com.foo</code>.
+package <code>com.foo</code>.</p>
<p><table bgcolor="CCCCCC"><tr><td>
<pre>
@@ -615,53 +630,54 @@
}
}
</pre>
-</table>
+</td></tr>
+</table></p>
<p>The invocation of the <a
-href="api/org/apache/log4j/BasicConfigurator.html#configure()">BasicConfigurator.configure</a>
+href="apidocs/org/apache/log4j/BasicConfigurator.html#configure()">BasicConfigurator.configure</a>
method creates a rather simple log4j setup. This method is hardwired
to add to the root logger a <a
-href="api/org/apache/log4j/ConsoleAppender.html">
+href="apidocs/org/apache/log4j/ConsoleAppender.html">
ConsoleAppender</a>. The output will be formatted using a <a
-href="api/org/apache/log4j/PatternLayout.html">PatternLayout</a> set
-to the pattern "%-4r [%t] %-5p %c %x - %m%n".
+href="apidocs/org/apache/log4j/PatternLayout.html">PatternLayout</a> set
+to the pattern "%-4r [%t] %-5p %c %x - %m%n".</p>
<p>Note that by default, the root logger is assigned to
-<code>Level.DEBUG</code>.
+<code>Level.DEBUG</code>.</p>
<p>The output of MyApp is:
<pre>
0 [main] INFO MyApp - Entering application.
36 [main] DEBUG com.foo.Bar - Did it again!
51 [main] INFO MyApp - Exiting application.
-</pre>
+</pre></p>
<p>The figure below depicts the object diagram of <code>MyApp</code>
after just having called the <code>BasicConfigurator.configure</code>
-method.
+method.</p>
<p>
<center>
-<img src="od.gif" align="center" >
-</center>
+<img src="images/od.gif" align="center" />
+</center></p>
<p>As a side note, let me mention that in log4j child loggers link
only to their existing ancestors. In particular, the logger named
<code>com.foo.Bar</code> is linked directly to the <code>root</code>
logger, thereby circumventing the unused <code>com</code> or
<code>com.foo</code> loggers. This significantly increases
-performance and reduces log4j's memory footprint.
+performance and reduces log4j's memory footprint.</p>
<p>The <code>MyApp</code> class configures log4j by invoking
<code>BasicConfigurator.configure</code> method. Other classes only
need to import the <code>org.apache.log4j.Logger</code> class,
-retrieve the loggers they wish to use, and log away.
+retrieve the loggers they wish to use, and log away.</p>
<p>The previous example always outputs the same log information.
Fortunately, it is easy to modify <code>MyApp</code> so that the log
output can be controlled at run-time. Here is a slightly modified
-version.
+version.</p>
<p><table bgcolor="CCCCCC"><tr><td>
<pre>
@@ -687,14 +703,15 @@
}
}
</pre>
+</td></tr>
</table>
<p>This version of <code>MyApp</code> instructs
<code>PropertyConfigurator</code> to parse a configuration file and
-set up logging accordingly.
+set up logging accordingly.</p>
<p>Here is a sample configuration file that results in exactly same
-output as the previous <code>BasicConfigurator</code> based example.
+output as the previous <code>BasicConfigurator</code> based example.</p>
<p><table bgcolor="CCAAAA"><tr><td>
<pre>
@@ -708,7 +725,7 @@
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
</pre>
-</table>
+</td></tr></table></p>
<!-- <p>Please note that if you copy and paste the examples, then result is
likely to include trailing spaces on some lines. These trailing spaces
are not trimmed out but interpreted by the PropertyConfigurator. By
@@ -717,7 +734,7 @@
<p>Suppose we are no longer interested in seeing the output of any
component belonging to the <code>com.foo</code> package. The following
-configuration file shows one possible way of achieving this.
+configuration file shows one possible way of achieving this.</p>
<p><table bgcolor="CCAAAA"><tr><td>
<pre>
@@ -731,9 +748,9 @@
# Print only messages of level WARN or above in the package com.foo.
<strong>log4j.logger.com.foo=WARN</strong>
</pre>
-</table>
+</td></tr></table></p>
-<p>The output of <code>MyApp</code> configured with this file is shown below.
+<p>The output of <code>MyApp</code> configured with this file is shown below.</p>
<pre>
<strong>2000-09-07 14:07:41,508</strong> [main] INFO MyApp - Entering application.
@@ -745,9 +762,9 @@
was set to WARN in the configuration file. The log statement from the
<code>Bar.doIt</code> method has the level DEBUG, lower than the
logger level WARN. Consequently, <code>doIt()</code> method's log
-request is suppressed.
+request is suppressed.</p>
-<p>Here is another configuration file that uses multiple appenders.
+<p>Here is another configuration file that uses multiple appenders.</p>
<p><table bgcolor="CCAAAA"><tr><td>
<pre>
@@ -769,31 +786,31 @@
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
</pre>
-</table>
+</td></tr></table></p>
<p>Calling the enhanced MyApp with the this configuration file will
-output the following on the console.
+output the following on the console.</p>
<pre>
INFO [main] <strong>(MyApp2.java:12)</strong> - Entering application.
DEBUG [main] (Bar.java:8) - Doing it again!
INFO [main] (MyApp2.java:15) - Exiting application.
-</pre>
+</pre></p>
<p>In addition, as the root logger has been allocated a second
appender, output will also be directed to the <code>example.log</code>
file. This file will be rolled over when it reaches 100KB. When
roll-over occurs, the old version of <code>example.log</code> is
-automatically moved to <code>example.log.1</code>.
+automatically moved to <code>example.log.1</code>.</p>
<p>Note that to obtain these different logging behaviors we did not
need to recompile code. We could just as easily have logged to a UNIX
Syslog daemon, redirected all <code>com.foo</code> output to an NT
Event logger, or forwarded logging events to a remote log4j server,
which would log according to local server policy, for example by
-forwarding the log event to a second log4j server.
+forwarding the log event to a second log4j server.</p>
-<a name="defaultInit"><h2>Default Initialization Procedure</h2>
+<a name="defaultInit"/><h2>Default Initialization Procedure</h2>
<p>The log4j library does not make any assumptions about its
environment. In particular, there are no default log4j
@@ -804,34 +821,34 @@
loading of a class into memory. It is important to remember that
different classloaders may load distinct copies of the same
class. These copies of the same class are considered as totally
-unrelated by the JVM.
+unrelated by the JVM.</p>
<p>The default initialization is very useful in environments where the
exact entry point to the application depends on the runtime
environment. For example, the same application can be used as a
stand-alone application, as an applet, or as a servlet under the
-control of a web-server.
+control of a web-server.</p>
-<p>The exact default initialization algorithm is defined as follows:
+<p>The exact default initialization algorithm is defined as follows:</p>
<ol>
<li>Setting the <b>log4j.defaultInitOverride</b> system property to
any other value then "false" will cause log4j to skip the default
- initialization procedure (this procedure).
+ initialization procedure (this procedure).</li>
- <p><li>Set the <code>resource</code> string variable to the value of
+ <li>Set the <code>resource</code> string variable to the value of
the <b>log4j.configuration</b> system property. <em>The preferred
way to specify the default initialization file is through the
<b>log4j.configuration</b> system property.</em> In case the system
property <b>log4j.configuration</b> is not defined, then set the
string variable <code>resource</code> to its default value
- "log4j.properties".
+ "log4j.properties".</li>
- <p><li>Attempt to convert the <code>resource</code> variable to a
- URL.
+ <li>Attempt to convert the <code>resource</code> variable to a
+ URL.</li>
- <p><li>If the resource variable cannot be converted to a URL, for
+ <li>If the resource variable cannot be converted to a URL, for
example due to a <code>MalformedURLException</code>, then search for
the <code>resource</code> from the classpath by calling
<code>org.apache.log4j.helpers.Loader.getResource(resource,
@@ -839,23 +856,23 @@
"log4j.properties" constitutes a malformed URL.
<p>See <a
- href="api/org/apache/log4j/helpers/Loader.html#getResource(java.lang.String)">Loader.getResource(java.lang.String)</a>
- for the list of searched locations.
+ href="apidocs/org/apache/log4j/helpers/Loader.html#getResource(java.lang.String)">Loader.getResource(java.lang.String)</a>
+ for the list of searched locations.</p></li>
- <p><li>If no URL could not be found, abort default
+ <li>If no URL could not be found, abort default
initialization. Otherwise, configure log4j from the URL.
<p>The <a
- href="api/org/apache/log4j/PropertyConfigurator.html">PropertyConfigurator</a>
+ href="apidocs/org/apache/log4j/PropertyConfigurator.html">PropertyConfigurator</a>
will be used to parse the URL to configure log4j unless the URL ends
with the ".xml" extension, in which case the <a
- href="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>
+ href="apidocs/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>
will be used. You can optionaly specify a custom configurator. The
value of the <b>log4j.configuratorClass</b> system property is taken
as the fully qualified class name of your custom configurator. The
custom configurator you specify <em>must</em> implement the <a
- href="api/org/apache/log4j/spi/Configurator.html">Configurator</a>
- interface.
+ href="apidocs/org/apache/log4j/spi/Configurator.html">Configurator</a>
+ interface.</p></li>
</ol>
@@ -870,15 +887,15 @@
the <code>log4j.properties</code> under the
<code>WEB-INF/classes</code> directory of your web-applications. Log4j
will find the properties file and initialize itself. This is easy to
-do and it works.
+do and it works.</p>
<p>You can also choose to set the system property
<b>log4j.configuration</b> before starting Tomcat. For Tomcat 3.x The
<code>TOMCAT_OPTS</code> environment variable is used to set command
line options. For Tomcat 4.0, set the <code>CATALINA_OPTS</code>
-environment variable instead of <code>TOMCAT_OPTS</code>.
+environment variable instead of <code>TOMCAT_OPTS</code>.</p>
-<p><b>Example 1</b>
+<p><b>Example 1</b></p>
<p>The Unix shell command
<pre>
@@ -889,12 +906,12 @@
configuration file. This file should be place under the
<code>WEB-INF/classes</code> directory of your web-application. The
file will be read using the <a
-href="api/org/apache/log4j/xml/PropertyConfigurator.html">PropertyConfigurator</a>. Each
+href="apidocs/org/apache/log4j/xml/PropertyConfigurator.html">PropertyConfigurator</a>. Each
web-application will use a different default configuration file because
-each file is relative to a web-application.
+each file is relative to a web-application.</p>
-<p><b>Example 2</b>
+<p><b>Example 2</b></p>
<p>The Unix shell command
<pre>
@@ -906,11 +923,11 @@
file. This file should be place under the <code>WEB-INF/classes</code>
directory of your web-application. Since the file ends with a
<code>.xml</code> extension, it will read using the <a
-href="api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>. Each
+href="apidocs/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</a>. Each
web-application will use a different default configuration file because
-each file is relative to a web-application.
+each file is relative to a web-application.</p>
-<p><b>Example 3</b>
+<p><b>Example 3</b></p>
<p>The Windows shell command
<pre>
@@ -924,9 +941,9 @@
the file will be read using the <code>com.foo.BarConfigurator</code>
custom configurator. Each web-application will use a different
default configuration file because each file is relative to a
-web-application.
+web-application.</p>
-<p><b>Example 4</b>
+<p><b>Example 4</b></p>
<p>The Windows shell command
<pre>
@@ -935,7 +952,7 @@
tells log4j to use the file <code>c:\foobar.lcf</code> as the default
configuration file. The configuration file is fully specified by the
URL <code>file:/c:/foobar.lcf</code>. Thus, the same configuration
-file will be used for all web-applications.
+file will be used for all web-applications.</p>
<p>Different web-applications will load the log4j classes through
@@ -946,13 +963,13 @@
all attempt to write the same file. The results are likely to be less
than satisfactory. You must make sure that log4j configurations of
different web-applications do not use the same underlying system
-resource.
+resource.</p>
-<p><b>Initialization servlet</b>
+<p><b>Initialization servlet</b></p>
<p>It is also possible to use a special servlet for log4j
-initialization. Here is an example,
+initialization. Here is an example,</p>
<p><table bgcolor="CCCCCC"><tr><td>
<pre>
@@ -982,9 +999,9 @@
}
}
</pre>
-</table>
+</td></tr></table></p>
-<p>Define the following servlet in the web.xml file for your web-application.
+<p>Define the following servlet in the web.xml file for your web-application.</p>
<p><table bgcolor="CCAAAA"><tr><td>
<pre>
@@ -1000,11 +1017,11 @@
<b><load-on-startup>1</load-on-startup></b>
</servlet>
</pre>
-</table>
+</td></tr></table></p>
<p>Writing an initialization servlet is the most flexible way for
initializing log4j. There are no constraints on the code you can place
-in the <code>init()</code> method of the servlet.
+in the <code>init()</code> method of the servlet.</p>
@@ -1017,13 +1034,13 @@
applications. A common approach to differentiate the logging output of
one client from another is to instantiate a new separate logger for
each client. This promotes the proliferation of loggers and
-increases the management overhead of logging.
+increases the management overhead of logging.</p>
<p>A lighter technique is to uniquely stamp each log request initiated
from the same client interaction. Neil Harrison described this method
in the book "Patterns for Logging Diagnostic Messages," in <em>Pattern
Languages of Program Design 3</em>, edited by R. Martin, D. Riehle,
-and F. Buschmann (Addison-Wesley, 1997).
+and F. Buschmann (Addison-Wesley, 1997).</p>
@@ -1045,7 +1062,7 @@
// Remove the diagnostic context for this thread.
public <strong>static</strong> void remove();
}
-</pre>
+</pre></p>
<p>The NDC is managed per thread as a <em>stack</em> of contextual
information. Note that all methods of the <code>org.apache.log4j.NDC</code>
@@ -1056,7 +1073,7 @@
responsible only for placing the correct information in the NDC by
using the <code>push</code> and <code>pop</code> methods at a few
well-defined points in the code. In contrast, the per-client logger
-approach commands extensive changes in the code.
+approach commands extensive changes in the code.</p>
<p>To illustrate this point, let us take the example of a servlet
delivering content to numerous clients. The servlet can build the NDC
@@ -1068,38 +1085,38 @@
the same logger, can still be distinguished because each client
request will have a different NDC stack. Contrast this with the
complexity of passing a freshly instantiated logger to all code
-exercised during the client's request.
+exercised during the client's request.</p>
<p>Nevertheless, some sophisticated applications, such as virtual
hosting web servers, must log differently depending on the virtual
host context and also depending on the software component issuing the
request. Recent log4j releases support multiple hierarchy trees. This
enhancement allows each virtual host to possess its own copy of the
-logger hierarchy.
+logger hierarchy.</p>
-<a name="performance"><h2>Performance</h2>
+<a name="performance"/><h2>Performance</h2>
<p>One of the often-cited arguments against logging is its
computational cost. This is a legitimate concern as even moderately
sized applications can generate thousands of log requests. Much
effort was spent measuring and tweaking logging performance. Log4j
-claims to be fast and flexible: speed first, flexibility second.
+claims to be fast and flexible: speed first, flexibility second.</p>
-<p>The user should be aware of the following performance issues.
+<p>The user should be aware of the following performance issues.</p>
<ol>
- <b><li>Logging performance when logging is turned off.</b>
+ <li><b>Logging performance when logging is turned off.</b><br/>
<p>When logging is turned
off entirely or just for a <a
- href="api/org/apache/log4j/Hierarchy.html#setThreshold(java.lang.String)">set
+ href="apidocs/org/apache/log4j/Hierarchy.html#setThreshold(java.lang.String)">set
of levels</a>, the cost of a log request consists of a method
invocation plus an integer comparison. On a 233 MHz Pentium II
- machine this cost is typically in the 5 to 50 nanosecond range.
+ machine this cost is typically in the 5 to 50 nanosecond range.</p>
<p>However, The method invocation involves the "hidden" cost of
- parameter construction.
+ parameter construction.</p>
<p>For example, for some logger <code>cat</code>, writing,
<pre>
@@ -1112,7 +1129,7 @@
regardless of whether the message will be logged or not.
This cost of parameter construction can be quite high and it
- depends on the size of the parameters involved.
+ depends on the size of the parameters involved.</p>
<p>To avoid the parameter construction cost write:
@@ -1120,7 +1137,7 @@
if(logger.isDebugEnabled() {
logger.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
}
- </pre>
+ </pre></p>
<p>This will not incur the cost of parameter
construction if debugging is disabled. On the other hand, if
@@ -1129,12 +1146,12 @@
in <code>debugEnabled</code> and once in
<code>debug</code>. This is an insignificant
overhead because evaluating a logger takes about 1%
- of the time it takes to actually log.
+ of the time it takes to actually log.</p>
<p>In log4j, logging requests are made to instances of the Logger
class. Logger is a class and not an interface. This measurably
reduces the cost of method invocation at the cost of some
- flexibility.
+ flexibility.</p>
<p>Certain users resort to preprocessing or compile-time
@@ -1143,12 +1160,10 @@
resulting application binary does not contain any log statements,
logging cannot be turned on for that binary. In my opinion this is
a disproportionate price to pay in exchange for a small performance
- gain.
-
+ gain.</p></li>
- <p><b><li>The performance of deciding whether to log or not to log when
- logging is turned on.</b>
- </p>
+ <li><b>The performance of deciding whether to log or not to log when
+ logging is turned on.</b><br/>
<p>This is essentially the performance of walking the logger
hierarchy. When logging is turned on, log4j still needs to compare
@@ -1156,7 +1171,7 @@
logger. However, loggers may not have an assigned
level; they can inherit them from the logger hierarchy. Thus,
before inheriting a level, the logger may need to search its
- ancestors.
+ ancestors.</p>
<p>There has been a serious effort to make this hierarchy walk to
be as fast as possible. For example, child loggers link only to
@@ -1165,22 +1180,23 @@
linked directly to the root logger, thereby circumventing the
nonexistent <code>com</code> or <code>com.foo</code> loggers. This
significantly improves the speed of the walk, especially in "sparse"
-hierarchies.
+hierarchies.</p>
<p>The typical cost of walking the hierarchy is typically 3
- times slower than when logging is turned off entirely.
+ times slower than when logging is turned off entirely.</p></li>
- <p><b><li>Actually outputting log messages</b>
+ <li><b>Actually outputting log messages</b><br/>
<p>This is the cost of formatting the log output and sending it to
its target destination. Here again, a serious effort was made to
make layouts (formatters) perform as quickly as possible. The same
is true for appenders. The typical cost of actually logging is
- about 100 to 300 microseconds.
+ about 100 to 300 microseconds.</p>
See <a
- href="api/org/apache/log4j/performance/Logging.html">org.apache.log4.performance.Logging</a>
+ href="apidocs/org/apache/log4j/performance/Logging.html">org.apache.log4.performance.Logging</a>
for actual figures.
+ </li>
</ol>
@@ -1189,9 +1205,9 @@
performance. Nevertheless, contributors frequently come up with new
optimizations. You should be pleased to know that when configured with
the <a
-href="api/org/apache/log4j/SimpleLayout.html">SimpleLayout</a>
+href="apidocs/org/apache/log4j/SimpleLayout.html">SimpleLayout</a>
performance tests have shown log4j to log as quickly as
-<code>System.out.println</code>.
+<code>System.out.println</code>.</p>
<h2>Conclusions</h2>
@@ -1199,7 +1215,7 @@
distinctive features is the notion of inheritance in loggers. Using
a logger hierarchy it is possible to control which log statements
are output at arbitrary granularity. This helps reduce the volume of
-logged output and minimize the cost of logging.
+logged output and minimize the cost of logging.</p>
<p>One of the advantages of the log4j API is its manageability. Once
the log statements have been inserted into the code, they can be
@@ -1207,7 +1223,7 @@
or disabled, and sent to different and multiple output targets in
user-chosen formats. The log4j package is designed so that log
statements can remain in shipped code without incurring a heavy
-performance cost.
+performance cost.</p>
<h2>Acknowledgments</h2>
@@ -1218,5 +1234,6 @@
collective effort. My special thanks go to all the authors who have
contributed to the project. Without exception, the best features in
the package have all originated in the user community.
-
-</body> </html>
+</section>
+</body>
+</document>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-unsubscribe@logging.apache.org
For additional commands, e-mail: log4j-dev-help@logging.apache.org