diff --git a/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java b/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java index e3dbd1f9e..0041341c3 100644 --- a/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java +++ b/src/main/java/org/apache/commons/lang3/exception/ExceptionUtils.java @@ -32,8 +32,8 @@ import org.apache.commons.lang3.ClassUtils; import org.apache.commons.lang3.StringUtils; /** - *
Provides utilities for manipulating and examining - * {@code Throwable} objects.
+ * Provides utilities for manipulating and examining + * {@code Throwable} objects. * * @since 1.0 */ @@ -42,7 +42,7 @@ public class ExceptionUtils { private static final int NOT_FOUND = -1; /** - *The names of methods commonly used to access a wrapped exception.
+ * The names of methods commonly used to access a wrapped exception. */ // TODO: Remove in Lang 4.0 private static final String[] CAUSE_METHOD_NAMES = { @@ -61,15 +61,15 @@ public class ExceptionUtils { }; /** - *Used when printing stack frames to denote the start of a - * wrapped exception.
+ * Used when printing stack frames to denote the start of a + * wrapped exception. * *Package private for accessibility by test suite.
*/ static final String WRAPPED_MARKER = " [wrapped] "; /** - *Introspects the {@code Throwable} to obtain the cause.
+ * Introspects the {@code Throwable} to obtain the cause. * *The method searches for methods with specific names that return a * {@code Throwable} object. This will pick up most wrapping exceptions, @@ -101,7 +101,7 @@ public class ExceptionUtils { } /** - *
Introspects the {@code Throwable} to obtain the cause.
+ * Introspects the {@code Throwable} to obtain the cause. * *A {@code null} set of method names means use the default set. * A {@code null} in the set of method names will be ignored.
@@ -141,7 +141,7 @@ public class ExceptionUtils { } /** - *Finds a {@code Throwable} by method name.
+ * Gets a {@code Throwable} by method name. * * @param throwable the exception to examine * @param methodName the name of the method to find and invoke @@ -167,7 +167,7 @@ public class ExceptionUtils { } /** - *Returns the default names used when searching for the cause of an exception.
+ * Gets the default names used when searching for the cause of an exception. * *This may be modified and used in the overloaded getCause(Throwable, String[]) method.
* @@ -185,6 +185,7 @@ public class ExceptionUtils { ** The message returned is of the form * {ClassNameWithoutPackage}: {ThrowableMessage} + *
* * @param th the throwable to get a message for, null returns empty string * @return the message, non-null @@ -200,7 +201,7 @@ public class ExceptionUtils { } /** - *Introspects the {@code Throwable} to obtain the root cause.
+ * Introspects the {@code Throwable} to obtain the root cause. * *This method walks through the exception chain to the last element, * "root" of the tree, using {@link Throwable#getCause()}, and @@ -226,6 +227,7 @@ public class ExceptionUtils { *
* The message returned is of the form * {ClassNameWithoutPackage}: {ThrowableMessage} + *
* * @param th the throwable to get a message for, null returns empty string * @return the message, non-null @@ -238,8 +240,8 @@ public class ExceptionUtils { } /** - *Creates a compact stack trace for the root cause of the supplied - * {@code Throwable}.
+ * Gets a compact stack trace for the root cause of the supplied + * {@code Throwable}. * *The output of this method is consistent across JDK versions. * It consists of the root exception followed by each of its wrapping @@ -275,9 +277,9 @@ public class ExceptionUtils { } /** - *
Produces a {@code List} of stack frames - the message + * Gets a {@code List} of stack frames - the message * is not included. Only the trace of the specified exception is - * returned, any caused by trace is stripped.
+ * returned, any caused by trace is stripped. * *This works in most cases - it will only fail if the exception * message contains a line that starts with: @@ -307,7 +309,7 @@ public class ExceptionUtils { } /** - *
Returns an array where each element is a line from the argument.
+ * Gets an array where each element is a line from the argument. * *The end of line is determined by the value of {@link System#lineSeparator()}.
* @@ -325,9 +327,9 @@ public class ExceptionUtils { } /** - *Captures the stack trace associated with the specified + * Gets the stack trace associated with the specified * {@code Throwable} object, decomposing it into a list of - * stack frames.
+ * stack frames. * *The result of this method vary by JDK version as this method * uses {@link Throwable#printStackTrace(java.io.PrintWriter)}. @@ -345,7 +347,7 @@ public class ExceptionUtils { } /** - *
Gets the stack trace from a Throwable as a String.
+ * Gets the stack trace from a Throwable as a String. * *The result of this method vary by JDK version as this method * uses {@link Throwable#printStackTrace(java.io.PrintWriter)}. @@ -364,8 +366,8 @@ public class ExceptionUtils { } /** - *
Counts the number of {@code Throwable} objects in the - * exception chain.
+ * Gets a count of the number of {@code Throwable} objects in the + * exception chain. * *A throwable without cause will return {@code 1}. * A throwable with one cause will return {@code 2} and so on. @@ -384,8 +386,8 @@ public class ExceptionUtils { } /** - *
Returns the list of {@code Throwable} objects in the - * exception chain.
+ * Gets the list of {@code Throwable} objects in the + * exception chain. * *A throwable without cause will return a list containing * one element - the input throwable. @@ -412,8 +414,8 @@ public class ExceptionUtils { } /** - *
Returns the list of {@code Throwable} objects in the - * exception chain.
+ * Gets the list of {@code Throwable} objects in the + * exception chain. * *A throwable without cause will return an array containing * one element - the input throwable. @@ -436,7 +438,7 @@ public class ExceptionUtils { } /** - * Does the throwable's causal chain have an immediate or wrapped exception + * Tests if the throwable's causal chain have an immediate or wrapped exception * of the given type? * * @param chain @@ -457,7 +459,7 @@ public class ExceptionUtils { } /** - *
Worker method for the {@code indexOfType} methods.
+ * Worker method for the {@code indexOfType} methods. * * @param throwable the throwable to inspect, may be null * @param type the type to search for, subclasses match, null returns -1 @@ -495,10 +497,10 @@ public class ExceptionUtils { } /** - *Returns the (zero-based) index of the first {@code Throwable} + * Returns the (zero-based) index of the first {@code Throwable} * that matches the specified class (exactly) in the exception chain. * Subclasses of the specified class do not match - see - * {@link #indexOfType(Throwable, Class)} for the opposite.
+ * {@link #indexOfType(Throwable, Class)} for the opposite. * *A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -513,11 +515,11 @@ public class ExceptionUtils { } /** - *
Returns the (zero-based) index of the first {@code Throwable} + * Returns the (zero-based) index of the first {@code Throwable} * that matches the specified type in the exception chain from * a specified index. * Subclasses of the specified class do not match - see - * {@link #indexOfType(Throwable, Class, int)} for the opposite.
+ * {@link #indexOfType(Throwable, Class, int)} for the opposite. * *A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -536,10 +538,10 @@ public class ExceptionUtils { } /** - *
Returns the (zero-based) index of the first {@code Throwable} + * Returns the (zero-based) index of the first {@code Throwable} * that matches the specified class or subclass in the exception chain. * Subclasses of the specified class do match - see - * {@link #indexOfThrowable(Throwable, Class)} for the opposite.
+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite. * *A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -555,11 +557,11 @@ public class ExceptionUtils { } /** - *
Returns the (zero-based) index of the first {@code Throwable} + * Returns the (zero-based) index of the first {@code Throwable} * that matches the specified type in the exception chain from * a specified index. * Subclasses of the specified class do match - see - * {@link #indexOfThrowable(Throwable, Class)} for the opposite.
+ * {@link #indexOfThrowable(Throwable, Class)} for the opposite. * *A {@code null} throwable returns {@code -1}. * A {@code null} type returns {@code -1}. @@ -579,8 +581,8 @@ public class ExceptionUtils { } /** - *
Prints a compact stack trace for the root cause of a throwable - * to {@code System.err}.
+ * Prints a compact stack trace for the root cause of a throwable + * to {@code System.err}. * *The compact stack trace starts with the root cause and prints * stack frames up to the place where it was caught and wrapped. @@ -601,7 +603,7 @@ public class ExceptionUtils { } /** - *
Prints a compact stack trace for the root cause of a throwable.
+ * Prints a compact stack trace for the root cause of a throwable. * *The compact stack trace starts with the root cause and prints * stack frames up to the place where it was caught and wrapped. @@ -633,7 +635,7 @@ public class ExceptionUtils { } /** - *
Prints a compact stack trace for the root cause of a throwable.
+ * Prints a compact stack trace for the root cause of a throwable. * *The compact stack trace starts with the root cause and prints * stack frames up to the place where it was caught and wrapped. @@ -665,7 +667,7 @@ public class ExceptionUtils { } /** - *
Removes common frames from the cause trace given the two stack traces.
+ * Removes common frames from the cause trace given the two stack traces. * * @param causeFrames stack trace of a cause throwable * @param wrapperFrames stack trace of a wrapper throwable @@ -692,14 +694,15 @@ public class ExceptionUtils { } /** - * Throw a checked exception without adding the exception to the throws + * Throws a checked exception without adding the exception to the throws * clause of the calling method. This method prevents throws clause * pollution and reduces the clutter of "Caused by" exceptions in the * stacktrace. *
* The use of this technique may be controversial, but exceedingly useful to
* library developers.
- *
+ *
* public int propagateExample { // note that there is no throws clause * try { * return invocation(); // throws IOException @@ -707,11 +710,12 @@ public class ExceptionUtils { * return ExceptionUtils.rethrow(e); // propagates a checked exception * } * } - * + **
* This is an alternative to the more conservative approach of wrapping the
* checked exception in a RuntimeException:
- *
+ *
* public int wrapExample { // note that there is no throws clause * try { * return invocation(); // throws IOException @@ -723,7 +727,7 @@ public class ExceptionUtils { * throw new UndeclaredThrowableException(e); // wraps a checked exception * } * } - * + **
* One downside to using this approach is that the java compiler will not * allow invoking code to specify a checked exception in a catch clause @@ -735,6 +739,7 @@ public class ExceptionUtils { * techniques are required when interacting with non-java jvm code such as * Jython, Scala, or Groovy, since these languages do not consider any * exceptions as checked. + *
* * @param throwable * The throwable to rethrow. @@ -752,7 +757,7 @@ public class ExceptionUtils { } /** - *Worker method for the {@code throwableOfType} methods.
+ * Worker method for the {@code throwableOfType} methods. * * @paramReturns the first {@code Throwable} + * Returns the first {@code Throwable} * that matches the specified class (exactly) in the exception chain. * Subclasses of the specified class do not match - see - * {@link #throwableOfType(Throwable, Class)} for the opposite.
+ * {@link #throwableOfType(Throwable, Class)} for the opposite. * *A {@code null} throwable returns {@code null}. * A {@code null} type returns {@code null}. @@ -811,11 +816,11 @@ public class ExceptionUtils { } /** - *
Returns the first {@code Throwable} + * Returns the first {@code Throwable} * that matches the specified type in the exception chain from * a specified index. * Subclasses of the specified class do not match - see - * {@link #throwableOfType(Throwable, Class, int)} for the opposite.
+ * {@link #throwableOfType(Throwable, Class, int)} for the opposite. * *A {@code null} throwable returns {@code null}. * A {@code null} type returns {@code null}. @@ -836,10 +841,10 @@ public class ExceptionUtils { } /** - *
Returns the throwable of the first {@code Throwable} + * Returns the throwable of the first {@code Throwable} * that matches the specified class or subclass in the exception chain. * Subclasses of the specified class do match - see - * {@link #throwableOfThrowable(Throwable, Class)} for the opposite..
+ * {@link #throwableOfThrowable(Throwable, Class)} for the opposite. * *A {@code null} throwable returns {@code null}. * A {@code null} type returns {@code null}. @@ -856,11 +861,11 @@ public class ExceptionUtils { } /** - *
Returns the first {@code Throwable} + * Returns the first {@code Throwable} * that matches the specified type in the exception chain from * a specified index. * Subclasses of the specified class do match - see - * {@link #throwableOfThrowable(Throwable, Class)} for the opposite.
+ * {@link #throwableOfThrowable(Throwable, Class)} for the opposite. * *A {@code null} throwable returns {@code null}. * A {@code null} type returns {@code null}. @@ -881,8 +886,8 @@ public class ExceptionUtils { } /** - * Claim a Throwable is another Exception type using type erasure. This - * hides a checked exception from the java compiler, allowing a checked + * Claims a Throwable is another Exception type using type erasure. This + * hides a checked exception from the Java compiler, allowing a checked * exception to be thrown without having the exception in the method's throw * clause. */ @@ -892,7 +897,7 @@ public class ExceptionUtils { } /** - * Throw a checked exception without adding the exception to the throws + * Throws a checked exception without adding the exception to the throws * clause of the calling method. For checked exceptions, this method throws * an UndeclaredThrowableException wrapping the checked exception. For * Errors and RuntimeExceptions, the original exception is rethrown. @@ -900,6 +905,7 @@ public class ExceptionUtils { * The downside to using this approach is that invoking code which needs to * handle specific checked exceptions must sniff up the exception chain to * determine if the caught exception was caused by the checked exception. + *
* * @param throwable * The throwable to rethrow. @@ -923,10 +929,8 @@ public class ExceptionUtils { } /** - ** Public constructor allows an instance of {@code ExceptionUtils} to be created, although that is not * normally necessary. - *
*/ public ExceptionUtils() { }