logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgo...@apache.org
Subject 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
Date Thu, 26 Jan 2012 13:34:56 GMT
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"/>



Mime
View raw message