You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sis.apache.org by de...@apache.org on 2015/10/03 18:57:20 UTC
svn commit: r1706610 -
/sis/branches/JDK8/core/sis-utility/src/main/java/org/apache/sis/util/logging/Logging.java
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)