org.apache.brooklyn.util.exceptions

Class Exceptions

java.lang.Object

org.apache.brooklyn.util.exceptions.Exceptions

public class Exceptions
extends java.lang.Object

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Exceptions.CollapseTextSupplier

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_COLLAPSE_RECURSIVE_DEPTH

Constructor Summary

Constructors

Constructor and Description
Exceptions()

Method Summary

Modifier and Type	Method and Description
static java.lang.Throwable	collapse(java.lang.Throwable source) creates (but does not throw) a new PropagatedRuntimeException whose message and cause are taken from the first _interesting_ element in the source
static java.lang.Throwable	collapse(java.lang.Throwable source, boolean collapseCausalChain) creates (but does not throw) a new PropagatedRuntimeException whose message is taken from the first _interesting_ element in the source, and optionally also the causal chain
static java.lang.Throwable	collapseIncludingAllCausalMessages(java.lang.Throwable source) as collapse(Throwable) but includes causal messages in the message as per collapseTextIncludingAllCausalMessages(Throwable); use with care (limit once) as repeated usage can result in multiple copies of the same message
static java.lang.String	collapseText(java.lang.Throwable t) like collapse(Throwable) but returning a one-line message suitable for logging without traces
static java.lang.String	collapseTextIncludingAllCausalMessages(java.lang.Throwable t) normally collapseText(Throwable) will stop following causal chains when encountering an interesting exception with a message; this variant will continue to follow such causal chains, showing all messages.
static java.lang.String	collapseTextInContext(java.lang.Throwable t, java.lang.Object... contexts) as collapseText(Throwable) but skipping any throwables which implement CanSkipInContext and indicate they should be skipped any of the given contexts
static java.lang.Throwable	create(java.lang.Iterable<? extends java.lang.Throwable> exceptions) creates the given exception, but without propagating it, for use when caller will be wrapping
static java.lang.RuntimeException	create(java.lang.String prefix, java.lang.Iterable<? extends java.lang.Throwable> exceptions) creates the given exception, but without propagating it, for use when caller will be wrapping
static java.util.List<java.lang.Throwable>	getCausalChain(java.lang.Throwable t) As Throwables#getCausalChain(Throwable) but safe in the face of perverse classes which return themselves as their cause or otherwise have a recursive causal chain.
static java.lang.Throwable	getFirstInteresting(java.lang.Throwable throwable) returns the first exception in the call chain which whose message is potentially interesting, in the sense that it is has some chance of giving helpful information as the cause.
static java.lang.Throwable	getFirstThrowableMatching(java.lang.Throwable from, <any> filter) returns the first exception that matches the filter, or null
static <T extends java.lang.Throwable> T	getFirstThrowableOfType(java.lang.Throwable from, java.lang.Class<T> clazz) returns the first exception of the given type, or null
static java.lang.String	getMessageWithAppropriatePrefix(java.lang.Throwable t) Like Throwable.toString() except suppresses boring prefixes and replaces prefixes with sensible messages where required
static boolean	isFatal(java.lang.Throwable throwable) Indicates whether this exception is "fatal" - i.e.
static <any>	isFatalPredicate()
static boolean	isPrefixBoring(java.lang.Throwable t) Returns whether the prefix is throwable either known to be boring or to have an unhelpful type name (prefix) which should be suppressed in messages.
static boolean	isPrefixRequiredForMessageToMakeSense(java.lang.Throwable t) Some throwables require a prefix for the message to make sense, for instance NoClassDefFoundError's message is often just the type.
static boolean	isRootBoringClassNotFound(java.lang.Exception e, java.lang.String clazz) Returns true if the root cause is a "boring" CNF, ie a straightforward declaration that the clazz is not found; this permits callers to include the cause only when it is interesting, ie caused by a dependent class not loadable.
static boolean	isSkippableInContext(java.lang.Throwable e, java.lang.Object... contexts) True if the given exception is skippable in any of the supplied contexts.
static java.lang.RuntimeException	propagate(java.lang.Iterable<? extends java.lang.Throwable> exceptions)
static java.lang.RuntimeException	propagate(java.lang.String prefix, java.lang.Iterable<? extends java.lang.Throwable> exceptions)
static java.lang.RuntimeException	propagate(java.lang.String msg, java.lang.Throwable throwable) Deprecated. since 0.12.0 behaviour will change (default should be to always wrap and annotate); for now users should review and switch to either propagateAnnotated(String, Throwable) or propagateAnnotateIfWrapping(String, Throwable) as appropriate.
static java.lang.RuntimeException	propagate(java.lang.Throwable throwable) Propagate a Throwable as a RuntimeException.
static java.lang.RuntimeException	propagateAnnotated(java.lang.String msg, java.lang.Throwable throwable) As propagate(String, Throwable) but unlike earlier deprecated version this always re-wraps including the given message, until semantics of that method change to match this.
static java.lang.RuntimeException	propagateAnnotateIfWrapping(java.lang.String msg, java.lang.Throwable throwable) See propagate(Throwable).
static void	propagateIfFatal(java.lang.Throwable throwable) Propagate exceptions which are fatal.
static void	propagateIfInterrupt(java.lang.Throwable throwable) Propagate exceptions which are interrupts (be it InterruptedException or RuntimeInterruptedException.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_COLLAPSE_RECURSIVE_DEPTH

public static final int MAX_COLLAPSE_RECURSIVE_DEPTH

See Also:

Constant Field Values

Constructor Detail

Exceptions

public Exceptions()

Method Detail

isPrefixBoring

public static boolean isPrefixBoring(java.lang.Throwable t)

Returns whether the prefix is throwable either known to be boring or to have an unhelpful type name (prefix) which should be suppressed in messages. (They may be important in stack traces.)

null is accepted but treated as not boring.

propagate

public static java.lang.RuntimeException propagate(java.lang.Throwable throwable)

Propagate a Throwable as a RuntimeException.

Like Guava Throwables#propagate(Throwable) but:

throws RuntimeInterruptedException to handle InterruptedExceptions; and wraps as PropagatedRuntimeException for easier filtering

propagate

@Deprecated
public static java.lang.RuntimeException propagate(java.lang.String msg,
                                                               java.lang.Throwable throwable)

Deprecated. since 0.12.0 behaviour will change (default should be to always wrap and annotate); for now users should review and switch to either propagateAnnotated(String, Throwable) or propagateAnnotateIfWrapping(String, Throwable) as appropriate.

Convenience for propagateAnnotateIfWrapping(String, Throwable).

propagateAnnotateIfWrapping

public static java.lang.RuntimeException propagateAnnotateIfWrapping(java.lang.String msg,
                                                                     java.lang.Throwable throwable)

See propagate(Throwable).

The given message is included only if the given Throwable needs to be wrapped; otherwise the message is not used. To always include the message, use propagateAnnotated(String, Throwable).

propagateAnnotated

public static java.lang.RuntimeException propagateAnnotated(java.lang.String msg,
                                                            java.lang.Throwable throwable)

As propagate(String, Throwable) but unlike earlier deprecated version this always re-wraps including the given message, until semantics of that method change to match this. See propagateAnnotateIfWrapping(String, Throwable) if the message should be omitted and the given throwable preserved if it can already be propagated.

propagateIfInterrupt

public static void propagateIfInterrupt(java.lang.Throwable throwable)

Propagate exceptions which are interrupts (be it InterruptedException or RuntimeInterruptedException.

propagateIfFatal

public static void propagateIfFatal(java.lang.Throwable throwable)

Propagate exceptions which are fatal.

Propagates only those exceptions which one rarely (if ever) wants to capture, such as InterruptedException and Errors.

isFatal

public static boolean isFatal(java.lang.Throwable throwable)

Indicates whether this exception is "fatal" - i.e. in normal programming, should not be caught but should instead be propagating so the call-stack fails. For example, an interrupt should cause the task to abort rather than catching and ignoring (or "handling" incorrectly).

isFatalPredicate

public static <any> isFatalPredicate()

getFirstThrowableOfType

public static <T extends java.lang.Throwable> T getFirstThrowableOfType(java.lang.Throwable from,
                                                                        java.lang.Class<T> clazz)

returns the first exception of the given type, or null

getFirstThrowableMatching

public static java.lang.Throwable getFirstThrowableMatching(java.lang.Throwable from,
                                                            <any> filter)

returns the first exception that matches the filter, or null

getFirstInteresting

public static java.lang.Throwable getFirstInteresting(java.lang.Throwable throwable)

returns the first exception in the call chain which whose message is potentially interesting, in the sense that it is has some chance of giving helpful information as the cause.

more specifically this drops those which typically wrap such causes giving chain / thread info, reporting rather than causal explanation or important context -- ie excluding ExecutionException always, and PropagatedRuntimeException if it has no message, and similar such.

if all are "uninteresting" in this sense (which should not normally be the case) this method just returns the original.

often looking for a UserFacingException eg using getFirstThrowableOfType(Throwable, Class) is a better way to give a user-facing message.

collapse

public static java.lang.Throwable collapse(java.lang.Throwable source)

creates (but does not throw) a new PropagatedRuntimeException whose message and cause are taken from the first _interesting_ element in the source

collapseIncludingAllCausalMessages

public static java.lang.Throwable collapseIncludingAllCausalMessages(java.lang.Throwable source)

as collapse(Throwable) but includes causal messages in the message as per collapseTextIncludingAllCausalMessages(Throwable); use with care (limit once) as repeated usage can result in multiple copies of the same message

collapse

public static java.lang.Throwable collapse(java.lang.Throwable source,
                                           boolean collapseCausalChain)

creates (but does not throw) a new PropagatedRuntimeException whose message is taken from the first _interesting_ element in the source, and optionally also the causal chain

getCausalChain

public static java.util.List<java.lang.Throwable> getCausalChain(java.lang.Throwable t)

As Throwables#getCausalChain(Throwable) but safe in the face of perverse classes which return themselves as their cause or otherwise have a recursive causal chain.

isSkippableInContext

public static boolean isSkippableInContext(java.lang.Throwable e,
                                           java.lang.Object... contexts)

True if the given exception is skippable in any of the supplied contexts.

collapseText

public static java.lang.String collapseText(java.lang.Throwable t)

like collapse(Throwable) but returning a one-line message suitable for logging without traces

collapseTextInContext

public static java.lang.String collapseTextInContext(java.lang.Throwable t,
                                                     java.lang.Object... contexts)

as collapseText(Throwable) but skipping any throwables which implement CanSkipInContext and indicate they should be skipped any of the given contexts

collapseTextIncludingAllCausalMessages

public static java.lang.String collapseTextIncludingAllCausalMessages(java.lang.Throwable t)

normally collapseText(Throwable) will stop following causal chains when encountering an interesting exception with a message; this variant will continue to follow such causal chains, showing all messages. for use e.g. when verbose is desired in the single-line message.

propagate

public static java.lang.RuntimeException propagate(java.lang.Iterable<? extends java.lang.Throwable> exceptions)

propagate

public static java.lang.RuntimeException propagate(java.lang.String prefix,
                                                   java.lang.Iterable<? extends java.lang.Throwable> exceptions)

create

public static java.lang.Throwable create(java.lang.Iterable<? extends java.lang.Throwable> exceptions)

creates the given exception, but without propagating it, for use when caller will be wrapping

create

public static java.lang.RuntimeException create(@Nullable
                                                java.lang.String prefix,
                                                java.lang.Iterable<? extends java.lang.Throwable> exceptions)

creates the given exception, but without propagating it, for use when caller will be wrapping

isPrefixRequiredForMessageToMakeSense

public static boolean isPrefixRequiredForMessageToMakeSense(java.lang.Throwable t)

Some throwables require a prefix for the message to make sense, for instance NoClassDefFoundError's message is often just the type.

getMessageWithAppropriatePrefix

public static java.lang.String getMessageWithAppropriatePrefix(java.lang.Throwable t)

Like Throwable.toString() except suppresses boring prefixes and replaces prefixes with sensible messages where required

isRootBoringClassNotFound

public static boolean isRootBoringClassNotFound(java.lang.Exception e,
                                                java.lang.String clazz)

Returns true if the root cause is a "boring" CNF, ie a straightforward declaration that the clazz is not found; this permits callers to include the cause only when it is interesting, ie caused by a dependent class not loadable.