Author: linus
Date: 2008-09-14 22:15:58-0700
New Revision: 15719
Modified:
trunk/documentation/cookbook/subsystemlogging.xml
Log:
Simplified the description of logging.
Modified: trunk/documentation/cookbook/subsystemlogging.xml
Url: http://argouml.tigris.org/source/browse/argouml/trunk/documentation/cookbook/subsystemlogging.xml?view=diff&rev=15719&p1=trunk/documentation/cookbook/subsystemlogging.xml&p2=trunk/documentation/cookbook/subsystemlogging.xml&r1=15718&r2=15719
==============================================================================
--- trunk/documentation/cookbook/subsystemlogging.xml (original)
+++ trunk/documentation/cookbook/subsystemlogging.xml 2008-09-14 22:15:58-0700
@@ -35,28 +35,17 @@
Purpose - to provide an api for debug log and trace messages.
</para>
<para>
-The purpose of debug log and trace messages is:
-To provide a mechanism that allows the developer to
+The purpose of debug log and trace messages is
+to provide a mechanism that allows the developer to
enable output of minor events focused on a specific problem area
and
to follow what is going on inside ArgoUML.
</para>
<para>
-The Logging is located in <classname>org.argouml.???</classname>
-<warning>This describes an imaginary subsystem. All ArgoUML code uses
-log4j directly.</warning>
+The Logging uses log4j directly.
</para>
<para>
-The Logging is a Layer 0 subsystem.
-</para>
- <para>
-From a strict subsystem point of view,
-the logging subsystem should be merged with the JRE subsystem.
-The problem is that the JRE subsystem is strange enough as it is
-with the fact that it doesn't exist in the source code.
-</para>
- <para>
-Logging is currently implemented using log4j.
+The Logging is an infrastructure subsystem.
</para>
<para>
<application>ArgoUML</application> uses the standard
@@ -93,8 +82,6 @@
<listitem>
<para>
The WARN level designates potentially harmful situations.
-This is if CG can't find all the information required
-and has to make something up.
</para>
</listitem>
<listitem>
@@ -108,7 +95,7 @@
</listitem>
<listitem>
<para>
- The DEBUG Level designates fine-grained informational
+The DEBUG level designates fine-grained informational
events that are most useful to debug an application.
This could be everything happening within the application.
</para>
@@ -121,12 +108,6 @@
all logging entries that belong to the above levels ERROR
and FATAL are logged as well.
</para>
- <para>
-For performance reasons, it is advised to do a check before
-frequently passed DEBUG
-and INFO log4j messages (see <xref linkend="example.log4j.speed"/>).
-The purpose of this test is to avoid the creation of the argument.
- </para>
</sect2>
<sect2>
@@ -138,6 +119,35 @@
<primary>Logger</primary>
</indexterm>
<para>
+In the ArgoUML project have decided to have all loggers
+private static final with a static initializer.
+</para>
+ <sidebar>
+ <para>
+The reason for making them private is that this reduces the coupling between
+classes i.e. there is no risk that one class uses some other class' Logger
+to do logging.
+</para>
+ <para>
+The reason for making them static is that our classes are more or less
+all either lightweight, like a representation of an object in the
+model, or a singleton.
+For the lightweight classes, having a reference to a logger object per
+object is a burden and for the singleton objects it doesn't care if
+the logger is static or not.
+</para>
+ <para>
+The reason for making this final is that it shall never be modified by
+the class.
+</para>
+ <para>
+The reason for having a static initializer is that then all classes can
+do this in the same way and we don't ever risk to forgot to create the
+Logger.
+</para>
+ </sidebar>
+
+ <para>
You should <emphasis>not</emphasis> use
<function>System.out.println</function> in
<application>ArgoUML</application>
@@ -145,18 +155,9 @@
The only exception of this rule is for output in non-GUI mode
like to print the usage message in <filename>Main.java</filename>.
</para>
-
- <para>
- To make log entries from within your own classes, you just
- need to follow the three steps below:
- <orderedlist>
- <listitem><para>Import the org.apache.log4j.Logger class</para></listitem>
- <listitem><para>Get a Logger</para></listitem>
- <listitem><para>Start Logging...</para></listitem>
- </orderedlist>
- </para>
+
<example>
- <title>For log4j version 1.2.x</title>
+ <title>Logging in ArgoUML</title>
<programlisting>
import org.apache.log4j.Logger;
...
@@ -176,94 +177,8 @@
}
</programlisting>
</example>
- <para>
-Notice that we in the ArgoUML project have decided to have all loggers
-private static final with a static initializer.
-The reason for making them private is that this reduces the coupling between
-classes i.e. there is no risk that one class uses some other class' Logger
-to do logging.
-The reason for making them static is that our classes are more or less
-all either lightweight, like a representation of an object in the
-model, or a singleton.
-For the lightweight classes, having a reference to a logger object per
-object is a burden and for the singleton objects it doesn't care if
-the logger is static or not.
-The reason for making this final is that it shall never be modified by
-the class.
-The reason for having a static initializer is that then all classes can
-do this in the same way and we don't ever risk to forgot to create the
-Logger.
-</para>
- <para>
- For performance reasons, a check before the actual logging statement
- saves the overhead of all the concatenations, data conversions and
- temporary objects that would be created otherwise. Even if logging
- is turned off for DEBUG and/or INFO level.
- </para>
- <example id="example.log4j.speed">
- <title>Improving on speed/performance</title>
- <programlisting>
- if (LOG.isDebugEnabled()) {
- LOG.debug("Entry number: " + i + " is " + entry[i]);
- }
- if (LOG.isInfoEnabled()) {
- LOG.info("Entry number: " + i + " is " + entry[i]);
- }
- </programlisting>
- </example>
- <warning>
- <para>
-Since this has a big impact also on the readability,
-only use it where it is really needed
-(like places passed several times per second or hundreds of times
-for every key the user presses).
-</para>
- </warning>
- <para>
- For more information go to the log4j homepage at
- <ulink url="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j</ulink>.
- </para>
-
- <sect3>
- <title>Reasoning around the performance issues</title>
- <para>
-Most of the log statements passed in ArgoUML are passed with logging
-turned off.
-This means that the only thing log4j should do is to determine that
-logging is off and return.
-Log4j has a really quick algorithm to determine if logging is on for
-a certain level so that is not a problem.
-</para>
- <para>
-The problem is instead explained by noticing
-the following log statement:
- <programlisting>
- int i;
-...
- LOG.debug("Entry number: " + i + " is " + entry[i]);
- </programlisting>
-It is quite innocent looking isn't it?
-Well that is because the java compiler is very helpful
-when it comes to handling strings
-and will convert it to the equivalent of:
- <programlisting>
- StringBuffer sb = new StringBuffer();
- sb.append("Entry number: ");
- sb.append(i);
- sb.append(" is ");
- sb.append(entry[i].toString());
- LOG.debug(sb.toString());
- </programlisting>
-If the entry[i] is some object with a lot of calculations
-when toString() is called and the logging statement is passed
-often some action needs to be taken.
-If the toString() methods are simple you are still
-stuck with the overhead of creating a <classname>StringBuffer</classname>
-(and a <classname>String</classname> from the sb.toString()-statement.
-</para>
- </sect3>
</sect2>
-
+
<sect2>
<title>How to Enable Logging...</title>
<para>
@@ -372,36 +287,57 @@
</sect3>
<sect3>
- <title>...when running ArgoUML from NetBeans</title>
+ <title>...when running ArgoUML in other environments</title>
<para>
- At the time of writing this paragraph, it is not possible to
- set the logging configuration file on a per project basis in
- NetBeans.
- Instead, the Global Options of
- [Debbuging and Execution/Execution Types/External
- Execution/External Process] need to be changed.
- </para>
- <example>
- <title>External Execution Property (Arguments)</title>
- <programlisting>
--cp {filesystems}{:}{classpath}{:}{library} <emphasis>-Dlog4j.configuration=URL</emphasis>
- {classname} {arguments}
- </programlisting>
- </example>
+Add the log4j configuration URL to the arguments.
+</para>
</sect3>
</sect2>
-
+
<sect2>
- <title>How to Customize Logging...</title>
+ <title>Reasoning around the performance issues</title>
<para>
- There are some sample configuration files provided in
- <parameter>org.argouml.resource</parameter>. Modify these according
- to your needs.
- Or alternatively, you can try <ulink url="http://www.japhy.de/configLog4j">
- configLog4j</ulink> to assist yourself in creating a log4j configuration file.
- </para>
+Most of the log statements passed in ArgoUML are passed with logging
+turned off.
+This means that the only thing log4j should do is to determine that
+logging is off and return.
+Log4j has a really quick algorithm to determine if logging is on for
+a certain level so that is not a problem.
+</para>
+
+ <para>
+The problem is how to
+avoid the overhead of all the concatenations, data conversions and
+temporary objects that would be created otherwise. Even if logging
+is turned off for DEBUG and/or INFO level.
+</para>
+ <para>
+It is best explained by noticing the following log statement:
+ <programlisting>
+ int i;
+...
+ LOG.debug("Entry number: " + i + " is " + entry[i]);
+ </programlisting>
+It is quite innocent looking isn't it?
+That is because the java compiler is very helpful
+when it comes to handling strings
+and will convert it to the equivalent of:
+ <programlisting>
+ StringBuffer sb = new StringBuffer();
+ sb.append("Entry number: ");
+ sb.append(i);
+ sb.append(" is ");
+ sb.append(entry[i].toString());
+ LOG.debug(sb.toString());
+ </programlisting>
+If entry[i] is some object with a lot of calculations
+this could cause a performance problem.
+If the toString() methods are simple you are still
+stuck with the overhead of creating a <classname>StringBuffer</classname>
+(and a <classname>String</classname> from the sb.toString()-statement.
+</para>
</sect2>
-
+
<sect2>
<title>References</title>
<itemizedlist>
@@ -410,11 +346,6 @@
<ulink url="http://jakarta.apache.org/log4j/">http://jakarta.apache.org/log4j</ulink>
</para>
</listitem>
- <listitem><para>
- The configlog4j homepage at
- <ulink url="http://www.japhy.de/configLog4j/">http://www.japhy.de/configLog4j</ulink>
- </para>
- </listitem>
<!-- TO DO
... add links to other log4j tutorials etc.
-->
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.