You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ma...@apache.org on 2014/08/31 00:19:34 UTC
[07/50] [abbrv] git commit: Fix up and flesh out javadocs.
Fix up and flesh out javadocs.
git-svn-id: https://svn.apache.org/repos/asf/logging/log4j/log4j2/trunk@1621024 13f79535-47bb-0310-9956-ffa450edef68
Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/28348cbc
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/28348cbc
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/28348cbc
Branch: refs/heads/messaging-module
Commit: 28348cbc743ef76a2f27589eebd152347d213b1f
Parents: 8a4cb72
Author: mattsicker <ma...@unknown>
Authored: Thu Aug 28 03:09:43 2014 +0000
Committer: mattsicker <ma...@unknown>
Committed: Thu Aug 28 03:09:43 2014 +0000
----------------------------------------------------------------------
.../java/org/apache/logging/log4j/Logger.java | 80 +++++++++++++-------
1 file changed, 53 insertions(+), 27 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/28348cbc/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java
----------------------------------------------------------------------
diff --git a/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java b/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java
index 35d475c..8e57f4b 100644
--- a/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java
+++ b/log4j-api/src/main/java/org/apache/logging/log4j/Logger.java
@@ -22,11 +22,31 @@ import org.apache.logging.log4j.message.MessageFactory;
/**
* This is the central interface in the log4j package. Most logging operations, except configuration, are done through
* this interface.
+ *
+ * <p>
+ * The canonical way to obtain a Logger for a class is through {@link LogManager#getLogger()}. Typically, each class
+ * gets its own Logger named after its fully qualified class name (the default Logger name when obtained through the
+ * {@link LogManager#getLogger()} method). Thus, the simplest way to use this would be like so:
+ * </p>
+ * <pre>
+ * public class MyClass {
+ * private static final Logger LOGGER = LogManager.getLogger();
+ * // ...
+ * }
+ * </pre>
+ * <p>
+ * For ease of filtering, searching, sorting, etc., it is generally a good idea to create Loggers for each class rather
+ * than sharing Loggers. Instead, {@link Marker Markers} should be used for shared, filterable identification.
+ * </p>
+ * <p>
+ * For service provider implementations, it is recommended to extend the
+ * {@link org.apache.logging.log4j.spi.AbstractLogger} class rather than implementing this interface directly.
+ * </p>
*/
public interface Logger {
/**
- * Logs an exception or error that has been caught.
+ * Logs an exception or error that has been caught to a specific logging level.
*
* @param level The logging Level.
* @param t The Throwable.
@@ -34,7 +54,10 @@ public interface Logger {
void catching(Level level, Throwable t);
/**
- * Logs an exception or error that has been caught.
+ * Logs an exception or error that has been caught. Normally, one may wish to provide additional information with
+ * an exception while logging it; in these cases, one would not use this method. In other cases where simply
+ * logging the fact that an exception was swallowed somewhere (e.g., at the top of the stack trace in a
+ * {@code main()} method), this method is ideal for it.
*
* @param t The Throwable.
*/
@@ -160,12 +183,21 @@ public interface Logger {
void debug(String message, Throwable t);
/**
- * Logs entry to a method.
+ * Logs entry to a method. Used when the method in question has no parameters or when the parameters should not be
+ * logged.
*/
void entry();
/**
- * Logs entry to a method.
+ * Logs entry to a method along with its parameters. For example,
+ * <pre>
+ * public void doSomething(String foo, int bar) {
+ * LOGGER.entry(foo, bar);
+ * // do something
+ * }
+ * </pre>
+ * <p>The use of methods such as this are more effective when combined with aspect-oriented programming or other
+ * bytecode manipulation tools. It can be rather tedious (and messy) to use this type of method manually.</p>
*
* @param params The parameters to the method.
* @doubt Use of varargs results in array creation which can be a substantial portion of no-op case. LogMF/LogSF
@@ -305,13 +337,15 @@ public interface Logger {
void error(String message, Throwable t);
/**
- * Logs exit from a method.
+ * Logs exit from a method. Used for methods that do not return anything.
*/
void exit();
/**
- * Logs exiting from a method with the result. This may be coded as <br />
- * return logger.exit(myResult);
+ * Logs exiting from a method with the result. This may be coded as:
+ * <pre>
+ * return LOGGER.exit(myResult);
+ * </pre>
*
* @param <R> The type of the parameter and object being returned.
* @param result The result being returned from the method call.
@@ -866,8 +900,10 @@ public interface Logger {
void printf(Level level, String format, Object... params);
/**
- * Logs an exception or error to be thrown. This may be coded as <br />
- * throw logger.throwing(debug, myException);
+ * Logs an exception or error to be thrown. This may be coded as:
+ * <pre>
+ * throw logger.throwing(Level.DEBUG, myException);
+ * </pre>
*
* @param <T> the Throwable type.
* @param level The logging Level.
@@ -877,8 +913,10 @@ public interface Logger {
<T extends Throwable> T throwing(Level level, T t);
/**
- * Logs an exception or error to be thrown. This may be coded as <br />
- * throw logger.throwing(myException);
+ * Logs an exception or error to be thrown. This may be coded as:
+ * <pre>
+ * throw logger.throwing(myException);
+ * </pre>
*
* @param <T> the Throwable type.
* @param t The Throwable.
@@ -914,14 +952,11 @@ public interface Logger {
/**
* Logs a message at the {@link Level#TRACE TRACE} level including the stack trace of the {@link Throwable}
* <code>t</code> passed as parameter.
- * <p/>
- * <p>
- * See {@link #debug(String)} form for more detailed information.
- * </p>
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
* @param t the exception to log, including its stack trace.
+ * @see #debug(String)
*/
void trace(Marker marker, Object message, Throwable t);
@@ -946,14 +981,11 @@ public interface Logger {
/**
* Logs a message at the {@link Level#TRACE TRACE} level including the stack trace of the {@link Throwable}
* <code>t</code> passed as parameter.
- * <p/>
- * <p>
- * See {@link #debug(String)} form for more detailed information.
- * </p>
*
* @param marker the marker data specific to this log statement
* @param message the message object to log.
* @param t the exception to log, including its stack trace.
+ * @see #debug(String)
*/
void trace(Marker marker, String message, Throwable t);
@@ -982,13 +1014,10 @@ public interface Logger {
/**
* Logs a message at the {@link Level#TRACE TRACE} level including the stack trace of the {@link Throwable}
* <code>t</code> passed as parameter.
- * <p/>
- * <p>
- * See {@link #debug(String)} form for more detailed information.
- * </p>
*
* @param message the message object to log.
* @param t the exception to log, including its stack trace.
+ * @see #debug(String)
*/
void trace(Object message, Throwable t);
@@ -1011,13 +1040,10 @@ public interface Logger {
/**
* Logs a message at the {@link Level#TRACE TRACE} level including the stack trace of the {@link Throwable}
* <code>t</code> passed as parameter.
- * <p/>
- * <p>
- * See {@link #debug(String)} form for more detailed information.
- * </p>
*
* @param message the message object to log.
* @param t the exception to log, including its stack trace.
+ * @see #debug(String)
*/
void trace(String message, Throwable t);