Author: ceki Date: Fri Aug 12 19:58:45 2005 New Revision: 158 Modified: slf4j/trunk/src/java/org/slf4j/ILoggerFactory.java slf4j/trunk/src/java/org/slf4j/IMarkerFactory.java slf4j/trunk/src/java/org/slf4j/Logger.java slf4j/trunk/src/java/org/slf4j/Marker.java slf4j/trunk/src/java/org/slf4j/impl/BasicMarker.java slf4j/trunk/src/java/org/slf4j/impl/BasicMarkerFactory.java slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerAdapter.java slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerFactory.java slf4j/trunk/src/java/org/slf4j/impl/NOPLogger.java slf4j/trunk/src/java/org/slf4j/impl/SimpleLogger.java Log:
- Added getName method to Logger - Improved javadocs Modified: slf4j/trunk/src/java/org/slf4j/ILoggerFactory.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/ILoggerFactory.java (original) +++ slf4j/trunk/src/java/org/slf4j/ILoggerFactory.java Fri Aug 12 19:58:45 2005 @@ -34,22 +34,30 @@ /** - * Implementaitons of this interface are used to manufacture [EMAIL PROTECTED] Logger} - * instances. + * <code>ILoggerFactory</code> instances manufacture [EMAIL PROTECTED] Logger} + * instances by name. * - * ILoggerFactory interface is used internally by [EMAIL PROTECTED] - * LoggerFactory}. + * <p>Most users retreive [EMAIL PROTECTED] Logger} instances through the static + * [EMAIL PROTECTED] LoggerFactory#getLogger} mehtod. An instance of of this + * interface is bound internally with [EMAIL PROTECTED] LoggerFactory} compile + * time. Only developers of SLF4J conformant logging systems SLF4J + * need to worry about this interface. * - * <p>Normally, only developers wishing to write new SLF4J adapters need to - * worry about this interface. However, - * - * @author Ceki Gülcü + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> * */ public interface ILoggerFactory { /** - * Return the appropriate named [EMAIL PROTECTED] Logger} instance. + * Return an appropriate [EMAIL PROTECTED] Logger} instance as specified by the + * <code>name</code> parameter. + * + * <p>Null-valued name arguments are considered invalid. + * + * <p>Certain extremely simple logging systems, e.g. NOP, may always + * return the same logger instance regardless of the requested name. + * + * @param name the name of the Logger to return */ public Logger getLogger(String name); } Modified: slf4j/trunk/src/java/org/slf4j/IMarkerFactory.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/IMarkerFactory.java (original) +++ slf4j/trunk/src/java/org/slf4j/IMarkerFactory.java Fri Aug 12 19:58:45 2005 @@ -1,6 +1,5 @@ /* - * Copyright (c) 2004-2005 SLF4J.ORG - * Copyright (c) 2004-2005 QOS.ch + * Copyright (c) 2004-2005 SLF4J.ORG Copyright (c) 2004-2005 QOS.ch * * All rights reserved. * @@ -38,15 +37,20 @@ * Implementaitons of this interface are used to manufacture [EMAIL PROTECTED] Marker} * instances. * - * * @author Ceki Gülcü + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> */ public interface IMarkerFactory { - /** - * Manufacture a [EMAIL PROTECTED] Marker} instance by name. If the instance has been - * created earlier, return the previously created instance. - * - * @param name the name of the marker to be created - * @return a Marker instance - */ - Marker getMarker(String name); + + /** + * Manufacture a [EMAIL PROTECTED] Marker} instance by name. If the instance has been + * created earlier, return the previously created instance. + * + * <p>Null name values are not allowed. + * + * @param name the name of the marker to be created, null value is + * not allowed. + * + * @return a Marker instance + */ + Marker getMarker(String name); } Modified: slf4j/trunk/src/java/org/slf4j/Logger.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/Logger.java (original) +++ slf4j/trunk/src/java/org/slf4j/Logger.java Fri Aug 12 19:58:45 2005 @@ -35,13 +35,18 @@ /** * * The main user interface to logging. It is expected that logging - * takes places through concrete implementations of the Logger - * interface. + * takes place through concrete implementations of this interface. * - * @author Ceki Gülcü + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> */ public interface Logger { + + /** + * Return the name of this <code>Logger</code> instance. + */ + public String getName(); + /** * Is the logger instance enabled for the DEBUG level? * @return True if this Logger is enabled for the DEBUG level, @@ -49,7 +54,14 @@ */ public boolean isDebugEnabled(); + /** + * Similar to [EMAIL PROTECTED] #isDebugEnabled()} method except that the + * marker data is also taken into account. + * + * @param marker The marker data to take into consideration + */ public boolean isDebugEnabled(Marker marker); + /** * Log a message at the DEBUG level. * @@ -59,14 +71,6 @@ /** - * Log a message with the specific Marker at the DEBUG level. - * - * @param marker The marker specific for this log statement - * @param msg the message string to be logged - */ - public void debug(Marker marker, String msg); - - /** * Log a message at the DEBUG level according to the specified format * and argument. * @@ -78,7 +82,7 @@ */ public void debug(String format, Object arg); - public void debug(Marker marker, String format, Object arg); + /** * Log a message at the DEBUG level according to the specified format @@ -93,9 +97,6 @@ */ public void debug(String format, Object arg1, Object arg2); - public void debug(Marker marker, String format, Object arg1, Object arg2); - - /** * Log an exception (throwable) at the DEBUG level with an * accompanying message. @@ -104,9 +105,49 @@ * @param t the exception (throwable) to log */ public void debug(String msg, Throwable t); + + /** + * Log a message with the specific Marker at the DEBUG level. + * + * @param marker the marker data specific to this log statement + * @param msg the message string to be logged + */ + public void debug(Marker marker, String msg); + + /** + * This method is similar to [EMAIL PROTECTED] #debug(String, Object)} method except that the + * marker data is also taken into consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg the argument + */ + public void debug(Marker marker, String format, Object arg); + + + /** + * This method is similar to [EMAIL PROTECTED] #debug(String, Object, Object)} + * method except that the marker data is also taken into + * consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg1 the first argument + * @param arg2 the second argument + */ + public void debug(Marker marker, String format, Object arg1, Object arg2); + /** + * This method is similar to [EMAIL PROTECTED] #debug(String, Throwable)} method except that the + * marker data is also taken into consideration. + * + * @param marker the marker data specific to this log statement + * @param msg the message accompanying the exception + * @param t the exception (throwable) to log + */ public void debug(Marker marker, String msg, Throwable t); + /** * Is the logger instance enabled for the INFO level? * @return True if this Logger is enabled for the INFO level, @@ -114,6 +155,13 @@ */ public boolean isInfoEnabled(); + + /** + * Similar to [EMAIL PROTECTED] #isInfoEnabled()} method except that the marker + * data is also taken into consideration. + * + * @param marker The marker data to take into consideration + */ public boolean isInfoEnabled(Marker marker); /** @@ -123,8 +171,6 @@ */ public void info(String msg); - public void info(Marker marker, String msg); - /** * Log a message at the INFO level according to the specified format @@ -138,6 +184,7 @@ */ public void info(String format, Object arg); + /** * Log a message at the INFO level according to the specified format * and arguments. @@ -160,8 +207,44 @@ */ public void info(String msg, Throwable t); + /** + * Log a message with the specific Marker at the INFO level. + * + * @param marker The marker specific to this log statement + * @param msg the message string to be logged + */ + public void info(Marker marker, String msg); + + /** + * This method is similar to [EMAIL PROTECTED] #info(String, Object)} method except that the + * marker data is also taken into consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg the argument + */ public void info(Marker marker, String format, Object arg); + + /** + * This method is similar to [EMAIL PROTECTED] #debug(String, Object, Object)} + * method except that the marker data is also taken into + * consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg1 the first argument + * @param arg2 the second argument + */ public void info(Marker marker, String format, Object arg1, Object arg2); + + /** + * This method is similar to [EMAIL PROTECTED] #info(String, Throwable)} method + * except that the marker data is also taken into consideration. + * + * @param marker the marker data for this log statement + * @param msg the message accompanying the exception + * @param t the exception (throwable) to log + */ public void info(Marker marker, String msg, Throwable t); @@ -203,7 +286,7 @@ * @param arg2 the second argument */ public void warn(String format, Object arg1, Object arg2); - + /** * Log an exception (throwable) at the WARN level with an * accompanying message. @@ -212,12 +295,57 @@ * @param t the exception (throwable) to log */ public void warn(String msg, Throwable t); - + + /** + * Similar to [EMAIL PROTECTED] #isWarnEnabled()} method except that the marker + * data is also taken into consideration. + * + * @param marker The marker data to take into consideration + */ + public boolean isWarnEnabled(Marker marker); + + /** + * Log a message with the specific Marker at the WARN level. + * + * @param marker The marker specific to this log statement + * @param msg the message string to be logged + */ public void warn(Marker marker, String msg); + + /** + * This method is similar to [EMAIL PROTECTED] #warn(String, Object)} method except that the + * marker data is also taken into consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg the argument + */ public void warn(Marker marker, String format, Object arg); + + /** + * This method is similar to [EMAIL PROTECTED] #debug(String, Object, Object)} + * method except that the marker data is also taken into + * consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg1 the first argument + * @param arg2 the second argument + */ public void warn(Marker marker, String format, Object arg1, Object arg2); + + + /** + * This method is similar to [EMAIL PROTECTED] #warn(String, Throwable)} method + * except that the marker data is also taken into consideration. + * + * @param marker the marker data for this log statement + * @param msg the message accompanying the exception + * @param t the exception (throwable) to log + */ public void warn(Marker marker, String msg, Throwable t); - public boolean isWarnEnabled(Marker marker); + + /** * Is the logger instance enabled for the ERROR level? @@ -225,14 +353,14 @@ * false otherwise. */ public boolean isErrorEnabled(); - + /** * Log a message at the ERROR level. * * @param msg the message string to be logged */ public void error(String msg); - + /** * Log a message at the ERROR level according to the specified format * and argument. @@ -267,10 +395,55 @@ */ public void error(String msg, Throwable t); + /** + * Similar to [EMAIL PROTECTED] #isErrorEnabled()} method except that the + * marker data is also taken into consideration. + * + * @param marker The marker data to take into consideration + */ + public boolean isErrorEnabled(Marker marker); + + /** + * Log a message with the specific Marker at the ERROR level. + * + * @param marker The marker specific to this log statement + * @param msg the message string to be logged + */ public void error(Marker marker, String msg); + + /** + * This method is similar to [EMAIL PROTECTED] #error(String, Object)} method except that the + * marker data is also taken into consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg the argument + */ public void error(Marker marker, String format, Object arg); + + /** + * This method is similar to [EMAIL PROTECTED] #debug(String, Object, Object)} + * method except that the marker data is also taken into + * consideration. + * + * @param marker the marker data specific to this log statement + * @param format the format string + * @param arg1 the first argument + * @param arg2 the second argument + */ public void error(Marker marker, String format, Object arg1, Object arg2); - public void error(Marker marker, String msg, Throwable t); - public boolean isErrorEnabled(Marker marker); + + + /** + * This method is similar to [EMAIL PROTECTED] #error(String, Throwable)} + * method except that the marker data is also taken into + * consideration. + * + * @param marker the marker data specific to this log statement + * @param msg the message accompanying the exception + * @param t the exception (throwable) to log + */ + public void error(Marker marker, String msg, Throwable t); + } Modified: slf4j/trunk/src/java/org/slf4j/Marker.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/Marker.java (original) +++ slf4j/trunk/src/java/org/slf4j/Marker.java Fri Aug 12 19:58:45 2005 @@ -36,12 +36,16 @@ import java.util.Iterator; /** - * Markers are named objects which can be used to enrich log statements. + * Markers are named objects used to enrich log statements. Conforming + * logging system Implementations of SLF4J determine how information + * conveyed by markers are used, if at all. In particular, many + * conformant logging systems ignore markers. * - * <p>Markers can contain child markers which can contain children of their - * own. * - * @author Ceki Gulcu + * <p>Markers can contain child markers, which in turn can contain + * children of their own. + * + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> */ public interface Marker { @@ -71,8 +75,9 @@ public boolean hasChildren(); /** - * Returns an Iterator which can be used to iterator over the children of this - * marker. An empty iterator is returned when this marker has no children. + * Returns an Iterator which can be used to iterate over the + * children of this marker. An empty iterator is returned when this + * marker has no children. * * @return Iterator over the children of this marker */ Modified: slf4j/trunk/src/java/org/slf4j/impl/BasicMarker.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/impl/BasicMarker.java (original) +++ slf4j/trunk/src/java/org/slf4j/impl/BasicMarker.java Fri Aug 12 19:58:45 2005 @@ -42,10 +42,16 @@ /** - * @author ceki + * An almost trivial implementation of the [EMAIL PROTECTED] Marker} interface. * - * TODO To change the template for this generated type comment go to - * Window - Preferences - Java - Code Style - Code Templates + * <p><code>BasicMarker</code> lets users specify marker + * information. However, it does not offer any useful operations on + * that information. + * + * <p>Simple logging systems which ignore marker data, just return + * instances of this class in order to conform to the SLF4J API. + * + * @author Ceki Gulcu* */ public class BasicMarker implements Marker { String name; @@ -82,9 +88,6 @@ } } - /** - * - */ public synchronized boolean remove(Marker markerToRemove) { if (children == null) { return false; Modified: slf4j/trunk/src/java/org/slf4j/impl/BasicMarkerFactory.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/impl/BasicMarkerFactory.java (original) +++ slf4j/trunk/src/java/org/slf4j/impl/BasicMarkerFactory.java Fri Aug 12 19:58:45 2005 @@ -40,18 +40,28 @@ import org.slf4j.Marker; /** - * A basic implementation of the [EMAIL PROTECTED] IMarkerFactory} implementation - * which creates [EMAIL PROTECTED] BasicMarker} instances. <code>BasicMarkerFactory</code> - * keeps track of the marker instances it creates with the help - * of a hashtable. + * An almost trivial implementation of the [EMAIL PROTECTED] IMarkerFactory} + * interface which creates [EMAIL PROTECTED] BasicMarker} instances. * + * <p>Simple logging systems can conform to the SLF4J API by binding + * [EMAIL PROTECTED] org.slf4j.MarkerFactory} with an instance of this class. + * * @author Ceki Gulcu - */ + */ public class BasicMarkerFactory implements IMarkerFactory { Map markerMap = new HashMap(); /** + * Regular users should <em>not</em> create + * <code>BasicMarkerFactory</code> instances. <code>Marker</code> + * instances can be obtained using the static [EMAIL PROTECTED] + * org.slf4j.MarkerFactory#getMarker} method. + */ + public BasicMarkerFactory() { + } + + /** * Manufacture a [EMAIL PROTECTED] BasicMarker} instance by name. If the instance has been * created earlier, return the previously created instance. * Modified: slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerAdapter.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerAdapter.java (original) +++ slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerAdapter.java Fri Aug 12 19:58:45 2005 @@ -56,6 +56,10 @@ this.logger = logger; } + public String getName() { + return logger.getName(); + } + /** * Is this logger instance enabled for the FINE level? * Modified: slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerFactory.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerFactory.java (original) +++ slf4j/trunk/src/java/org/slf4j/impl/JDK14LoggerFactory.java Fri Aug 12 19:58:45 2005 @@ -43,7 +43,7 @@ * JDK14LoggerFactory is an implementation of [EMAIL PROTECTED] ILoggerFactory} * returning the appropriate named [EMAIL PROTECTED] JDK14LoggerAdapter} instance. * - * @author Ceki Gülcü + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> */ public class JDK14LoggerFactory implements ILoggerFactory { Modified: slf4j/trunk/src/java/org/slf4j/impl/NOPLogger.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/impl/NOPLogger.java (original) +++ slf4j/trunk/src/java/org/slf4j/impl/NOPLogger.java Fri Aug 12 19:58:45 2005 @@ -40,7 +40,7 @@ /** * A direct NOP (no operation) implementation of [EMAIL PROTECTED] Logger}. * - * @author Ceki Gülcü + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> */ public final class NOPLogger implements Logger { /** @@ -56,6 +56,13 @@ } /** + * Always returns the string value "NOP". + */ + public String getName() { + return "NOP"; + } + + /** * Always returns false. * @return always false */ Modified: slf4j/trunk/src/java/org/slf4j/impl/SimpleLogger.java ============================================================================== --- slf4j/trunk/src/java/org/slf4j/impl/SimpleLogger.java (original) +++ slf4j/trunk/src/java/org/slf4j/impl/SimpleLogger.java Fri Aug 12 19:58:45 2005 @@ -60,7 +60,7 @@ 467 [main] INFO examples.Sort - Exiting main method. </pre> * - * @author Ceki Gülcü + * @author <a href="http://www.qos.ch/log4j/";>Ceki Gülcü</a> */ public class SimpleLogger implements Logger { /** @@ -72,16 +72,19 @@ private static String INFO_STR = "INFO"; private static String WARN_STR = "WARN"; private static String ERROR_STR = "ERROR"; - String loggerName; + String name; /** * Package access allows only [EMAIL PROTECTED] SimpleLoggerFactory} to instantiate * SimpleLogger instances. */ SimpleLogger(String name) { - this.loggerName = name; + this.name = name; } + public String getName() { + return name; + } /** * Always returns false. * @return always false @@ -166,7 +169,7 @@ buf.append(level); buf.append(" "); - buf.append(loggerName); + buf.append(name); buf.append(" - "); buf.append(message); _______________________________________________ dev mailing list [email protected] http://slf4j.org/mailman/listinfo/dev
