rsitze 02/02/22 06:49:15
Modified: java/docs developers-guide.html integration-guide.html
Log:
Updated log/trace section
Revision Changes Path
1.8 +222 -1 xml-axis/java/docs/developers-guide.html
Index: developers-guide.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/developers-guide.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- developers-guide.html 30 Jan 2002 10:30:05 -0000 1.7
+++ developers-guide.html 22 Feb 2002 14:49:14 -0000 1.8
@@ -3,7 +3,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.72 [en] (Windows NT 5.0; U)
[Netscape]">
- <title>Axis System Integration Guide</title>
+ <title>Axis Developer's Guide</title>
<!-- saved from url=(0022)http://internet.e-mail -->
<style type="text/css">
<!--
@@ -30,6 +30,7 @@
<a href="#Introduction">Introduction</a>
<br><a href="#General Guidelines">General Guidelines</a>
<br><a href="#Development Environment">Development Environment</a>
+<br><a href="#Logging/Tracing">Logging/Tracing</a>
<br><a href="#Compile And Run">Compile and Run</a>
<br><a href="#Internationalization">Internationalization</a>
<br><a href="#Adding Testcases">Adding Testcases</a>
@@ -100,6 +101,226 @@
<blockquote><tt><font color="#009900">-Dhttp.proxyHost=proxy.somewhere.com
-Dhttp.proxyPort=80 -Dhttp.nonProxyHosts="localhost"</font></tt></blockquote>
</blockquote>
+
+<h2>
+<a NAME="Logging/Tracing"></a>Logging/Tracing</h2>
+AXIS logging and tracing is based on the Logging component of the
+<a href="http://jakarta.apache.org/commons/index.html";>Jakarta Commons</a>
+project, or the Jakarta Commons Logging (JCL) SPI.
+The JCL provides a Log interface with thin-wrapper implementations for
+other logging tools, including
+<a href="http://jakarta.apache.org/log4j/docs/index.html";>Log4J</a>,
+<a href="http://jakarta.apache.org/avalon/logkit/index.html";>Avalon LogKit</a>,
+and
+<a>JDK 1.4</a>.
+The interface maps closely to Log4J and LogKit.
+<h3>Using the Logger SPI</h3>
+<p>
+To use the JCL SPI from a Java class,
+include the following import statements:
+<ul>
+<code>
+import org.apache.commons.logging.Log;
+<br>
+import org.apache.commons.logging.LogFactory;
+<br>
+</code>
+</ul>
+For each class definition, declare and initialize a
+<code>log</code> attribute as follows:
+<ul>
+<code>
+public class CLASS
+<br>{
+<br> private static Log log = LogFactory.getLog(CLASS.class);
+<br> ...
+<br>
+</code>
+</ul>
+<p>
+Messages are logged to a <i>logger</i>, such as <code>log</code>
+by invoking a method corresponding to <i>priority</i>:
+The <code>Log</code> interface defines the following methods for use
+in writing log/trace messages to the log:
+<ul>
+<code>
+log.fatal(Object message);
+<br>log.fatal(Object message, Throwable t);
+<br>log.error(Object message);
+<br>log.error(Object message, Throwable t);
+<br>log.warn(Object message);
+<br>log.warn(Object message, Throwable t);
+<br>log.info(Object message);
+<br>log.info(Object message, Throwable t);
+<br>log.debug(Object message);
+<br>log.debug(Object message, Throwable t);
+<br>log.trace(Object message);
+<br>log.trace(Object message, Throwable t);
+</code>
+</ul>
+While semantics for these methods are ultimately
+defined by the implementation of the Log interface,
+it is expected that the severity of messages is ordered
+as shown in the above list.
+<p>
+In addition to the logging methods, the following are provided:
+<ul>
+<code>
+log.isFatalEnabled();
+<br>log.isErrorEnabled();
+<br>log.isWarnEnabled();
+<br>log.isInfoEnabled();
+<br>log.isDebugEnabled();
+<br>log.isTraceEnabled();
+</code>
+</ul>
+These are typically used to guard code that
+only needs to execute in support of logging,
+and that introduces undesirable runtime overhead
+in the general case (logging disabled).
+
+<h3>Guidelines</h3>
+<h4>Message Priorities</h4>
+It is important to ensure that log message are
+appropriate in content and severity.
+The following guidelines are suggested:
+<ul>
+<li>fatal - Severe errors that cause the AXIS server to terminate prematurely.
+Expect these to be immediately visible on a console.</li>
+<br>
+<li>error - Other runtime errors or unexpected conditions.
+Expect these to be immediately visible on a console.</li>
+<br>
+<li>warn - Use of deprecated APIs, poor use of API, Almost errors, other
+runtime situations that are undesirable or unexpected, but not
+necessarily "wrong".
+Expect these to be immediately visible on a console.</li>
+<br>
+<li>info -
+Interesting runtime events (startup/shutdown).
+Expect these to be immediately visible on a console,
+so be conservative and keep to a minimum.</li>
+<br>
+<li>debug - detailed information on flow of through the system.
+Expect these to be written to logs only.</li>
+<br>
+<li>trace - more detailed information.
+Expect these to be written to logs only.</li>
+</ul>
+
+<h4>Debug Output</h4>
+Developers may be tempted to use <code>System.out.println</code>
+while debugging or analyzing a system.
+PLEASE DON'T.
+Remember that AXIS is targetted for use in a number
+of open-source and other web applications,
+and so it needs to be a good citizen.
+We strongly encourage you to use the following guidelines:
+<ul>
+<li>
+Take a few moments and introduce debug statements
+<code>log.debug("reasonably terse and meaningful message");</code>
+If they are useful for understanding a problem now,
+they may be again in the future to you or a peer.
+</li>
+
+<br>
+<li>
+You are saying: <i>"Yes, but I don't want to see ALL the debug output"</i>.
+Turn on DEBUG output ONLY for the package(s) or class(es)
+that you are interested in.
+In Log4J, leave the root (default) priority high,
+lower the threshold for either the
+<code>CONSOLE</code> or <code>LOGFILE</code>
+appenders (assuming your properties file is based on the
+<code>log4j.properties</code> file in AXIS) as you desire,
+and set the logger (class/package name) priority down to <code>DEBUG</code>.
+See <a href="#Configuring the Logger">Configuring the Logger</a>, below.
+</li>
+
+<br>
+<li>
+You are saying: <i>"OK, but I still have TO MUCH OUTPUT"</i>.
+Welcome to the real world :-).
+Seriously, consider logging to a file and using tools to
+extract the information you need (grep).
+Place key words in log messages that will help categorize them.
+At worst, try <code>log.debug("myname: my message");</code>.
+This last is also good for messages that you want to clean out when done,
+as it makes it easy to search for your specific debug statements.
+Regardless, remove <code>myname</code> from the message when done.
+</li>
+</ul>
+
+<h3><a NAME="Configuring the Logger">Configuring the Logger</a></h3>
+The Jakarta Commons Logging (JCL) SPI
+can be configured to use different logging toolkits.
+To configure which logger is used by the JCL, see the
+<a href="integration-guide.html">AXIS System Integration Guide</a>.
+<p>
+Configuration of the behavior of the JCL ultimately depends upon the
+logging toolkit being used.
+The JCL SPI (and hence AXIS) uses
+<a href="http://jakarta.apache.org/log4j/docs/index.html";>Log4J</a>
+by default if it is available (in the CLASSPATH).
+<h4>Log4J</h4>
+As
+<a href="http://jakarta.apache.org/log4j/docs/index.html";>Log4J</a>
+is the prefered/default logger for AXIS,
+a <i>few</i> details are presented herein to get the developer going.
+<p>
+Configure Log4J using system properties and/or a properties file:
+<ul>
+<li><h5>log4j.configuration=<i>log4j.properties</i></h5></li>
+Use this system property to specify the name of a Log4J configuration file.
+If not specified, the default configuration file is <i>log4j.properties</i>.
+A <i>log4j.properties</i> file is provided in <code>axis.jar</code>,
+but can be overridden (?verify this still works?)
+by placing a file of the same name so as to
+appear before <code>axis.jar</code> in the CLASSPATH.
+
+<br>
+<li><h5>log4j.rootCategory=<i>priority</i> [, <i>appender</i>]*</h5></li>
+Set the default (root) logger priority.
+
+<br>
+<li><h5>log4j.logger.<i>logger.name</i>=<i>priority</i></h5></li>
+Set the priority for the named logger
+and all loggers hierarchically lower than, or below, the
+named logger.
+<i>logger.name</i> corresponds to the parameter of
+<code>LogFactory.getLog(<i>logger.name</i>)</code>,
+used to create the logger instance. Priorities are:
+<code>DEBUG</code>,
+<code>INFO</code>,
+<code>WARN</code>,
+<code>ERROR</code>,
+or <code>FATAL</code>.
+<p>
+Log4J understands hierarchical names,
+enabling control by package or high-level qualifiers:
+<code>log4j.logger.org.apache.axis.encoding=DEBUG</code>
+will enable debug messages for all classes in both
+<code>org.apache.axis.encoding</code>
+and
+<code>org.apache.axis.encoding.ser</code>.
+Likewise, setting
+<code>log4j.logger.org.apache.axis=DEBUG</code>
+will enable debug message for all AXIS classes,
+but not for other Jakarta projects.
+<br>
+<li><h5>log4j.appender.<i>appender</i>.Threshold=<i>priority</i></h5></li>
+Log4J <i>appenders</i> correspond to different output devices:
+console, files, sockets, and others.
+If appender's <i>threshold</i>
+is less than or equal to the message priority then
+the message is written by that appender.
+This allows different levels of detail to be appear
+at different log destinations.
+<p>
+For example: one can capture DEBUG (and higher) level information in a logfile,
+while limiting console output to INFO (and higher).
+</ul>
<h2>
<a NAME="Compile And Run"></a>Compile and Run</h2>
1.4 +117 -29 xml-axis/java/docs/integration-guide.html
Index: integration-guide.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/integration-guide.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- integration-guide.html 22 Jan 2002 15:35:11 -0000 1.3
+++ integration-guide.html 22 Feb 2002 14:49:14 -0000 1.4
@@ -44,7 +44,7 @@
of Pluggable APIs that are necessary for such an integration.
<p>
The reader may find useful background information in the
-<a href="architecture-guide.html">Architecture Guide</a>.
+<a href="architecture-guide.html">Architecture Guide</a>.
<h2>
<a NAME="Pluggable APIs"></a>Pluggable APIs</h2>
@@ -86,40 +86,128 @@
Example</li>
</ul>
-<h3>
-<a NAME="Logging/Tracing Plug"></a>Logging/Tracing</h3>
-How can AXIS fit into existing logging/tracing systems other than log4j?
+<h3><a NAME="Logging/Tracing Plug"></a>Logging/Tracing</h3>
+AXIS logging and tracing is based on the Logging component of the
+<a href="http://jakarta.apache.org/commons/index.html";>Jakarta Commons</a>
+project, or the Jakarta Commons Logging (JCL) SPI.
+The JCL provides a Log interface with thin-wrapper implementations for
+other logging tools, including
+<a href="http://jakarta.apache.org/log4j/docs/index.html";>Log4J</a>,
+<a href="http://jakarta.apache.org/avalon/logkit/index.html";>Avalon LogKit</a>,
+and
+<a>JDK 1.4</a>.
+The interface maps closely to Log4J and LogKit.
+
+<h4>Justification/Rationale</h4>
+A pluggable logging/trace facility enables
+AXIS to direct logging/trace messages to a host web application server's
+logging facility.
+A central logging facility with a single point of configuration/control
+is superior to distinct logging mechanisms for each of a multitude of
+middleware components that are to be integrated into
+a web application server.
+
+<h4>Integration</h4>
+The minimum requirement to integrate with another logger
+is to provide an implementation of the
+<code>org.apache.commons.logging.Log</code> interface.
+In addition, an implementation of the
+<code>org.apache.commons.logging.LogFactory</code> interface
+can be provided to meet
+specific requirements for connecting to, or instantiating, a logger.
<ul>
-<li>
-Justification/Rationale - why is this plug point necessary? Spec
-compliance?</li>
-
-<li>
-Interfaces</li>
-
-<li>
-Mechanism</li>
-
+<li><h5>org.apache.commons.logging.Log</h5></li>
+The <code>Log</code> interface defines the following methods for use
+in writing log/trace messages to the log:
<ul>
-<li>
-Life cycle</li>
-
-<li>
-Exception handling - in general; plug-in shouldn't throw any exceptions
-- does runtime ignore? Log?)</li>
-
-<li>
-Multiple thread support? Ie., is synchronization required?</li>
+<code>
+<br>log.fatal(Object message);
+<br>log.fatal(Object message, Throwable t);
+<br>log.error(Object message);
+<br>log.error(Object message, Throwable t);
+<br>log.warn(Object message);
+<br>log.warn(Object message, Throwable t);
+<br>log.info(Object message);
+<br>log.info(Object message, Throwable t);
+<br>log.debug(Object message);
+<br>log.debug(Object message, Throwable t);
+<br>log.trace(Object message);
+<br>log.trace(Object message, Throwable t);
+<br>
+<br>log.isFatalEnabled();
+<br>log.isErrorEnabled();
+<br>log.isWarnEnabled();
+<br>log.isInfoEnabled();
+<br>log.isDebugEnabled();
+<br>log.isTraceEnabled();
+<br>
+</code>
+</ul>
+<p>
+Semantics for these methods are such that it is expected
+that the severity of messages is ordered, from highest to lowest:
+<p>
+<ul>
+<li>fatal - Consider logging to console and system log.</li>
+<li>error - Consider logging to console and system log.</li>
+<li>warn - Consider logging to console and system log.</li>
+<li>info - Consider logging to console and system log.</li>
+<li>debug - Log to system log, if enabled.</li>
+<li>trace - Log to system log, if enabled.</li>
</ul>
-<li>
-Configuration/reconfiguration</li>
+<br>
+<li><h5>org.apache.commons.logging.LogFactory</h5></li>
+If desired, the default implementation of the
+<code>org.apache.commons.logging.LogFactory</code>
+interface can be overridden,
+allowing the JDK 1.3 Service Provider discovery process
+to locate and create a LogFactory specific to the needs of the application.
+Review the Javadoc for the <code>LogFactoryImpl.java</code>
+for details.
+</ul>
-<li>
-Default behavior if not plugged.</li>
+<h4>Mechanism</h4>
+<ul>
+<li><h5>Life cycle</h5></li>
+The JCL LogFactory implementation must assume responsibility for
+either connecting/disconnecting to a logging toolkit,
+or instantiating/initializing/destroying a logging toolkit.
+<br>
+<li><h5>Exception handling</h5></li>
+The JCL Log interface doesn't specify any exceptions to be handled,
+the implementation must catch any exceptions.
+<br>
+<li><h5>Multiple threads</h5></li>
+The JCL Log and LogFactory implementations must ensure
+that any synchronization required by the logging toolkit
+is met.
+</ul>
-<li>
-Example</li>
+<h4>Logger Configuration</h4>
+<ul>
+<li><h5>Log</h5></li>
+The default <code>LogFactory</code> provided by JCL
+can be configured to instantiate a specific implementation of the
+<code>org.apache.commons.logging.Log</code> interface
+by setting the property <code>org.apache.commons.logging.Log</code>.
+This property can be specified as a system property,
+or in the <code>commons-logging.properties</code> file,
+which must exist in the CLASSPATH.
+<br>
+<li><h5>Default logger if not plugged</h5></li>
+The Jakarta Commons Logging SPI uses the
+implementation of the <code>org.apache.commons.logging.Log</code>
+interface specified by the system property
+<code>org.apache.commons.logging.Log</code>.
+If the property is not specified or the class is not available then the JCL
+provides access to a default logging toolkit by searching the CLASSPATH
+for the following toolkits, in order of preference:
+<ul>
+<li><a href="http://jakarta.apache.org/log4j/docs/index.html";>Log4J</a></li>
+<li>JDK 1.4</li>
+<li>JCL SimpleLog</li>
+</ul>
</ul>
<h3>
