[Japi-cvs] SF.net SVN: japi: [219] libs/logging/trunk/src/net/sf/japi/log

[<chr...@us...>]

Revision: 219
          http://svn.sourceforge.net/japi/?rev=219&view=rev
Author:   christianhujer
Date:     2006-11-26 11:33:51 -0800 (Sun, 26 Nov 2006)

Log Message:
-----------
Logging improvements: Fixed documentation of SimpleLogger, renamed AbstractLogger to StandardLogger, added VERBOSE as new logging level.

Modified Paths:
--------------
    libs/logging/trunk/src/net/sf/japi/log/SimpleLogger.java
    libs/logging/trunk/src/net/sf/japi/log/def/Level.java

Added Paths:
-----------
    libs/logging/trunk/src/net/sf/japi/log/StandardLogger.java

Removed Paths:
-------------
    libs/logging/trunk/src/net/sf/japi/log/AbstractLogger.java

Deleted: libs/logging/trunk/src/net/sf/japi/log/AbstractLogger.java
===================================================================
--- libs/logging/trunk/src/net/sf/japi/log/AbstractLogger.java	2006-11-26 18:51:59 UTC (rev 218)
+++ libs/logging/trunk/src/net/sf/japi/log/AbstractLogger.java	2006-11-26 19:33:51 UTC (rev 219)
@@ -1,93 +0,0 @@
-/*
- * JAPI - (Yet another (hopefully) useful) Java API
- *
- * Copyright (C) 2006 Christian Hujer
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License as
- * published by the Free Software Foundation; either version 2 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
- * General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
- * 02111-1307, USA.
- */
-
-package net.sf.japi.log;
-
-import net.sf.japi.log.def.Level;
-
-import java.util.ResourceBundle;
-
-/**
- * Logger is a logger which logs to {@link System#err}.
- * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
- */
-public final class AbstractLogger<Level extends Enum<Level>> implements Logger<Level> {
-
-    /** The minimum enabled level. */
-    private Level enabledLevel; // TODO: init with reasonable value
-
-    /** The ResourceBundle to get messages from. */
-    private final ResourceBundle bundle;
-
-    /**
-     * Create a Logger.
-     * @param name Name of the logger, used for retrieving the resource bundle
-     */
-    public AbstractLogger(final String name) {
-        bundle = ResourceBundle.getBundle(name);
-    }
-
-    public void log(final Level level, final String key) {
-        if (level.ordinal() >= enabledLevel.ordinal()) {
-            logImpl(level, null, bundle.getString(key));
-        }
-    }
-
-    public void log(final Level level, final String key, final Object... params) {
-        if (level.ordinal() >= enabledLevel.ordinal()) {
-            // TODO: alternatively use MessageFormat
-            logImpl(level, null, String.format(bundle.getString(key), params));
-        }
-    }
-
-    public void log(final Level level, final Throwable t, final String key) {
-        if (level.ordinal() >= enabledLevel.ordinal()) {
-            logImpl(level, t, bundle.getString(key));
-        }
-    }
-
-    public void log(final Level level, final Throwable t, final String key, final Object... params) {
-        if (level.ordinal() >= enabledLevel.ordinal()) {
-            // TODO: alternatively use MessageFormat
-            logImpl(level, t, String.format(bundle.getString(key), params));
-        }
-    }
-
-    public void setLevel(final Level level) {
-        enabledLevel = level;
-    }
-
-    public boolean isEnabled(final Level level) {
-        return level.ordinal() >= enabledLevel.ordinal();
-    }
-
-    /**
-     * Format and print a log message.
-     * @param level   Log Level
-     * @param t       Throwable to log (maybe null)
-     * @param message Message to log
-     */
-    private void logImpl(final Level level, final Throwable t, final String message) {
-        final LogEntry<Level> logEntry = new LogEntry<Level>(level, message, t);
-        System.err.format("%s:%d: %s: %s %s", logEntry.getFilename(), logEntry.getLineNumber(), level, t, message);
-    }
-
-} // class Logger

Modified: libs/logging/trunk/src/net/sf/japi/log/SimpleLogger.java
===================================================================
--- libs/logging/trunk/src/net/sf/japi/log/SimpleLogger.java	2006-11-26 18:51:59 UTC (rev 218)
+++ libs/logging/trunk/src/net/sf/japi/log/SimpleLogger.java	2006-11-26 19:33:51 UTC (rev 219)
@@ -23,29 +23,30 @@
 import net.sf.japi.log.def.Level;
 
 /**
- * Provides simple static access to logging.
+ * Provides simple static access to logging using the configured default logger.
+ * If there is no configured logger, a default configuration will be used.
  * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  */
 public final class SimpleLogger {
 
     private static final Logger<Level> defaultLogger = LoggerFactory.INSTANCE.getLogger(SimpleLogger.class);
 
-    /** @see Logger#log(Level, String) */
+    /** @see Logger#log(Enum, String) */
     public static void log(final Level level, final String message) {
         defaultLogger.log(level, message);
     }
 
-    /** @see Logger#log(Level, String, Object...) */
+    /** @see Logger#log(Enum, String, Object...) */
     public static void log(final Level level, final String message, final Object... params) {
         defaultLogger.log(level, message, params);
     }
 
-    /** @see Logger#log(Level, Throwable, String) */
+    /** @see Logger#log(Enum, Throwable, String) */
     public static void log(final Level level, final Throwable t, final String message) {
         defaultLogger.log(level, t, message);
     }
 
-    /** @see Logger#log(Level, Throwable, String, Object...) */
+    /** @see Logger#log(Enum, Throwable, String, Object...) */
     public static void log(final Level level, final Throwable t, final String message, final Object... params) {
         defaultLogger.log(level, t, message, params);
     }

Copied: libs/logging/trunk/src/net/sf/japi/log/StandardLogger.java (from rev 218, libs/logging/trunk/src/net/sf/japi/log/AbstractLogger.java)
===================================================================
--- libs/logging/trunk/src/net/sf/japi/log/StandardLogger.java	                        (rev 0)
+++ libs/logging/trunk/src/net/sf/japi/log/StandardLogger.java	2006-11-26 19:33:51 UTC (rev 219)
@@ -0,0 +1,91 @@
+/*
+ * JAPI - (Yet another (hopefully) useful) Java API
+ *
+ * Copyright (C) 2006 Christian Hujer
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
+ * 02111-1307, USA.
+ */
+
+package net.sf.japi.log;
+
+import java.util.ResourceBundle;
+
+/**
+ * Logger is a logger which logs to {@link System#err}.
+ * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
+ */
+public final class StandardLogger<Level extends Enum<Level>> implements Logger<Level> {
+
+    /** The minimum enabled level. */
+    private Level enabledLevel; // TODO: init with reasonable value
+
+    /** The ResourceBundle to get messages from. */
+    private final ResourceBundle bundle;
+
+    /**
+     * Create a Logger.
+     * @param name Name of the logger, used for retrieving the resource bundle
+     */
+    public StandardLogger(final String name) {
+        bundle = ResourceBundle.getBundle(name);
+    }
+
+    public void log(final Level level, final String key) {
+        if (level.ordinal() >= enabledLevel.ordinal()) {
+            logImpl(level, null, bundle.getString(key));
+        }
+    }
+
+    public void log(final Level level, final String key, final Object... params) {
+        if (level.ordinal() >= enabledLevel.ordinal()) {
+            // TODO: alternatively use MessageFormat
+            logImpl(level, null, String.format(bundle.getString(key), params));
+        }
+    }
+
+    public void log(final Level level, final Throwable t, final String key) {
+        if (level.ordinal() >= enabledLevel.ordinal()) {
+            logImpl(level, t, bundle.getString(key));
+        }
+    }
+
+    public void log(final Level level, final Throwable t, final String key, final Object... params) {
+        if (level.ordinal() >= enabledLevel.ordinal()) {
+            // TODO: alternatively use MessageFormat
+            logImpl(level, t, String.format(bundle.getString(key), params));
+        }
+    }
+
+    public void setLevel(final Level level) {
+        enabledLevel = level;
+    }
+
+    public boolean isEnabled(final Level level) {
+        return level.ordinal() >= enabledLevel.ordinal();
+    }
+
+    /**
+     * Format and print a log message.
+     * @param level   Log Level
+     * @param t       Throwable to log (maybe null)
+     * @param message Message to log
+     */
+    private void logImpl(final Level level, final Throwable t, final String message) {
+        final LogEntry<Level> logEntry = new LogEntry<Level>(level, message, t);
+        System.err.format("%s:%d: %s: %s %s", logEntry.getFilename(), logEntry.getLineNumber(), level, t, message);
+    }
+
+} // class Logger


Property changes on: libs/logging/trunk/src/net/sf/japi/log/StandardLogger.java
___________________________________________________________________
Name: svn:mime-type
   + text/plain
Name: svn:eol-style
   + LF

Modified: libs/logging/trunk/src/net/sf/japi/log/def/Level.java
===================================================================
--- libs/logging/trunk/src/net/sf/japi/log/def/Level.java	2006-11-26 18:51:59 UTC (rev 218)
+++ libs/logging/trunk/src/net/sf/japi/log/def/Level.java	2006-11-26 19:33:51 UTC (rev 219)
@@ -24,22 +24,70 @@
 /**
  * Enumeration of log levels.
  * <p />
- * The default JAPI Logging knows six logging levels:
+ * The default JAPI Logging knows seven logging levels:
  * <ol>
- *  <li>trace (the least serious)</li>
+ *  <li>trace (the finest / least serious)</li>
  *  <li>debug</li>
+ *  <li>verbose</li>
  *  <li>info</li>
  *  <li>warn</li>
  *  <li>error</li>
  *  <li>fatal (the most serious)</li>
  * </ol>
- * It's regarded a feature that JAPI Logging is simple and only knows exactly these six levels.
+ * It's regarded a feature that JAPI Logging is simple and well-defined and only knows exactly these seven levels.
+ * However JAPI Logging is modular enough to allow you to use your own definition of log levels instead of these default levels.
  * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  */
 public enum Level {
 
     // The ordinal of the enums is used for determining the log level.
     // Therefore the order of these enum constants MUST NOT be changed.
-    TRACE, DEBUG, INFO, WARN, ERROR, FATAL
 
+    /**
+     * Level for tracing.
+     * This is the finest and least severe level.
+     * It should be used for diagnostic messages that are usually only interesting for the program's developers.
+     * Usually, TRACE logging is only used during certain periods of development and later removed from the code.
+     */
+    TRACE,
+
+    /**
+     * Level for debugging.
+     * This level should be used for debugging and diagnostic messages that are also interesting if a user runs a program and thinks she encountered a bug.
+     */
+    DEBUG,
+
+    /**
+     * Level for verbose.
+     * Example: a program loops over files and wouldn't normally inform the user when it opens them unless the user wants the program to be verbose.
+     */
+    VERBOSE,
+
+    /**
+     * Level for info messages.
+     * Example: print program's version number at startup or statistical information after a run.
+     */
+    INFO,
+
+    /**
+     * Level for warning messages.
+     * Warning messages denote exceptional situations that do not keep the program from continueing normal flow.
+     * Example: A config file was expected to be there but not found when the program can continue with a default configuration.
+     */
+    WARN,
+
+    /**
+     * Level for error messages.
+     * Error messages denote exceptional situations that stop a program's current action to be performed properly but are not expected to change a program's state that it couldn't continue with other operations normally.
+     * Example: The user wanted to open a file but it couldn't be opened due to an IOException. The program cannot continue loading the desired file, but the user can still use the program e.g. try to open another file.
+     */
+    ERROR,
+
+    /**
+     * Level for fatal error messages.
+     * Fatal messages denote exceptional situations that indicate that the program's state is disrupted so severe that it cannot continue normally.
+     * Usually, a program exits after encountering a fatal error situation.
+     */
+    FATAL
+
 } // enum Level


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.