Package org.axonframework.messaging.core

Class HandlerExecutionException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.axonframework.common.AxonException

org.axonframework.messaging.core.HandlerExecutionException

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

CommandExecutionException, QueryExecutionException

public abstract class HandlerExecutionException
extends AxonException

Base exception for exceptions raised by Handler methods. Besides standard exception information (such as message and cause), these exception may optionally carry an object with additional application-specific details about the exception.

By default, a stack trace is not generated for this exception. However, the stack trace creation can be enforced explicitly via the constructor accepting the writableStackTrace parameter.

When these details cross an infrastructure boundary (for example, a remote command or query dispatched through Axon Server), they may arrive as raw data alongside a Converter rather than as the original application object. In that case, getDetails(Class), getDetails(TypeReference), and getDetails(Type) apply the Converter lazily, on request, mirroring how Message.payloadAs(Class) defers payload conversion. This keeps the thrower and the receiver decoupled from having to agree on the exact same details class or version.

Since:

4.2.0

Author:

Allard Buize

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
HandlerExecutionException(String message)	Initializes an execution exception with given message.
HandlerExecutionException(String message, @Nullable Throwable cause)	Initializes an execution exception with given message and cause.
HandlerExecutionException(String message, @Nullable Throwable cause, @Nullable Object details)	Initializes an execution exception with given message, cause and application-specific details.
HandlerExecutionException(String message, @Nullable Throwable cause, @Nullable Object details, boolean writableStackTrace)	Initializes an execution exception with given message, cause, application-specific details, and writableStackTrace
HandlerExecutionException(String message, @Nullable Throwable cause, @Nullable Object details, @Nullable Converter converter, boolean writableStackTrace)	Initializes an execution exception with given message, cause, application-specific details, converter, and writableStackTrace.

Method Summary

Modifier and Type	Method	Description
<R> Optional<R>	getDetails()	Deprecated, for removal: This API element is subject to removal in a future version. in favor of getDetails(Class), or any of the Type, TypeReference, or Converter parameter combinations, as those ensure the details are converted to the desired type
<R> Optional<R>	getDetails(Class<R> type)	Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the Converter attached to this exception (if any).
<R> Optional<R>	getDetails(Class<R> type, @Nullable Converter converter)	Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the given converter.
<R> Optional<R>	getDetails(Type type)	Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the Converter attached to this exception (if any).
<R> Optional<R>	getDetails(Type type, @Nullable Converter converter)	Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the given converter.
<R> Optional<R>	getDetails(TypeReference<R> type)	Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the Converter attached to this exception (if any).
<R> Optional<R>	getDetails(TypeReference<R> type, @Nullable Converter converter)	Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the given converter.
static <R> Optional<R>	resolveDetails(@Nullable Throwable throwable)	Resolve details from the given throwable, taking into account that the details may be available in any of the HandlerExecutionExceptions in the "cause" chain.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Constructor Details

HandlerExecutionException

public HandlerExecutionException(String message)

Initializes an execution exception with given message. The cause and application-specific details are set to null.

Parameters:

message - a message describing the exception

HandlerExecutionException

public HandlerExecutionException(String message,
 @Nullable Throwable cause)

Initializes an execution exception with given message and cause. Application-specific details and their Converter, if any, are inherited from the first HandlerExecutionException in the cause chain that carries details.

Parameters:

message - a message describing the exception

cause - the cause of the execution exception

HandlerExecutionException

public HandlerExecutionException(String message,
 @Nullable Throwable cause,
 @Nullable Object details)

Initializes an execution exception with given message, cause and application-specific details.

Parameters:

message - a message describing the exception

cause - the cause of the execution exception

details - an object providing application-specific details of the exception

HandlerExecutionException

public HandlerExecutionException(String message,
 @Nullable Throwable cause,
 @Nullable Object details,
 boolean writableStackTrace)

Initializes an execution exception with given message, cause, application-specific details, and writableStackTrace

Parameters:

message - a message describing the exception

cause - the cause of the execution exception

details - an object providing application-specific details of the exception

writableStackTrace - whether the stack trace should be generated (true) or not (false)

HandlerExecutionException

@Internal
public HandlerExecutionException(String message,
 @Nullable Throwable cause,
 @Nullable Object details,
 @Nullable Converter converter,
 boolean writableStackTrace)

Initializes an execution exception with given message, cause, application-specific details, converter, and writableStackTrace.

This constructor is used by messaging infrastructure to attach a Converter when reconstructing details from raw data received over an infrastructure boundary (for example, a remote command or query response). It is not meant to be used directly by application code, which typically already has the details object in its final form and can use HandlerExecutionException(String, Throwable, Object) instead.

Parameters:

message - a message describing the exception

cause - the cause of the execution exception

details - an object providing application-specific details of the exception, potentially raw data awaiting conversion

converter - the Converter to lazily apply when getDetails(Class), getDetails(TypeReference), or getDetails(Type) is called with a type details does not already match, or null if no such conversion is available

writableStackTrace - whether the stack trace should be generated (true) or not (false)

Method Details

resolveDetails

public static <R> Optional<R> resolveDetails(@Nullable Throwable throwable)

Resolve details from the given throwable, taking into account that the details may be available in any of the HandlerExecutionExceptions in the "cause" chain.

Type Parameters:

R - the type of details expected

Parameters:

throwable - the exception to resolve the details from

Returns:

an Optional containing details, if present in the given throwable

getDetails

@Deprecated(since="5.3.0",
            forRemoval=true)
public <R> Optional<R> getDetails()

Deprecated, for removal: This API element is subject to removal in a future version.

in favor of getDetails(Class), or any of the Type, TypeReference, or Converter parameter combinations, as those ensure the details are converted to the desired type

Returns an Optional containing application-specific details of the exception, if any were provided.

These details are implicitly cast to the expected type. A mismatch in type may lead to a ClassCastException further downstream, when accessing the Optional's enclosed value.

Type Parameters:

R - the type of details expected

Returns:

an Optional containing the details, if provided

getDetails

public <R> Optional<R> getDetails(Class<R> type)

Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the Converter attached to this exception (if any).

Type Parameters:

R - the type of details expected

Parameters:

type - the type to return the details as

Returns:

an Optional containing the details converted to type, if provided

Throws:

ConversionException - if the details are present but do not match type, and either no Converter is available or the conversion fails

getDetails

public <R> Optional<R> getDetails(Class<R> type,
 @Nullable Converter converter)

Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the given converter.

If the current details already are an instance of type, no conversion takes place and the given converter is ignored. Otherwise, the given converter is used to convert the details into type. This allows the thrower and the receiver of these details to use different classes or versions for the same logical details.

Type Parameters:

R - the type of details expected

Parameters:

type - the type to return the details as

converter - the converter to convert the details with, or null if no conversion is available

Returns:

an Optional containing the details converted to type, if provided

Throws:

ConversionException - if the details are present but do not match type, and either no converter is given or the conversion fails

getDetails

public <R> Optional<R> getDetails(TypeReference<R> type)

Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the Converter attached to this exception (if any).

Behaves identically to getDetails(Class), but supports generic types (for example List<String>) through a TypeReference.

Type Parameters:

R - the type of details expected

Parameters:

type - the type to return the details as

Returns:

an Optional containing the details converted to type, if provided

Throws:

ConversionException - if the details are present but do not match type, and either no Converter is available or the conversion fails

getDetails

public <R> Optional<R> getDetails(TypeReference<R> type,
 @Nullable Converter converter)

Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the given converter.

Behaves identically to getDetails(Class, Converter), but supports generic types (for example List<String>) through a TypeReference.

Type Parameters:

R - the type of details expected

Parameters:

type - the type to return the details as

converter - the converter to convert the details with, or null if no conversion is available

Returns:

an Optional containing the details converted to type, if provided

Throws:

ConversionException - if the details are present but do not match type, and either no converter is given or the conversion fails

getDetails

public <R> Optional<R> getDetails(Type type)

Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the Converter attached to this exception (if any).

Behaves identically to getDetails(Class), but accepts a raw Type, for callers that already have one at hand (for example, obtained through reflection) instead of a Class or TypeReference.

Type Parameters:

R - the type of details expected

Parameters:

type - the type to return the details as

Returns:

an Optional containing the details converted to type, if provided

Throws:

ConversionException - if the details are present but do not match type, and either no Converter is available or the conversion fails

getDetails

public <R> Optional<R> getDetails(Type type,
 @Nullable Converter converter)

Returns an Optional containing application-specific details of the exception, converted into the given type if necessary, using the given converter.

If the current details already are an instance of type, no conversion takes place and the given converter is ignored. Otherwise, the given converter is used to convert the details into type. This allows the thrower and the receiver of these details to use different classes or versions for the same logical details. This is the terminal operation every other getDetails overload delegates to.

Type Parameters:

R - the type of details expected

Parameters:

type - the type to return the details as

converter - the converter to convert the details with, or null if no conversion is available

Returns:

an Optional containing the details converted to type, if provided

Throws:

ConversionException - if the details are present but do not match type, and either no converter is given or the conversion fails