sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject svn commit: r1706610 - /sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/Logging.java
Date Sat, 03 Oct 2015 16:57:20 GMT
Author: desruisseaux
Date: Sat Oct  3 16:57:19 2015
New Revision: 1706610

URL: http://svn.apache.org/viewvc?rev=1706610&view=rev
Log:
Javadoc update, and deprecate a convenience method which is not worth its weight.

Modified:
    sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/Logging.java

Modified: sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/Logging.java
URL: http://svn.apache.org/viewvc/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/Logging.java?rev=1706610&r1=1706609&r2=1706610&view=diff
==============================================================================
--- sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/Logging.java
[UTF-8] (original)
+++ sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/Logging.java
[UTF-8] Sat Oct  3 16:57:19 2015
@@ -208,34 +208,30 @@ public final class Logging extends Stati
     }
 
     /**
-     * Invoked when an unexpected error occurs. This method logs a message at {@link Level#WARNING}
to the
+     * Invoked when an unexpected error occurred. This method logs a message at {@link Level#WARNING}
to the
      * specified logger. The originating class name and method name are inferred from the
error stack trace,
      * using the first {@linkplain StackTraceElement stack trace element} for which the class
name is inside
      * a package or sub-package of the logger name.
      *
-     * <div class="note"><b>Example:</b>
-     * if the logger name is {@code "org.apache.sis.image"}, then this method will uses the
first stack
-     * trace element where the fully qualified class name starts with {@code "org.apache.sis.image"}
or
-     * {@code "org.apache.sis.image.io"}, but not {@code "org.apache.sis.imageio"}.</div>
+     * @param  logger Where to log the error, or {@code null} for inferring a default value
from other arguments.
+     * @param  error  The error that occurred, or {@code null} if none.
+     * @return {@code true} if the error has been logged, or {@code false} if the given {@code
error}
+     *         was null or if the logger does not log anything at {@link Level#WARNING}.
      *
-     * @param  logger Where to log the error.
-     * @param  error  The error that occurred.
-     * @return {@code true} if the error has been logged, or {@code false} if the logger
-     *         does not log anything at {@link Level#WARNING}.
+     * @deprecated Use {@link #unexpectedException(Logger, Class, String, Throwable)} instead.
      */
+    @Deprecated
     public static boolean unexpectedException(final Logger logger, final Throwable error)
{
         return unexpectedException(logger, null, null, error, Level.WARNING);
     }
 
     /**
-     * Invoked when an unexpected error occurs. This method logs a message at {@link Level#WARNING}
+     * Invoked when an unexpected error occurred. This method logs a message at {@link Level#WARNING}
      * to the specified logger. The originating class name and method name can optionally
be specified.
-     * If any of them is {@code null}, then it will be inferred from the error stack trace
as in
-     * {@link #unexpectedException(Logger, Throwable)}.
-     *
-     * <p>Explicit value for class and method names are sometime preferred to automatic
-     * inference for the following reasons:</p>
+     * If any of them is {@code null}, then it will be inferred from the error stack trace
as described below.
      *
+     * <div class="note"><b>Recommended usage:</b>
+     * explicit value for class and method names are preferred to automatic inference for
the following reasons:
      * <ul>
      *   <li>Automatic inference is not 100% reliable, since the Java Virtual Machine
      *       is free to omit stack frame in optimized code.</li>
@@ -244,14 +240,23 @@ public final class Logging extends Stati
      *       since the user is not expected to know anything about the existence of the
      *       private method. If a developer really want to know about the private method,
      *       the stack trace is still available anyway.</li>
-     * </ul>
+     * </ul></div>
+     *
+     * If the {@code classe} or {@code method} arguments are null, then the originating class
name and method name
+     * are inferred from the given {@code error} using the first {@linkplain StackTraceElement
stack trace element}
+     * for which the class name is inside a package or sub-package of the same name than
the logger name.
+     *
+     * <div class="note"><b>Example:</b>
+     * if the logger name is {@code "org.apache.sis.image"}, then this method will uses the
first stack
+     * trace element where the fully qualified class name starts with {@code "org.apache.sis.image"}
or
+     * {@code "org.apache.sis.image.io"}, but not {@code "org.apache.sis.imageio"}.</div>
      *
-     * @param logger  Where to log the error.
-     * @param classe  The class where the error occurred, or {@code null}.
-     * @param method  The method where the error occurred, or {@code null}.
-     * @param error   The error.
-     * @return {@code true} if the error has been logged, or {@code false} if the logger
-     *         does not log anything at {@link Level#WARNING}.
+     * @param logger  Where to log the error, or {@code null} for inferring a default value
from other arguments.
+     * @param classe  The class where the error occurred, or {@code null} for inferring a
default value from other arguments.
+     * @param method  The method where the error occurred, or {@code null} for inferring
a default value from other arguments.
+     * @param error   The error, or {@code null} if none.
+     * @return {@code true} if the error has been logged, or {@code false} if the given {@code
error}
+     *         was null or if the logger does not log anything at {@link Level#WARNING}.
      *
      * @see #recoverableException(Logger, Class, String, Throwable)
      * @see #severeException(Logger, Class, String, Throwable)
@@ -266,13 +271,13 @@ public final class Logging extends Stati
     /**
      * Implementation of {@link #unexpectedException(Logger, Class, String, Throwable)}.
      *
-     * @param logger  Where to log the error, or {@code null}.
-     * @param classe  The fully qualified class name where the error occurred, or {@code
null}.
-     * @param method  The method where the error occurred, or {@code null}.
-     * @param error   The error.
+     * @param logger  Where to log the error, or {@code null} for inferring a default value
from other arguments.
+     * @param classe  The fully qualified class name where the error occurred, or {@code
null} for inferring a default value from other arguments.
+     * @param method  The method where the error occurred, or {@code null} for inferring
a default value from other arguments.
+     * @param error   The error, or {@code null} if none.
      * @param level   The logging level.
-     * @return {@code true} if the error has been logged, or {@code false} if the logger
-     *         does not log anything at the specified level.
+     * @return {@code true} if the error has been logged, or {@code false} if the given {@code
error}
+     *         was null or if the logger does not log anything at the specified level.
      */
     private static boolean unexpectedException(Logger logger, String classe, String method,
                                                final Throwable error, final Level level)
@@ -294,7 +299,7 @@ public final class Logging extends Stati
         /*
          * Loggeable, so complete the null argument from the stack trace if we can.
          */
-        if (logger==null || classe==null || method==null) {
+        if (logger == null || classe == null || method == null) {
             String paquet = (logger != null) ? logger.getName() : null;
             for (final StackTraceElement element : error.getStackTrace()) {
                 /*
@@ -398,12 +403,12 @@ public final class Logging extends Stati
      * {@code jre/lib/logging.properties} file is illegal, then {@link MonolineFormatter}
will log
      * this problem and use a default time pattern.</div>
      *
-     * @param logger  Where to log the error.
-     * @param classe  The class where the error occurred.
-     * @param method  The method name where the error occurred.
-     * @param error   The error.
-     * @return {@code true} if the error has been logged, or {@code false} if the logger
-     *         does not log anything at {@link Level#CONFIG}.
+     * @param logger  Where to log the error, or {@code null} for inferring a default value
from other arguments.
+     * @param classe  The class where the error occurred, or {@code null} for inferring a
default value from other arguments.
+     * @param method  The method name where the error occurred, or {@code null} for inferring
a default value from other arguments.
+     * @param error   The error, or {@code null} if none.
+     * @return {@code true} if the error has been logged, or {@code false} if the given {@code
error}
+     *         was null or if the logger does not log anything at {@link Level#CONFIG}.
      *
      * @see #unexpectedException(Logger, Class, String, Throwable)
      */
@@ -413,16 +418,16 @@ public final class Logging extends Stati
     }
 
     /**
-     * Invoked when a recoverable error occurs. This method is similar to
+     * Invoked when a recoverable error occurred. This method is similar to
      * {@link #unexpectedException(Logger,Class,String,Throwable) unexpectedException(…)}
      * except that it does not log the stack trace and uses a lower logging level.
      *
-     * @param logger  Where to log the error.
-     * @param classe  The class where the error occurred.
-     * @param method  The method name where the error occurred.
-     * @param error   The error.
-     * @return {@code true} if the error has been logged, or {@code false} if the logger
-     *         does not log anything at {@link Level#FINE}.
+     * @param logger  Where to log the error, or {@code null} for inferring a default value
from other arguments.
+     * @param classe  The class where the error occurred, or {@code null} for inferring a
default value from other arguments.
+     * @param method  The method name where the error occurred, or {@code null} for inferring
a default value from other arguments.
+     * @param error   The error, or {@code null} if none.
+     * @return {@code true} if the error has been logged, or {@code false} if the given {@code
error}
+     *         was null or if the logger does not log anything at {@link Level#FINE}.
      *
      * @see #unexpectedException(Logger, Class, String, Throwable)
      * @see #severeException(Logger, Class, String, Throwable)
@@ -435,16 +440,16 @@ public final class Logging extends Stati
     }
 
     /**
-     * Invoked when a severe error occurs. This method is similar to
+     * Invoked when a severe error occurred. This method is similar to
      * {@link #unexpectedException(Logger,Class,String,Throwable) unexpectedException}
      * except that it logs the message at the {@link Level#SEVERE SEVERE} level.
      *
-     * @param logger  Where to log the error.
-     * @param classe  The class where the error occurred.
-     * @param method  The method name where the error occurred.
-     * @param error   The error.
-     * @return {@code true} if the error has been logged, or {@code false} if the logger
-     *         does not log anything at {@link Level#SEVERE}.
+     * @param logger  Where to log the error, or {@code null} for inferring a default value
from other arguments.
+     * @param classe  The class where the error occurred, or {@code null} for inferring a
default value from other arguments.
+     * @param method  The method name where the error occurred, or {@code null} for inferring
a default value from other arguments.
+     * @param error   The error, or {@code null} if none.
+     * @return {@code true} if the error has been logged, or {@code false} if the given {@code
error}
+     *         was null or if the logger does not log anything at {@link Level#SEVERE}.
      *
      * @see #unexpectedException(Logger, Class, String, Throwable)
      * @see #recoverableException(Logger, Class, String, Throwable)



Mime
View raw message