Package org.springframework.security.web.util

# Class ThrowableAnalyzer

java.lang.Object
org.springframework.security.web.util.ThrowableAnalyzer

public class ThrowableAnalyzer extends Object
Handler for analyzing `Throwable` instances. Can be subclassed to customize its behavior.

Since:
  2.0

## Field Summary

Fields
Modifier and Type
Field
Description
`static final ThrowableCauseExtractor`
`DEFAULT_EXTRACTOR`
Default extractor for `Throwable` instances.
`static final ThrowableCauseExtractor`
`INVOCATIONTARGET_EXTRACTOR`
Default extractor for `InvocationTargetException` instances.

## Constructor Summary

Constructors
Constructor
Description
`ThrowableAnalyzer()`
Creates a new `ThrowableAnalyzer` instance.

## Method Summary

Modifier and Type
Method
Description
`final Throwable[]`
`determineCauseChain(Throwable throwable)`
Determines the cause chain of the provided `Throwable`.
`final Throwable`
`getFirstThrowableOfType(Class<? extends Throwable> throwableType, Throwable[] chain)`
Returns the first throwable from the passed in array that is assignable to the provided type.
`protected void`
`initExtractorMap()`
Initializes associations between `Throwable`s and `ThrowableCauseExtractor`s.
`protected final void`
`registerExtractor(Class<? extends Throwable> throwableType, ThrowableCauseExtractor extractor)`
Registers a `ThrowableCauseExtractor` for the specified type.
`static void`
`verifyThrowableHierarchy(Throwable throwable, Class<? extends Throwable> expectedBaseType)`
Verifies that the provided throwable is a valid subclass of the provided type (or of the type itself).

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### DEFAULT_EXTRACTOR

public static final ThrowableCauseExtractor DEFAULT_EXTRACTOR
Default extractor for `Throwable` instances.

See Also:
  - `Throwable.getCause()`

### INVOCATIONTARGET_EXTRACTOR

public static final ThrowableCauseExtractor INVOCATIONTARGET_EXTRACTOR
Default extractor for `InvocationTargetException` instances.

See Also:
  - `InvocationTargetException.getTargetException()`

## Constructor Details

### ThrowableAnalyzer

public ThrowableAnalyzer()
Creates a new `ThrowableAnalyzer` instance.

## Method Details

### registerExtractor

protected final void registerExtractor(Class<? extends Throwable> throwableType, ThrowableCauseExtractor extractor)
Registers a `ThrowableCauseExtractor` for the specified type. Can be used in subclasses overriding `initExtractorMap()`.

Parameters:
  `throwableType` - the type (has to be a subclass of `Throwable`)
  `extractor` - the associated `ThrowableCauseExtractor` (not `null`)
Throws:
  `IllegalArgumentException` - if one of the arguments is invalid

### initExtractorMap

protected void initExtractorMap()
Initializes associations between `Throwable`s and `ThrowableCauseExtractor`s. The default implementation performs the following registrations:

- `DEFAULT_EXTRACTOR` for `Throwable`
- `INVOCATIONTARGET_EXTRACTOR` for `InvocationTargetException`

Subclasses overriding this method are encouraged to invoke the super method to perform the default registrations. They can register additional extractors as required.

Note: An extractor registered for a specific type is applicable for that type and all subtypes thereof. However, extractors registered to more specific types are guaranteed to be resolved first. So in the default case InvocationTargetExceptions will be handled by `INVOCATIONTARGET_EXTRACTOR` while all other throwables are handled by `DEFAULT_EXTRACTOR`.

See Also:
  - `registerExtractor(Class, ThrowableCauseExtractor)`

### determineCauseChain

public final Throwable[] determineCauseChain(Throwable throwable)
Determines the cause chain of the provided `Throwable`. The returned array contains all throwables extracted from the stacktrace, using the registered `extractors`. The elements of the array are ordered: The first element is the passed in throwable itself. The following elements appear in their order downward the stacktrace.

Note: If no `ThrowableCauseExtractor` is registered for this instance then the returned array will always only contain the passed in throwable.

Parameters:
  `throwable` - the `Throwable` to analyze
Returns:
  an array of all determined throwables from the stacktrace
Throws:
  `IllegalArgumentException` - if the throwable is `null`
See Also:
  - `initExtractorMap()`

### getFirstThrowableOfType

public final Throwable getFirstThrowableOfType(Class<? extends Throwable> throwableType, Throwable[] chain)
Returns the first throwable from the passed in array that is assignable to the provided type. A returned instance is safe to be cast to the specified type.

If the passed in array is null or empty this method returns `null`.

Parameters:
  `throwableType` - the type to look for
  `chain` - the array (will be processed in element order)
Returns:
  the found `Throwable`, `null` if not found
Throws:
  `IllegalArgumentException` - if the provided type is `null` or no subclass of `Throwable`

### verifyThrowableHierarchy

public static void verifyThrowableHierarchy(Throwable throwable, Class<? extends Throwable> expectedBaseType)
Verifies that the provided throwable is a valid subclass of the provided type (or of the type itself). If `expectdBaseType` is `null`, no check will be performed.

Can be used for verification purposes in implementations of `extractors`.

Parameters:
  `throwable` - the `Throwable` to check
  `expectedBaseType` - the type to check against
Throws:
  `IllegalArgumentException` - if `throwable` is either `null` or its type is not assignable to `expectedBaseType`