ceki 01/09/26 03:42:08
Modified: build build.xml
docs HISTORY download.html
src/docbook changes.xml manual.xml
src/java/org/apache/log4j LogManager.java
PropertyConfigurator.java
src/java/org/apache/log4j/spi RepositorySelector.java
src/xdocs download.xml
Added: src/docbook wider.xml
Log:
Doc changes. Release of 1.2aplha1.
Revision Changes Path
1.51 +1 -1 jakarta-log4j/build/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/build/build.xml,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -r1.50 -r1.51
--- build.xml 2001/09/26 08:37:42 1.50
+++ build.xml 2001/09/26 10:42:07 1.51
@@ -9,7 +9,7 @@
<!-- ================================================================= -->
<project name="log4j" default="usage" basedir=".." >
- <property name="version" value="1.2alpha0"/>
+ <property name="version" value="1.2alpha1"/>
<!-- The base directory relative to which most targets are built -->
<property name="base" value="."/>
1.66 +7 -1 jakarta-log4j/docs/HISTORY
Index: HISTORY
===================================================================
RCS file: /home/cvs/jakarta-log4j/docs/HISTORY,v
retrieving revision 1.65
retrieving revision 1.66
diff -u -r1.65 -r1.66
--- HISTORY 2001/09/25 09:05:56 1.65
+++ HISTORY 2001/09/26 10:42:07 1.66
@@ -5,8 +5,14 @@
client code.
[***] Changes requiring important modifications to existing client code.
- September 25, 2001
+ September 26, 2001
+
+ - Release of version 1.2alpha_1
+
+ - This alpha release consists of documentation changes. [*]
+ September 25, 2001
+
- Release of version 1.2alpha_0
- Log4j is now configurable using JMX. [*]
1.37 +3 -3 jakarta-log4j/docs/download.html
Index: download.html
===================================================================
RCS file: /home/cvs/jakarta-log4j/docs/download.html,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -r1.36 -r1.37
--- download.html 2001/09/26 08:37:42 1.36
+++ download.html 2001/09/26 10:42:08 1.37
@@ -79,13 +79,13 @@
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
- <a name="log4j version 1.2 alpha0"><strong>log4j version 1.2
alpha0</strong></a>
+ <a name="log4j version 1.2 alpha1"><strong>log4j version 1.2
alpha1</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
- <p>An alpha version of log4j 1.2 is now
available in in <a href="../jakarta-log4j-1.2alpha0.tar.gz"><b>TAR.GZ</b></a>
- format or in <a href="../jakarta-log4j-1.2alpha0.zip"><b>ZIP</b></a> format.
+ <p>An alpha version of log4j 1.2 is now
available in in <a href="../jakarta-log4j-1.2alpha1.tar.gz"><b>TAR.GZ</b></a>
+ format or in <a href="../jakarta-log4j-1.2alpha1.zip"><b>ZIP</b></a> format.
</p>
<p>Log4j version 1.2 is still in
alpha stage. It is not
feature-complete, still requries fair amount of testing, nor
1.2 +3 -75 jakarta-log4j/src/docbook/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/changes.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- changes.xml 2001/09/26 08:37:42 1.1
+++ changes.xml 2001/09/26 10:42:08 1.2
@@ -77,82 +77,10 @@
<sect2>
<title>LogManager, RepositorySelector and LoggerRepository classes</title>
- <para>The <classname>LogManager</classname> provides a flexible
- method for retrieving <classname>Logger</classname> instances
- of <emphasis>varying types</emphasis> held in
- <emphasis>context-dependent repositories</emphasis>.
+ <para>In log4j 1.2, we introduced a powerful API to manage the
+ creation and retrieval of Loggers depending on application
+ context. See <xref linkend="wider"/> for furter details.
</para>
-
- <para>Log4j is a a low level API used in a variety of
- projects. Consequently, it is hard to make a priori
- assumptions about the environment where log4j will run. The
- problem is particularly acute in embedded components
- (e.g. libraries) which rely on log4j for their logging. The
- author of embedded component can rarely afford to make
- restrictive assumptions about the surrounding environment, a
- fortiori assumtions about logging. It might be the case that
- the end user is not interested in logging at all. It would be
- a total waste to generate logging output for a user who will
- never look at them. Under such circumstances, the embedded
- component will want to use a <classname>NullLogger</classname>
- which would not genereate any log output at all.
- </para>
-
-
- <para>Logging in Application Servers and Servlet Containers also
- create unique problems. It is often desirable to separate
- logging output originating from different applications (or
- web-application in the case of Servlet Containers). In the
- current version of log4j it is possible to have different
- applications live in their own parallel universe by using a
- different hierarchy for each application. For more details,
- refer to my <ulink
- url="http://apache.org/~ceki/multHierarchy.tar.gz";>multiple
- hierarchy tutorial</ulink> for Servlet Containers.
- </para>
-
- <para>Using multiple hierarchies works well with code that is
- designed to use them. However, it does not entend to a library
- which uses log4j but is unaware of multiple hierarchies.
- </para>
-
- <para>LogManager allows us to vary Logger implementation
- depending on the circumstances. Moreover, we would like to be
- able to control the logging repository (i.e. hierarchy) where
- loggers are held depending on the application context.
- </para>
-
-
- <para>One of the advantages of the LogManager approach is that
- the getInstance method can return totally different Logger
- implementations. For example, under JDK 1.2 we can return a
- Logger implementation that is aware of the Java2 security
- model whereas under JDK 1.1 the returned logger implementation
- may be oblivious to Java2 security checks. In shipped code,
- LogManager may be configured to return a NullLogger which
- could implement the Logger (abstract) class with empty method
- bodies.
- </para>
-
-
-
- <para>The behavior of LogManager is mostly determined by the
- RepositorySelector it uses. However, it may also be influenced
- by system properties or by parameters passed as a result of
- LogManager method invocations.
- </para>
-
- <para>The RepositorySelector returns a repository of logger
- objects offering primitives for retreiving individual loggers or
- acting on collections of loggers.
- </para>
-
- <para>One of the distinctive feature of log4j is its ability to
- arrange loggers (categories) in a hierarchy. A hierarchy is
- merely a repository of categories which happens to arrange
- them in a tree like structure.
- </para>
-
</sect2>
1.11 +2 -0 jakarta-log4j/src/docbook/manual.xml
Index: manual.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/manual.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- manual.xml 2001/09/26 08:37:42 1.10
+++ manual.xml 2001/09/26 10:42:08 1.11
@@ -3,6 +3,7 @@
<!ENTITY intro SYSTEM "intro.xml">
<!ENTITY architecture SYSTEM "architecture.xml">
<!ENTITY conf SYSTEM "configuration.xml">
+<!ENTITY wider SYSTEM "wider.xml">
<!ENTITY changes SYSTEM "changes.xml">
<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY glo SYSTEM "glossary.xml">
@@ -39,6 +40,7 @@
&intro
&architecture
&conf
+ &wider
&changes
&faq
&trouble
1.1 jakarta-log4j/src/docbook/wider.xml
Index: wider.xml
===================================================================
<chapter id="wider">
<title>The wider picture</title>
<para>The intended audience of chapter are the authors of
Application Servers, Servlet Containers and authors of general
purpose libraries.</para>
<para>Log4j is a a low level API used in a variety of
projects. Consequently, it is hard to make a priori assumptions
about the environment where log4j will run. The problem is
particularly acute in embedded components (e.g. libraries) which
rely on log4j for their logging. The author of embedded
component can rarely afford to make restrictive assumptions
about the surrounding environment, a fortiori assumtions about
logging. It might be the case that the end user is not
interested in logging at all. It would be a total waste to
generate logging output for a user who will never look at
them. Under such circumstances, the embedded component will want
to use a <classname>NullLogger</classname> which would not
genereate any log output at all. Similiarly, under JDK 1.2 we
may can use a Logger implementation that is aware of the Java2
security model whereas under JDK 1.1 use a logger implementation
may be oblivious to Java2 security checks. In shipped code,
LogManager may be configured to return a
<classname>NullLogger</classname> which could sub-class Logger
with empty method bodies.
</para>
<para>Logging in Application Servers and Servlet Containers also
create unique problems. It is often desirable to separate
logging output originating from different applications (or
web-application in the case of Servlet Containers). In the
current version of log4j it is possible to have different
applications live in their own parallel universe by using a
different hierarchy for each application. For more details,
refer to my <ulink
url="http://apache.org/~ceki/multHierarchy.tar.gz";>multiple
hierarchy tutorial</ulink> for Servlet Containers.
</para>
<para>Using multiple hierarchies works well with code that is
designed to use them. However, it does not compose well with a
library which uses log4j but is unaware of multiple
hierarchies. In log4j 1.2, a more powerful API was introduced to
manage logger creation and retrieval.
</para>
<sect1>
<title>LogManager</title>
<para>The <ulink
url="../api/org/apache/log4j/LogManager.html">LogManager</ulink>
acts as a facade to a sub-system that retrieves
<classname>Logger</classname> instances of <emphasis>varying
types</emphasis> held in <emphasis>context-dependent
repositories</emphasis>.
</para>
<para>From the users perspective, LogManager allows us to vary
Logger implementation depending on the
circumstances. Moreover, it controls the logging repository
(i.e. hierarchy) where loggers are held depending on the
application context.
</para>
<para>The behavior of LogManager is determined by the <ulink
url="../api/org/apache/log4j/spi/RepositorySelector.html">RepositorySelector</ulink>
it uses.
</para>
<para>At a given instance, the <classname>LogManager</classname>
will use one and only one
<classname>RepositorySelector</classname> implementation. The
particular implementation can be set using the <ulink
url="../api/org/apache/log4j/LogManager.html#setRepositorySelector(org.apache.log4j.spi.RepositorySelector,
java.lang.Object)">LogManager.setRepositorySelector</ulink>
method. Once set, changing the repository selector requires a
guard.</para>
<para>By default, log4j uses a very simple repository selector
which always returns the same logger repository regardless of
application context. However, a top-level application such as an
Application Server, e.g. JBoss, can set a
<classname>RepositorySelector</classname> which can track
application contexts by thread and return the approriate logger
repository.
</para>
<para>The actual algorithm for tracking applicaton context is
the responsability of the
<classname>RepositorySelector</classname> implementator.
</para>
</sect1>
<sect1>
<title>LoggerRepository</title>
<para>A <ulink
url="../api/org/apache/log4j/spi/LoggerRepository.html">LoggerRepository</ulink>
acts on a set of Loggers. It can be used to instante and
retreive them by name.
</para>
<para>One of the distinctive feature of log4j is its ability to
arrange loggers in a hierarchy. A hierarchy is merely a
repository of categories which happens to arrange them in a
tree like structure.
</para>
</sect1>
</chapter>
1.4 +7 -7 jakarta-log4j/src/java/org/apache/log4j/LogManager.java
Index: LogManager.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/LogManager.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- LogManager.java 2001/09/21 15:49:43 1.3
+++ LogManager.java 2001/09/26 10:42:08 1.4
@@ -109,6 +109,7 @@
static private RepositorySelector repositorySelector;
static {
+ // By default we use a DefaultRepositorySelector which always returns 'h'.
Hierarchy h = new Hierarchy(new RootCategory(Level.DEBUG));
repositorySelector = new DefaultRepositorySelector(h);
@@ -159,14 +160,14 @@
IllegalArgumentException}, unless the previously set
<code>guard</code> is passed as the second parameter.
- <p>This allows a high-level component to set the logger factory to
- be used. Thus, fixing the log4j environment.
+ <p>This allows a high-level component to set the {@link
+ RepositorySelector} used by the <code>LogManager</code>.
<p>For example, when tomcat starts it will be able to install its
- own logger factory. However, if and when Tomcat is embedded
- within JBoss, then JBoss will install its loggger factory and
- Tomcat will use the factory set by its container, JBoss.
- */
+ own repository selector. However, if and when Tomcat is embedded
+ within JBoss, then JBoss will install its own repository selector
+ and Tomcat will use the repository selector set by its container,
+ JBoss. */
static
public
void setRepositorySelector(RepositorySelector selector, Object guard)
@@ -182,7 +183,6 @@
LogManager.guard = guard;
LogManager.repositorySelector = selector;
-
}
static
1.42 +0 -2
jakarta-log4j/src/java/org/apache/log4j/PropertyConfigurator.java
Index: PropertyConfigurator.java
===================================================================
RCS file:
/home/cvs/jakarta-log4j/src/java/org/apache/log4j/PropertyConfigurator.java,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -r1.41 -r1.42
--- PropertyConfigurator.java 2001/09/26 08:37:42 1.41
+++ PropertyConfigurator.java 2001/09/26 10:42:08 1.42
@@ -222,8 +222,6 @@
log4j.loggerFactory=fully.qualified.name.of.loggerFactory.class
</pre>
- See {@link org.apache.log4j.examples.MyLogger} for an example.
-
<h3>Example</h3>
<p>An example configuration is given below. Other configuration
1.2 +21 -0
jakarta-log4j/src/java/org/apache/log4j/spi/RepositorySelector.java
Index: RepositorySelector.java
===================================================================
RCS file:
/home/cvs/jakarta-log4j/src/java/org/apache/log4j/spi/RepositorySelector.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- RepositorySelector.java 2001/09/03 22:33:21 1.1
+++ RepositorySelector.java 2001/09/26 10:42:08 1.2
@@ -5,8 +5,29 @@
import org.apache.log4j.Logger;
+/**
+
+ The <code>LogManager</code> uses one (and only one)
+ <code>RepositorySelector</code> implementation to select the
+ {@link LoggerRepository} for a particular application context.
+
+ <p>It is the responsability of the <code>RepositorySelector</code>
+ implementation to track the application context. Log4j makes no
+ assumptions about the application context or on its management.
+
+ <p>See also {@link org.apache.log4j.LogManager LogManager}.
+
+ @author Ceki Gülcü
+ @since 1.2
+
+ */
public interface RepositorySelector {
+ /**
+ Returns a {@link LoggerRepository} depending on the
+ context. Implementors must make sure that a valid (non-null)
+ LoggerRepository is returned.
+ */
public
LoggerRepository getLoggerRepository();
}
1.36 +3 -3 jakarta-log4j/src/xdocs/download.xml
Index: download.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/xdocs/download.xml,v
retrieving revision 1.35
retrieving revision 1.36
diff -u -r1.35 -r1.36
--- download.xml 2001/09/26 08:37:42 1.35
+++ download.xml 2001/09/26 10:42:08 1.36
@@ -57,11 +57,11 @@
</section>
- <section name="log4j version 1.2 alpha0">
+ <section name="log4j version 1.2 alpha1">
<p>An alpha version of log4j 1.2 is now available in in <a
- href="../jakarta-log4j-1.2alpha0.tar.gz"><b>TAR.GZ</b></a>
+ href="../jakarta-log4j-1.2alpha1.tar.gz"><b>TAR.GZ</b></a>
format or in <a
- href="../jakarta-log4j-1.2alpha0.zip"><b>ZIP</b></a> format.
+ href="../jakarta-log4j-1.2alpha1.zip"><b>ZIP</b></a> format.
</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
