[slf4j-dev] svn commit: r158 - in slf4j/trunk/src/java/org/slf4j: . impl
ceki at slf4j.org
ceki at slf4j.org
Fri Aug 12 19:58:48 CEST 2005
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 {@link Logger}
- * instances.
+ * <code>ILoggerFactory</code> instances manufacture {@link Logger}
+ * instances by name.
*
- * ILoggerFactory interface is used internally by {@link
- * LoggerFactory}.
+ * <p>Most users retreive {@link Logger} instances through the static
+ * {@link LoggerFactory#getLogger} mehtod. An instance of of this
+ * interface is bound internally with {@link 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 {@link Logger} instance.
+ * Return an appropriate {@link 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 {@link Marker}
* instances.
*
- * * @author Ceki Gülcü
+ * @author <a href="http://www.qos.ch/log4j/">Ceki Gülcü</a>
*/
public interface IMarkerFactory {
- /**
- * Manufacture a {@link 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 {@link 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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link #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 {@link 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 {@link IMarkerFactory} implementation
- * which creates {@link 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 {@link IMarkerFactory}
+ * interface which creates {@link BasicMarker} instances.
*
+ * <p>Simple logging systems can conform to the SLF4J API by binding
+ * {@link 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 {@link
+ * org.slf4j.MarkerFactory#getMarker} method.
+ */
+ public BasicMarkerFactory() {
+ }
+
+ /**
* Manufacture a {@link 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 {@link ILoggerFactory}
* returning the appropriate named {@link 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 {@link 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 {@link 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);
More information about the slf4j-dev
mailing list