commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From craig...@apache.org
Subject cvs commit: jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging package.html Log4JCategoryLog.java LogSource.java NoOpLog.java SimpleLog.java
Date Mon, 03 Dec 2001 02:45:53 GMT
craigmcc    01/12/02 18:45:53

  Modified:    logging/src/java/org/apache/commons/logging
                        Log4JCategoryLog.java LogSource.java NoOpLog.java
                        SimpleLog.java
  Added:       logging/src/java/org/apache/commons/logging package.html
  Log:
  Improve the Javadoc documentation for this package, and include a
  "package.html" providing overall usage documentation.
  
  Revision  Changes    Path
  1.7       +5 -3      jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/Log4JCategoryLog.java
  
  Index: Log4JCategoryLog.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/Log4JCategoryLog.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- Log4JCategoryLog.java	2001/08/15 21:23:23	1.6
  +++ Log4JCategoryLog.java	2001/12/03 02:45:53	1.7
  @@ -12,11 +12,13 @@
   import org.apache.log4j.Priority;
   
   /**
  - * Implementation of {@link Log} that maps directly to a Log4J
  - * <strong>Category</strong>.
  + * <p>Implementation of {@link Log} that maps directly to a Log4J
  + * <strong>Category</strong>.  Initial configuration of the corresponding
  + * Category instances should be done in the usual manner, as outlined in
  + * the Log4J documentation.</p>
    *
    * @author Rod Waldhoff
  - * @version $Id: Log4JCategoryLog.java,v 1.6 2001/08/15 21:23:23 rwaldhoff Exp $
  + * @version $Id: Log4JCategoryLog.java,v 1.7 2001/12/03 02:45:53 craigmcc Exp $
    */
   public class Log4JCategoryLog  implements Log {
       Category _category = null;
  
  
  
  1.6       +4 -2      jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/LogSource.java
  
  Index: LogSource.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/LogSource.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- LogSource.java	2001/08/17 15:56:04	1.5
  +++ LogSource.java	2001/12/03 02:45:53	1.6
  @@ -14,10 +14,12 @@
   import java.lang.reflect.InvocationTargetException;
   
   /**
  - * Factory for creating {@link Log} instances.
  + * <p>Factory for creating {@link Log} instances.  Applications should call
  + * the <code>makeNewLogInstance()</code> method to instantiate new instances
  + * of the configured {@link Log} implementation class.</p>
    *
    * @author Rod Waldhoff
  - * @version $Id: LogSource.java,v 1.5 2001/08/17 15:56:04 rwaldhoff Exp $
  + * @version $Id: LogSource.java,v 1.6 2001/12/03 02:45:53 craigmcc Exp $
    */
   public class LogSource {
       static protected HashMap _logs = new HashMap();
  
  
  
  1.7       +3 -2      jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/NoOpLog.java
  
  Index: NoOpLog.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/NoOpLog.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- NoOpLog.java	2001/08/15 21:23:23	1.6
  +++ NoOpLog.java	2001/12/03 02:45:53	1.7
  @@ -9,10 +9,11 @@
   package org.apache.commons.logging;
   
   /**
  - * Default implementation of Log that throws away all messages.
  + * <p>Default implementation of Log that throws away all messages.  No
  + * configurable system properties are supported.</p>
    *
    * @author Rod Waldhoff
  - * @version $Id: NoOpLog.java,v 1.6 2001/08/15 21:23:23 rwaldhoff Exp $
  + * @version $Id: NoOpLog.java,v 1.7 2001/12/03 02:45:53 craigmcc Exp $
    */
   public final class NoOpLog implements Log {
       public NoOpLog() { }
  
  
  
  1.7       +26 -1     jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/SimpleLog.java
  
  Index: SimpleLog.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/SimpleLog.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- SimpleLog.java	2001/08/15 21:23:23	1.6
  +++ SimpleLog.java	2001/12/03 02:45:53	1.7
  @@ -16,8 +16,33 @@
   import java.util.Date;
   
   /**
  + * <p>Simple implementation of Log that sends all enabled log messages,
  + * for all defined loggers, to System.out.  The following system properties
  + * are supported to configure the behavior of this logger:</p>
  + * <ul>
  + * <li><code>org.apache.commons.logging.simplelog.defaultlog</code> -
  + *     Default logging detail level for all instances of SimpleLog.
  + *     Must be one of ("debug", "info", "warn", "error", or "fatal").
  + *     If not specified, defaults to "error".</li>
  + * <li><code>org.apache.commons.logging.simplelog.log.xxxxx</code> -
  + *     Logging detail level for a SimpleLog instance named "xxxxx".
  + *     Must be one of ("debug", "info", "warn", "error", or "fatal").
  + *     If not specified, the default logging detail level is used.</li>
  + * <li><code>org.apache.commons.logging.simplelog.showlogname</code>
-
  + *     Set to <code>true</code> if you want the Log instance name to be
  + *     included in output messages.</li>
  + * <li><code>org.apache.commons.logging.simplelog.showtime</code> -
  + *     Set to <code>true</code> if you want the current date and time
  + *     to be included in output messages.</li>
  + * </ul>
  + *
  + * <p>In addition to looking for system properties with the names specified
  + * above, this implementation also checks for a class loader resource named
  + * <code>"simplelog.properties"</code>, and includes any matching definitions
  + * from this resource (if it exists).</p>
  + *
    * @author Rod Waldhoff
  - * @version $Id: SimpleLog.java,v 1.6 2001/08/15 21:23:23 rwaldhoff Exp $
  + * @version $Id: SimpleLog.java,v 1.7 2001/12/03 02:45:53 craigmcc Exp $
    */
   public class SimpleLog implements Log {
       static protected final String _prefix =
  
  
  
  1.1                  jakarta-commons-sandbox/logging/src/java/org/apache/commons/logging/package.html
  
  Index: package.html
  ===================================================================
  <body>
  <p>Simple wrapper API around multiple logging APIs.</p>
  
  <h3>Overview</h3>
  
  <p>This package provides an API for logging in server-based applications that
  can be used around a variety of different logging implementations, including
  prebuilt support for the following:</p>
  <ul>
  <li><a href="http://jakarta.apache.org/log4j/">Log4J</a> from Apache's
      Jakarta project.  Each named <a href="Log.html">Log</a> instance is
      connected to a corresponding Log4J Category.</li>
  <!--
  <li><a href="http://java.sun.com/j2se/1.4/docs/guide/util/logging/index.html">
      JDK Logging API</a>, included in JDK 1.4 or later systems.  Each named
      <a href="Log.html">Log</a> instance is connected to a corresponding
      <code>java.util.logging.Logger</code> instance.</li>
  -->
  <li><a href="NoOpLog.html">NoOpLog</a> implementation that simply swallows
      all log output, for all named <a href="Log.html">Log</a> isntances.</li>
  <li><a href="SimpleLog.html">SimpleLog</a> implementation that writes
all
      log output, for all named <a href="Log.html">Log</a> instances, to
      System.out.</li>
  </ul>
  
  <h3>Configuring the Logging Package APIs</h3>
  
  <p>The Logging Package APIs are configured based on the values of system
  properties, which are normally set on the command line that started your
  application.  The following system properties are global to all
  <a href="Log.html">Log</a> implementations:
  <ul>
  <li><code>org.apache.commons.logging.log</code> - Fully qualified class
name
      of the <code>org.apache.commons.logging.Log</code> implementation to be
      used.  If not specified, defaults to
      <code>org.apache.commons.logging.NoOpLog</code> (which causes any logged
      messages to be thrown away.</li>
  </ul>
  
  <p>Additionally, each individual <a href="Log.html">Log</a> implementation
may
  support its own configuration properties.  These will be documented in the
  class descriptions for the corresponding implementation class.</p>
  
  <p>Finally, some <code>Log</code> implementations (such as the one for
Log4J)
  require an external configuration file for the entire logging environment.
  This file should be prepared in a manner that is specific to the actual logging
  technology being used.</p>
  
  <h3>Using the Logging Package APIs</h3>
  
  <p>Use of the Logging Package APIs, from the perspective of an application
  component, consists of the following steps:</p>
  <ol>
  <li>Acquire a reference to an instance of
      <a href="Log.html">org.apache.commons.logging.Log</a>, by calling the
      factory method
      <a href="LogSource.html#makeNewLogInstance(java.lang.String)">
      LogSource.makeNewLogInstance()</a>.  Your application can contain
      references to multiple loggers that are used for different
      purposes.  A typical scenario for a server application is to have each
      major component of the server use its own Log instance.</li>
  <li>Optionally, you can dynamically change the logging detail level by
      calling <a href="Log.html#setLevel(int)">Log.setLevel()</a> with
      an appropriate constant from the <code>Log</code> interface.  Note that,
      in most cases, the underlying logging system configuration will have
      been preconfigured by the system administrator.</li>
  <li>Cause messages to be logged (if the corresponding detail level is enabled)
      by calling appropriate methods (<code>debug()</code>, <code>info()</code>,
      <code>warn()</code>, <code>error</code>, and <code>fatal()</code>).</li>
  </ol>
  
  <p>For example, you might use the following technique to initialize and
  use a <a href="Log.html">Log</a> instance in an application component:</p>
  <pre>
  import org.apache.commons.logging.Log;
  import org.apache.commons.logging.LogSource;
  
  public class MyComponent {
  
    protected Log log = LogSource.makeNewInstance("mycomponent");
  
    // Called once at startup time
    public void start() {
      ...
      log.info("MyComponent started");
      ...
    }
  
    // Called once at shutdown time
    public void stop() {
      ...
      log.info("MyComponent stopped");
      ...
    }
  
    // Called repeatedly to process a particular argument value
    // which you want logged if debugging is enabled
    public void process(String value) {
      ...
      // Do the string concatenation only if logging is enabled
      if (log.isDebugEnabled())
        log.debug("MyComponent processing " + value);
      ...
    }
  
  }
  </pre>
  
  </body>
  
  
  

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message