You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-cvs@jakarta.apache.org by ce...@apache.org on 2001/10/14 18:06:52 UTC
cvs commit: jakarta-log4j/src/docbook defaultInit.xml glossary.xml
ceki 01/10/14 09:06:52
Modified: src/docbook defaultInit.xml glossary.xml
Log:
Revision Changes Path
1.3 +109 -118 jakarta-log4j/src/docbook/defaultInit.xml
Index: defaultInit.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/defaultInit.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- defaultInit.xml 2001/10/12 07:05:11 1.2
+++ defaultInit.xml 2001/10/14 16:06:52 1.3
@@ -1,55 +1,59 @@
<chapter id="defaultInit">
- <title>Default Initialization Procedure</title>
+ <title>Default Initialization Procedure</title>
- <para>The log4j library does not make any assumptions about its
+ <para>The log4j library does not make any assumptions about its
environment. In particular, there are no default log4j
- appenders. Under certain well-defined circumstances however, the
- static inializer of the <classname>Logger</classname> class will attempt
- to automatically configure log4j. The Java language guarantees
- that the static initializer of a class is called once and only
- once during the 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.
+ appenders. A general-purpose library such as log4j cannot make
+ assumptions that are correct under all circumstances. If you
+ intend to write a library of your own, try making as few
+ assumtions as you can about the user's environment.</para>
+
+ <para>Under certain well-defined circumstances, the static inializer
+ of the <classname>Logger</classname> class will attempt to
+ automatically configure log4j. The Java language guarantees that
+ the static initializer of a class is called once and only once
+ during the 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.
</para>
- <para>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.
- </para>
-
- <procedure>
- <title>Default initialization algorithm</title>
- <para>The exact default initialization algorithm is defined as
- follows:</para>
-
- <step>
- <para>Skip default initialization if the system property
- <command>log4j.defaultInitOverride</command> is set to any value
- other than "false".
- </para>
- </step>
-
- <step>
- <para>Set the <classname>resource</classname> string variable
- to the value of the <command>log4j.configuration</command>
- system property. <emphasis>The preferred way to specify the
- default initialization file is thourough the <emphasis
- role="bold">log4j.configuration</emphasis> system
- property.</emphasis> In case the system property <emphasis
- role="bold">log4j.configuration</emphasis> is not defined,
- then set the string variable <classname>resource</classname>
- to its default value "log4j.properties".
+ <para>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.
+ </para>
+
+ <procedure>
+ <title>Default initialization algorithm</title> <para>The exact
+ default initialization algorithm is defined as follows:</para>
+
+ <step>
+ <para>Skip default initialization if the system property
+ <varname>log4j.defaultInitOverride</varname> is set to any
+ value other than "false".
+ </para>
+ </step>
+
+ <step>
+ <para>Set the <classname>resource</classname> string variable to
+ the value of the <envar>log4j.configuration</envar> system
+ property. The preferred way to specify the default
+ initialization file is thourough the
+ <envar>log4j.configuration</envar> system property. In case
+ the system property <envar>log4j.configuration</envar> is not
+ defined, then set the string variable
+ <classname>resource</classname> to its default value
+ "log4j.properties".
</para>
</step>
- <step>
- <para>Attempt to convert the <classname>resource</classname>
- variable to a URL.
- </para>
- </step>
+ <step>
+ <para>Attempt to convert the <classname>resource</classname>
+ variable to a URL.
+ </para>
+ </step>
<step>
<para>If the resource variable cannot be converted to a URL,
@@ -75,18 +79,18 @@
<para>The <ulink
url="../api/org/apache/log4j/PropertyConfigurator.html">PropertyConfigurator</ulink>
- will be used to parse the URL to configure log4j unless the
- URL ends with the ".xml"
- extension, in which case the
- <ulink
+ will be used to parse the URL to configure log4j unless
+ the URL ends with the ".xml" extension, in which case the
+ <ulink
url="../api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</ulink>
- will be used. You can optionaly specify a custom configurator. The
- value of the <emphasis role="bold">log4j.configuratorClass</emphasis> system property is taken
- as the fully qualified class name of your custom configurator. The
- custom configurator you specify <emphasis>must</emphasis> implement
- the <ulink
+ will be used. You can optionaly specify a custom
+ configurator. The value of the
+ <envar>log4j.configuratorClass</envar> system property is
+ taken as the fully qualified class name of your custom
+ configurator. The custom configurator you specify
+ <emphasis>must</emphasis> implement the <ulink
url="../api/org/apache/log4j/spi/Configurator.html">Configurator</ulink>
- interface.
+ interface.
</para>
</step>
@@ -99,34 +103,30 @@
Default Initialization under Tomcat</title>
<para>The default log4j initialization is particularly useful in
- web-server environments. Under Tomcat 3.x and 4.x, you should place
- the <classname>log4j.properties</classname> under the
- <classname>WEB-INF/classes</classname> directory of your
- web-applications. Log4j
- will find the properties file and
- initialize itself. This is easy to
- do and it works.
+ web-server environments. Under Tomcat 3.x and 4.x, you should
+ place the <filename>log4j.properties</filename> under the
+ <filename>WEB-INF/classes</filename> directory of your
+ web-applications. Log4j will find the properties file and
+ initialize itself. This is easy to do and works well.
</para>
- <para>You can also choose to set the system property <emphasis
- role="bold">log4j.configuration</emphasis> before starting
- Tomcat. For Tomcat 3.x The <classname>TOMCAT_OPTS</classname>
- environment variable is used to set command line options. For
- Tomcat 4.0, set the <classname>CATALINA_OPTS</classname>
- environment variable instead of
- <classname>TOMCAT_OPTS</classname>.
+ <para>You can also choose to set the system property
+ <envar>log4j.configuration</envar> before starting Tomcat. For
+ Tomcat 3.x The <filename>TOMCAT_OPTS</filename> environment
+ variable is used to set command line options. For Tomcat 4.0,
+ set the <envar>CATALINA_OPTS</envar> environment variable
+ instead of <envar>TOMCAT_OPTS</envar>.
</para>
<example>
- <title>FIXME FIXME</title>
+ <title>Relative path configuration file (ProperyConfigurator)</title>
<para>The Unix shell command
<computeroutput>
export TOMCAT_OPTS="-Dlog4j.configuration=foobar.txt"
</computeroutput>
-
- tells log4j to use the file <classname>foobar.txt</classname>
- as the default configuration file. This file should be place
- under the <classname>WEB-INF/classes</classname> directory of
+ tells log4j to use the file <filename>foobar.txt</filename> as
+ the default configuration file. This file should be place
+ under the <filename>WEB-INF/classes</filename> directory of
your web-application. The file will be read using the <ulink
url="../api/org/apache/log4j/xml/PropertyConfigurator.html">PropertyConfigurator</ulink>. Each
web-application will use a different default configuration for
@@ -136,7 +136,7 @@
</example>
<example>
- <title>FIXME FIXME</title>
+ <title>Relative path configuration file (DOMConfigurator)</title>
<para>The Unix shell command
<computeroutput>
@@ -144,13 +144,12 @@
</computeroutput>
tells log4j to output log4j-internal debugging information
- for the list of searched locations.and to use the file for
- the list of searched for the list of searched
- locations.locations.<classname>foobar.xml</classname> as the
- default configuration file. This file should be place under
- the <classname>WEB-INF/classes</classname> directory of your
+ for the list of searched locations and to use the file
+ <filename>foobar.xml</filename> as the default
+ configuration file. This file should be place under the
+ <filename>WEB-INF/classes</filename> directory of your
web-application. Since the file ends with a
- <classname>.xml</classname> extension, it will read using
+ <filename>.xml</filename> extension, it will read using
the <ulink
url="../api/org/apache/log4j/xml/DOMConfigurator.html">DOMConfigurator</ulink>. Each
web-application will use a different default configuration
@@ -159,48 +158,40 @@
</example>
<example>
- <title>FIXME FXME</title>
-
+ <title>Absolute-path configuration file</title>
<para>The Windows shell command
<computeroutput>
- set TOMCAT_OPTS=-Dlog4j.configuration=foobar.lcf#com.foo.BarConfigurator
- </computeroutput>
-
- tells log4j to use the file <classname>foobar.lcf</classname> as the default
- configuration file. This file should be place under the
- <classname>WEB-INF/classes</classname> directory of your web-application. Due to
- the extra reference part, the file will be read using the
- <classname>com.foo.BarConfigurator</classname> custom configurator. Each
- web-application will use a different default configuration file
- because each file is relative to a web-application. <emphasis role="bold">Support for
- custom configurators in the reference part will be dropped in future
- log4j versions. You should not rely on this feature.</emphasis>
- </para>
- </example>
-
- <example>
- <title></title>
- <para>The Windows shell command
- <computeroutput>
set TOMCAT_OPTS=-Dlog4j.configuration=file:/c:/foobar.lcf
</computeroutput>
- tells log4j to use the file <classname>c:\foobar.xml</classname> as the default
- configuration file. The configuration file is fully specified by the
- URL <classname>file:/c:/foobar.lcf</classname>. Thus, the same configuration
- file will be used for all web-applications.
+ tells log4j to use the file
+ <filename>c:\foobar.xml</filename> as the default
+ configuration file. The configuration file is fully
+ specified by the URL
+ <filename>file:/c:/foobar.lcf</filename>. Thus, the same
+ configuration file will be used for all web-applications.
</para>
</example>
- <para>Different web-applications will load the log4j classes through
- their respective classloaderss. Thus, each image of the log4j
- environment will act independetly and without any mutual
- synchronization. For example, <classname>FileAppenders</classname> defined
- exactly the same way in multiple web-application configurations will
- 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.</para>
+ <para>Different web-applications will load the log4j classes
+ through their respective classloaderss. Thus, each image of
+ the log4j environment will act independetly and without any
+ mutual synchronization. For example, a
+ <classname>FileAppender</classname> defined exactly the same
+ way in multiple web-application configurations will 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.
+ </para>
+
+ <para>More generally, appenders should not be sharing the same
+ system resource. Any appender shipped with log4j is guaranteed
+ to safely handle calls from multiple threads. However,
+ configuring one or more appenders to write to the same file or
+ system resource is unsafe as there is not mutual syncronization
+ between appenders even if they are running under the same VM.
+ </para>
</sect2>
</sect1>
@@ -283,10 +274,10 @@
<para>The easiest solution is to modify jboss' log4j
configuration file. Assuming all your classes live under
- <classname>com.wombat</classname> package or packages under it,
- configuring a a category called
- <classname>com.wombat</classname> and setting it's level and
- additivity will isolate all categories under it effectively
+ <classname>com.wombat</classname> package or in packages under
+ <classname>com.wombat</classname>, configuring a category
+ called <classname>com.wombat</classname> and setting it's level
+ and additivity will isolate all categories under it effectively
isolating logging from your code from that of JBoss. For this
approach to work properly your code should not make use of the
categories that JBoss uses such as those under
1.5 +24 -0 jakarta-log4j/src/docbook/glossary.xml
Index: glossary.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/glossary.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- glossary.xml 2001/09/20 22:19:07 1.4
+++ glossary.xml 2001/10/14 16:06:52 1.5
@@ -33,4 +33,28 @@
</glossdef>
</glossentry>
+ <glossentry id="javaSystemProperty">
+ <glossterm>Java System Property</glossterm>
+ <glossdef>
+ <para>Any of the string values available through the
+ <function>getProperty/setProperty</function> methods in
+ <classname>java.lang.System</classname>. You can set your java
+ system properties with the -D option of the <ulink
+ url="http://java.sun.com/products/jdk/1.2/docs/tooldocs/tools.html#basic">java
+ tool</ulink>.
+ </para>
+
+ <para>For example,
+ <screen>
+ <command>java</command> <option>-Dlog4j.debug=true</option> <replaceable>foo.bar</replaceable>
+ </screen>
+
+ will set the <varname>log4j.debug</varname> system property to
+ <varname>true</varname> when launching the
+ <classname>foo.bar</classname> java application.
+
+
+ </para>
+ </glossdef>
+ </glossentry>
</glossary>
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-cvs-help@jakarta.apache.org