You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by rg...@apache.org on 2012/01/26 14:34:56 UTC
svn commit: r1236171 - in
/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers:
log4j2-api/src/main/java/org/apache/logging/log4j/Logger.java
log4j2-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java
src/site/xdoc/manual/api.xml
Author: rgoers
Date: Thu Jan 26 13:34:56 2012
New Revision: 1236171
URL: http://svn.apache.org/viewvc?rev=1236171&view=rev
Log:
Add return values to exit and throwing. Continue API documentation.
Modified:
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/Logger.java
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java
logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/Logger.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/Logger.java?rev=1236171&r1=1236170&r2=1236171&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/Logger.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/Logger.java Thu Jan 26 13:34:56 2012
@@ -48,23 +48,30 @@ public interface Logger {
void exit();
/**
- * Log exiting from a method with the result.
+ * Log exiting from a method with the result. This may be coded as <br />
+ * return logger.exit(myResult);
* @param result The result being returned from the method call.
+ * @return the result.
*/
- void exit(Object result);
+ <R> R exit(R result);
/**
- * Log an exception or error to be thrown.
+ * Log an exception or error to be thrown. This may be coded as <br />
+ * throw logger.throwing(myException);
+ *
* @param t The Throwable.
+ * @return the Throwable.
*/
- void throwing(Throwable t);
+ <T extends Throwable> T throwing(T t);
/**
- * Log an exception or error to be thrown.
+ * Log an exception or error to be thrown. This may be coded as <br />
+ * throw logger.throwing(debug, myException);
* @param level The logging Level.
* @param t The Throwable.
+ * @return the Throwable.
*/
- void throwing(Level level, Throwable t);
+ <T extends Throwable> T throwing(Level level, T t);
/**
* Log an exception or error that has been caught.
Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java?rev=1236171&r1=1236170&r2=1236171&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-api/src/main/java/org/apache/logging/log4j/spi/AbstractLogger.java Thu Jan 26 13:34:56 2012
@@ -93,22 +93,26 @@ public abstract class AbstractLogger imp
* Log exiting from a method with the result.
*
* @param result The result being returned from the method call.
+ * @return the Throwable.
*/
- public void exit(Object result) {
+ public <R> R exit(R result) {
if (isEnabled(Level.TRACE, EXIT_MARKER, (Object) null, null)) {
log(EXIT_MARKER, FQCN, Level.TRACE, exitMsg(result), null);
}
+ return result;
}
/**
* Log an exception or error to be thrown.
*
* @param t The Throwable.
+ * @return the Throwable.
*/
- public void throwing(Throwable t) {
+ public <T extends Throwable> T throwing(T t) {
if (isEnabled(Level.ERROR, THROWING_MARKER, (Object) null, null)) {
log(THROWING_MARKER, FQCN, Level.ERROR, new SimpleMessage("throwing"), t);
}
+ return t;
}
@@ -117,11 +121,13 @@ public abstract class AbstractLogger imp
*
* @param level The logging Level.
* @param t The Throwable.
+ * @return the Throwable.
*/
- public void throwing(Level level, Throwable t) {
+ public <T extends Throwable> T throwing(Level level, T t) {
if (isEnabled(level, THROWING_MARKER, (Object) null, null)) {
log(THROWING_MARKER, FQCN, level, new SimpleMessage("throwing"), t);
}
+ return t;
}
/**
Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml?rev=1236171&r1=1236170&r2=1236171&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/api.xml Thu Jan 26 13:34:56 2012
@@ -28,7 +28,49 @@
<subsection name="Overview">
<p>
The Log4Jj 2.0 API provides the interface that applications should code to and provides the
- adapter components required for implementers to create a logging implementation.
+ adapter components required for implementers to create a logging implementation. Although Log4j 2
+ is broken up between an API and an implementation, the primary purpose of doing so was not to
+ allow multiple implementations, although that is certainly possible, but to clearly define
+ what classes and methods are safe to use in "normal" application code.
+ </p>
+ <h4>Hello World!</h4>
+ <p>
+ No introduction would be complete without the customary Hello, World example. Here is ours. First,
+ a Logger with the name "HelloWorld" is obtained from the LogManager. Next, the logger is used to
+ write the "Hello, World!" message, however the message will be written only if the Logger is
+ configured to allow informational messages.
+ </p>
+ <source> import org.apache.logging.log4j.LogManager;
+ import org.apache.logging.log4j.Logger;
+
+ public class HelloWorld {
+ private static Logger logger = LogManager.getLogger("HelloWorld");
+ public static void main(String[] args) {
+ logger.info("Hello, World!");
+ }
+ }</source>
+ <p>
+ The output from the call to logger.info() will vary significantly depending on the configuration
+ used. See the <a href="./configuration.html">Configuration</a> section for more details.
+ </p>
+ <h4>Parameter Substitution</h4>
+ <p>
+ Frequently the purpose of logging is to provide information about what is happening in the system,
+ which requires including information about the objects being manipulated. In Log4j 1.x this could
+ be accomplished by doing:
+ </p>
+ <source> if (logger.isDebugEnabled()) {
+ logger.debug("Logging in user " + user.getName() + " with id " + user.getId());
+ }</source>
+ <p>
+ Doing this repeatedly has the effect of making the code feel like it is more about logging than the
+ actual task at hand. In addition, it results in the logging level being checked twice; once on the
+ call to isDebugEnabled and once on the debug method. A better alternative would be:
+ </p>
+ <source> logger.debug("Logging in user {} with id {}", user.getName(), user.getId());</source>
+ <p>
+ With the code above the logging level will only be checked once and the String construction will
+ only occur when debug logging is enabled.
</p>
</subsection>
<a name="Markers"/>