org.axonframework.commandhandling.gateway

Class CommandGatewayFactory

java.lang.Object

org.axonframework.commandhandling.gateway.CommandGatewayFactory

public class CommandGatewayFactory
extends Object

Factory that creates Gateway implementations from custom interface definitions. The behavior of the method is defined by the parameters, declared exceptions and return type of the method.

Supported parameter types:

• The first parameter of the method is considered the payload of the message. If the first parameter is a Message itself, a new message is created using the payload and metadata of the message passed as parameter.
• Parameters that are annotated with @MetaDataValue will cause the parameter values to be added as meta data values to the outgoing message.
• If the last two parameters are of type long and TimeUnit, they are considered to represent the timeout for the command. The method will block for as long as the command requires to execute, or until the timeout expires.

Effect of return values

• void return types are always allowed. Unless another parameter makes the method blocking, void methods are non-blocking by default.
• Declaring a Future return type will always result in a non-blocking operation. A future is returned that allows you to retrieve the execution's result at your own convenience. Note that declared exceptions and timeouts are ignored.
• Any other return type will cause the dispatch to block (optionally with timeout) until a result is available

Effect of declared exceptions

• Any checked exception declared on the method will cause it to block (optionally with timeout). If the command results in a declared checked exception, that exception is thrown from the method.
• Declaring a TimeoutException will throw that exception when a configured timeout expires. If no such exception is declared, but a timeout is configured, the method will return null.
• Declaring an InterruptedException will throw that exception when a thread blocked while waiting for a response is interrupted. Not declaring the exception will have the method return null when a blocked thread is interrupted. Note that when no InterruptedException is declared, the interrupt flag is set back on the interrupted thread

Effect of unchecked exceptions

• Any unchecked exception thrown during command handling will cause it to block. If the method is blocking (see below) the unchecked exception will be thrown from the method

Finally, the @Timeout annotation can be used to define a timeout on a method. This will always cause a method invocation to block until a response is available, or the timeout expires.

Any method will be blocking if:

• It declares a return type other than void or Future, or
• It declares an exception, or
• The last two parameters are of type TimeUnit and long, or
• The method is annotated with @Timeout

In other cases, the method is non-blocking and will return immediately after dispatching a command.

This factory is thread safe once configured, and so are the gateways it creates.

Since:

2.0

Author:

Allard Buijze

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	CommandGatewayFactory.InvocationHandler<R> Interface towards the mechanism that handles a method call on a gateway interface method.

Constructor Summary

Constructors

Constructor and Description
CommandGatewayFactory(CommandBus commandBus, MessageDispatchInterceptor<CommandMessage<?>>... dispatchInterceptors) Initialize the factory sending Commands to the given commandBus, optionally intercepting them with given dispatchInterceptors.
CommandGatewayFactory(CommandBus commandBus, RetryScheduler retryScheduler, List<MessageDispatchInterceptor<CommandMessage<?>>> messageDispatchInterceptors) Initialize the factory sending Commands to the given commandBus, optionally intercepting them with given dispatchInterceptors.
CommandGatewayFactory(CommandBus commandBus, RetryScheduler retryScheduler, MessageDispatchInterceptor<CommandMessage<?>>... messageDispatchInterceptors) Initialize the factory sending Commands to the given commandBus, optionally intercepting them with given dispatchInterceptors.

Method Summary

Modifier and Type	Method and Description
<T> T	createGateway(Class<T> gatewayInterface) Creates a gateway instance for the given gatewayInterface.
<C,R> CommandGatewayFactory	registerCommandCallback(CommandCallback<C,R> callback) Registers the callback, which is invoked for each sent command, unless Axon is able to detect that the result of the command does not match the type accepted by the callback.
CommandGatewayFactory	registerDispatchInterceptor(MessageDispatchInterceptor<CommandMessage<?>> dispatchInterceptor) Registers the given dispatchInterceptor which is invoked for each Command dispatched through the Command Gateways created by this factory.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapToFireAndForget(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate) Wrap the given delegate in an InvocationHandler that returns immediately after invoking the delegate.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapToReturnNullOnInterrupted(CommandGatewayFactory.InvocationHandler<R> delegate) Wrap the given delegate in an InvocationHandler that returns null when the delegate throws an InterruptedException.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapToReturnNullOnTimeout(CommandGatewayFactory.InvocationHandler<R> delegate) Wrap the given delegate in an InvocationHandler that returns null when the delegate throws a TimeoutException.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapToReturnWithFixedTimeout(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate, long timeout, TimeUnit timeUnit) Wraps the given delegate and waits for the result in the Future to become available, with given timeout and timeUnit.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapToReturnWithTimeoutInArguments(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate, int timeoutIndex, int timeUnitIndex) Wraps the given delegate and waits for the result in the Future to become available using given indices to resolve the parameters that provide the timeout to use.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapToWaitForResult(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate) Wraps the given delegate and waits for the result in the Future to become available.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapUndeclaredExceptions(CommandGatewayFactory.InvocationHandler<R> delegate, Class<?>[] declaredExceptions) Wraps the given delegate in an InvocationHandler that wraps exceptions not declared on the method in a CommandExecutionException.

Methods inherited from class java.lang.Object

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

Constructor Detail

CommandGatewayFactory

@SafeVarargs
public CommandGatewayFactory(CommandBus commandBus,
                                           MessageDispatchInterceptor<CommandMessage<?>>... dispatchInterceptors)

Initialize the factory sending Commands to the given commandBus, optionally intercepting them with given dispatchInterceptors.

Note that the given dispatchInterceptors are applied only on commands sent through gateways that have been created using this factory.

Parameters:

commandBus - The CommandBus on which to dispatch the Command Messages

dispatchInterceptors - The interceptors to invoke before dispatching commands to the Command Bus

CommandGatewayFactory

@SafeVarargs
public CommandGatewayFactory(CommandBus commandBus,
                                           RetryScheduler retryScheduler,
                                           MessageDispatchInterceptor<CommandMessage<?>>... messageDispatchInterceptors)

Initialize the factory sending Commands to the given commandBus, optionally intercepting them with given dispatchInterceptors. The given retryScheduler will reschedule commands for dispatching if a previous attempt resulted in an exception.

Note that the given dispatchInterceptors are applied only on commands sent through gateways that have been created using this factory.

Parameters:

commandBus - The CommandBus on which to dispatch the Command Messages

retryScheduler - The scheduler that will decide whether to reschedule commands, may be null to report failures without rescheduling

messageDispatchInterceptors - The interceptors to invoke before dispatching commands to the Command Bus

CommandGatewayFactory

public CommandGatewayFactory(CommandBus commandBus,
                             RetryScheduler retryScheduler,
                             List<MessageDispatchInterceptor<CommandMessage<?>>> messageDispatchInterceptors)

Initialize the factory sending Commands to the given commandBus, optionally intercepting them with given dispatchInterceptors. The given retryScheduler will reschedule commands for dispatching if a previous attempt resulted in an exception.

Note that the given dispatchInterceptors are applied only on commands sent through gateways that have been created using this factory.

Parameters:

commandBus - The CommandBus on which to dispatch the Command Messages

retryScheduler - The scheduler that will decide whether to reschedule commands, may be null to report failures without rescheduling

messageDispatchInterceptors - The interceptors to invoke before dispatching commands to the Command Bus

Method Detail

createGateway

public <T> T createGateway(Class<T> gatewayInterface)

Creates a gateway instance for the given gatewayInterface. The returned instance is a Proxy that implements that interface.

Type Parameters:

T - The interface declaring the gateway methods

Parameters:

gatewayInterface - The interface declaring the gateway methods

Returns:

A Proxy implementation implementing the given interface

wrapUndeclaredExceptions

protected <R> CommandGatewayFactory.InvocationHandler<R> wrapUndeclaredExceptions(CommandGatewayFactory.InvocationHandler<R> delegate,
                                                                                  Class<?>[] declaredExceptions)

Wraps the given delegate in an InvocationHandler that wraps exceptions not declared on the method in a CommandExecutionException.

Type Parameters:

R - The response type of the command handler

Parameters:

delegate - The delegate to invoke that potentially throws exceptions

declaredExceptions - The exceptions declared on the method signature

Returns:

an InvocationHandler that wraps undeclared exceptions in a CommandExecutionException

wrapToReturnNullOnInterrupted

protected <R> CommandGatewayFactory.InvocationHandler<R> wrapToReturnNullOnInterrupted(CommandGatewayFactory.InvocationHandler<R> delegate)

Wrap the given delegate in an InvocationHandler that returns null when the delegate throws an InterruptedException.

Type Parameters:

R - The response type of the command handler

Parameters:

delegate - The delegate to invoke, potentially throwing an InterruptedException when invoked

Returns:

an InvocationHandler that wraps returns null when an InterruptedException is thrown

wrapToReturnNullOnTimeout

protected <R> CommandGatewayFactory.InvocationHandler<R> wrapToReturnNullOnTimeout(CommandGatewayFactory.InvocationHandler<R> delegate)

Wrap the given delegate in an InvocationHandler that returns null when the delegate throws a TimeoutException.

Type Parameters:

R - The response type of the command handler

Parameters:

delegate - The delegate to invoke, potentially throwing a TimeoutException when invoked

Returns:

an InvocationHandler that wraps returns null when a TimeoutException is thrown

wrapToFireAndForget

protected <R> CommandGatewayFactory.InvocationHandler<R> wrapToFireAndForget(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate)

Wrap the given delegate in an InvocationHandler that returns immediately after invoking the delegate.

Type Parameters:

R - The response type of the command handler

Parameters:

delegate - The delegate to invoke, potentially throwing an InterruptedException when invoked

Returns:

an InvocationHandler that wraps returns immediately after invoking the delegate

wrapToWaitForResult

protected <R> CommandGatewayFactory.InvocationHandler<R> wrapToWaitForResult(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate)

Wraps the given delegate and waits for the result in the Future to become available. No explicit timeout is provided for the waiting.

Type Parameters:

R - The result of the command handler

Parameters:

delegate - The delegate to invoke, returning a Future

Returns:

the result of the Future, either a return value or an exception

wrapToReturnWithFixedTimeout

protected <R> CommandGatewayFactory.InvocationHandler<R> wrapToReturnWithFixedTimeout(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate,
                                                                                      long timeout,
                                                                                      TimeUnit timeUnit)

Wraps the given delegate and waits for the result in the Future to become available, with given timeout and timeUnit.

Type Parameters:

R - The result of the command handler

Parameters:

delegate - The delegate to invoke, returning a Future

timeout - The amount of time to wait for the result to become available

timeUnit - The unit of time to wait

Returns:

the result of the Future, either a return value or an exception

wrapToReturnWithTimeoutInArguments

protected <R> CommandGatewayFactory.InvocationHandler<R> wrapToReturnWithTimeoutInArguments(CommandGatewayFactory.InvocationHandler<CompletableFuture<R>> delegate,
                                                                                            int timeoutIndex,
                                                                                            int timeUnitIndex)

Wraps the given delegate and waits for the result in the Future to become available using given indices to resolve the parameters that provide the timeout to use.

Type Parameters:

R - The result of the command handler

Parameters:

delegate - The delegate to invoke, returning a Future

timeoutIndex - The index of the argument providing the timeout

timeUnitIndex - The index of the argument providing the time unit

Returns:

the result of the Future, either a return value or an exception

registerCommandCallback

public <C,R> CommandGatewayFactory registerCommandCallback(CommandCallback<C,R> callback)

Registers the callback, which is invoked for each sent command, unless Axon is able to detect that the result of the command does not match the type accepted by the callback.

Axon will check the signature of the onSuccess() method and only invoke the callback if the actual result of the command is an instance of that type. If Axon is unable to detect the type, the callback is always invoked, potentially causing ClassCastException.

Type Parameters:

R - The type of return value the callback is interested in

Parameters:

callback - The callback to register

Returns:

this instance for further configuration

registerDispatchInterceptor

public CommandGatewayFactory registerDispatchInterceptor(MessageDispatchInterceptor<CommandMessage<?>> dispatchInterceptor)

Registers the given dispatchInterceptor which is invoked for each Command dispatched through the Command Gateways created by this factory.

Parameters:

dispatchInterceptor - The interceptor to register.

Returns:

this instance for further configuration