Javadoc: Tagging the first sentence as a paragraph is redundant.
- Use pre tags instead of code tags for in-line code examples. - Close HTML tags. - Use "Gets..." for most getters.
This commit is contained in:
Gary Gregory
parent
b82f96ecbb
commit
46094be47e
|
|
@ -32,8 +32,8 @@ import org.apache.commons.lang3.ClassUtils;
|
|||
import org.apache.commons.lang3.StringUtils;
|
||||
|
||||
/**
|
||||
* <p>Provides utilities for manipulating and examining
|
||||
* {@code Throwable} objects.</p>
|
||||
* 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;
|
||||
|
||||
/**
|
||||
* <p>The names of methods commonly used to access a wrapped exception.</p>
|
||||
* 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 {
|
|||
};
|
||||
|
||||
/**
|
||||
* <p>Used when printing stack frames to denote the start of a
|
||||
* wrapped exception.</p>
|
||||
* Used when printing stack frames to denote the start of a
|
||||
* wrapped exception.
|
||||
*
|
||||
* <p>Package private for accessibility by test suite.</p>
|
||||
*/
|
||||
static final String WRAPPED_MARKER = " [wrapped] ";
|
||||
|
||||
/**
|
||||
* <p>Introspects the {@code Throwable} to obtain the cause.</p>
|
||||
* Introspects the {@code Throwable} to obtain the cause.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Introspects the {@code Throwable} to obtain the cause.</p>
|
||||
* Introspects the {@code Throwable} to obtain the cause.
|
||||
*
|
||||
* <p>A {@code null} set of method names means use the default set.
|
||||
* A {@code null} in the set of method names will be ignored.</p>
|
||||
|
|
@ -141,7 +141,7 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Finds a {@code Throwable} by method name.</p>
|
||||
* 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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Returns the default names used when searching for the cause of an exception.</p>
|
||||
* Gets the default names used when searching for the cause of an exception.
|
||||
*
|
||||
* <p>This may be modified and used in the overloaded getCause(Throwable, String[]) method.</p>
|
||||
*
|
||||
|
|
@ -185,6 +185,7 @@ public class ExceptionUtils {
|
|||
* <p>
|
||||
* The message returned is of the form
|
||||
* {ClassNameWithoutPackage}: {ThrowableMessage}
|
||||
* </p>
|
||||
*
|
||||
* @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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Introspects the {@code Throwable} to obtain the root cause.</p>
|
||||
* Introspects the {@code Throwable} to obtain the root cause.
|
||||
*
|
||||
* <p>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 {
|
|||
* <p>
|
||||
* The message returned is of the form
|
||||
* {ClassNameWithoutPackage}: {ThrowableMessage}
|
||||
* </p>
|
||||
*
|
||||
* @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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Creates a compact stack trace for the root cause of the supplied
|
||||
* {@code Throwable}.</p>
|
||||
* Gets a compact stack trace for the root cause of the supplied
|
||||
* {@code Throwable}.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* returned, any caused by trace is stripped.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Returns an array where each element is a line from the argument.</p>
|
||||
* Gets an array where each element is a line from the argument.
|
||||
*
|
||||
* <p>The end of line is determined by the value of {@link System#lineSeparator()}.</p>
|
||||
*
|
||||
|
|
@ -325,9 +327,9 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* stack frames.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Gets the stack trace from a Throwable as a String.</p>
|
||||
* Gets the stack trace from a Throwable as a String.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Counts the number of {@code Throwable} objects in the
|
||||
* exception chain.</p>
|
||||
* Gets a count of the number of {@code Throwable} objects in the
|
||||
* exception chain.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Returns the list of {@code Throwable} objects in the
|
||||
* exception chain.</p>
|
||||
* Gets the list of {@code Throwable} objects in the
|
||||
* exception chain.
|
||||
*
|
||||
* <p>A throwable without cause will return a list containing
|
||||
* one element - the input throwable.
|
||||
|
|
@ -412,8 +414,8 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Returns the list of {@code Throwable} objects in the
|
||||
* exception chain.</p>
|
||||
* Gets the list of {@code Throwable} objects in the
|
||||
* exception chain.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Worker method for the {@code indexOfType} methods.</p>
|
||||
* 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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* {@link #indexOfType(Throwable, Class)} for the opposite.
|
||||
*
|
||||
* <p>A {@code null} throwable returns {@code -1}.
|
||||
* A {@code null} type returns {@code -1}.
|
||||
|
|
@ -513,11 +515,11 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* {@link #indexOfType(Throwable, Class, int)} for the opposite.
|
||||
*
|
||||
* <p>A {@code null} throwable returns {@code -1}.
|
||||
* A {@code null} type returns {@code -1}.
|
||||
|
|
@ -536,10 +538,10 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* {@link #indexOfThrowable(Throwable, Class)} for the opposite.
|
||||
*
|
||||
* <p>A {@code null} throwable returns {@code -1}.
|
||||
* A {@code null} type returns {@code -1}.
|
||||
|
|
@ -555,11 +557,11 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* {@link #indexOfThrowable(Throwable, Class)} for the opposite.
|
||||
*
|
||||
* <p>A {@code null} throwable returns {@code -1}.
|
||||
* A {@code null} type returns {@code -1}.
|
||||
|
|
@ -579,8 +581,8 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Prints a compact stack trace for the root cause of a throwable
|
||||
* to {@code System.err}.</p>
|
||||
* Prints a compact stack trace for the root cause of a throwable
|
||||
* to {@code System.err}.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Prints a compact stack trace for the root cause of a throwable.</p>
|
||||
* Prints a compact stack trace for the root cause of a throwable.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Prints a compact stack trace for the root cause of a throwable.</p>
|
||||
* Prints a compact stack trace for the root cause of a throwable.
|
||||
*
|
||||
* <p>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 {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Removes common frames from the cause trace given the two stack traces.</p>
|
||||
* 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.
|
||||
* <p>
|
||||
* The use of this technique may be controversial, but exceedingly useful to
|
||||
* library developers.
|
||||
* <code>
|
||||
* </p>
|
||||
* <pre>
|
||||
* 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
|
||||
* }
|
||||
* }
|
||||
* </code>
|
||||
* </pre>
|
||||
* <p>
|
||||
* This is an alternative to the more conservative approach of wrapping the
|
||||
* checked exception in a RuntimeException:
|
||||
* <code>
|
||||
* </p>
|
||||
* <pre>
|
||||
* 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
|
||||
* }
|
||||
* }
|
||||
* </code>
|
||||
* </pre>
|
||||
* <p>
|
||||
* 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.
|
||||
* </p>
|
||||
*
|
||||
* @param throwable
|
||||
* The throwable to rethrow.
|
||||
|
|
@ -752,7 +757,7 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Worker method for the {@code throwableOfType} methods.</p>
|
||||
* Worker method for the {@code throwableOfType} methods.
|
||||
*
|
||||
* @param <T> the type of Throwable you are searching.
|
||||
* @param throwable the throwable to inspect, may be null
|
||||
|
|
@ -791,10 +796,10 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>Returns 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.</p>
|
||||
* {@link #throwableOfType(Throwable, Class)} for the opposite.
|
||||
*
|
||||
* <p>A {@code null} throwable returns {@code null}.
|
||||
* A {@code null} type returns {@code null}.
|
||||
|
|
@ -811,11 +816,11 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* {@link #throwableOfType(Throwable, Class, int)} for the opposite.
|
||||
*
|
||||
* <p>A {@code null} throwable returns {@code null}.
|
||||
* A {@code null} type returns {@code null}.
|
||||
|
|
@ -836,10 +841,10 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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..</p>
|
||||
* {@link #throwableOfThrowable(Throwable, Class)} for the opposite.
|
||||
*
|
||||
* <p>A {@code null} throwable returns {@code null}.
|
||||
* A {@code null} type returns {@code null}.
|
||||
|
|
@ -856,11 +861,11 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>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.</p>
|
||||
* {@link #throwableOfThrowable(Throwable, Class)} for the opposite.
|
||||
*
|
||||
* <p>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.
|
||||
* </p>
|
||||
*
|
||||
* @param throwable
|
||||
* The throwable to rethrow.
|
||||
|
|
@ -923,10 +929,8 @@ public class ExceptionUtils {
|
|||
}
|
||||
|
||||
/**
|
||||
* <p>
|
||||
* Public constructor allows an instance of {@code ExceptionUtils} to be created, although that is not
|
||||
* normally necessary.
|
||||
* </p>
|
||||
*/
|
||||
public ExceptionUtils() {
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue