Package org.axonframework.commandhandling.gateway

Class CommandGatewayFactory

java.lang.Object

org.axonframework.commandhandling.gateway.CommandGatewayFactory

public class CommandGatewayFactory
extends Object

Factory that creates CommandGateway 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 implementation 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 MetaData 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, CompletableFuture, or CompletionStage return type will result in a non-blocking operation, given that the configured CommandBus is asynchronous. For example, when the provided CommandBus is a SimpleCommandBus, the returned Future is still blocking. The returned Future 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	Description
static class	CommandGatewayFactory.Builder	Builder class to instantiate a CommandGatewayFactory.
static interface	CommandGatewayFactory.InvocationHandler<R>	Interface towards the mechanism that handles a method call on a gateway interface method.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CommandGatewayFactory(CommandGatewayFactory.Builder builder)	Instantiate a CommandGatewayFactory based on the fields contained in the CommandGatewayFactory.Builder.

Method Summary

Modifier and Type	Method	Description
static CommandGatewayFactory.Builder	builder()	Instantiate a Builder to be able to create a CommandGatewayFactory.
<T> T	createGateway(Class<T> gatewayInterface)	Creates a gateway instance for the given gatewayInterface.
<C, R> CommandGatewayFactory	registerCommandCallback(CommandCallback<C,R> callback, ResponseType<R> responseType)	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 CommandGatewayFactory.InvocationHandler that returns immediately after invoking the delegate.
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 CompletableFuture 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 CompletableFuture 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 CompletableFuture to become available.
protected <R> CommandGatewayFactory.InvocationHandler<R>	wrapUndeclaredExceptions(CommandGatewayFactory.InvocationHandler<R> delegate, Class<?>[] declaredExceptions)	Wraps the given delegate in an CommandGatewayFactory.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 Details

CommandGatewayFactory

protected CommandGatewayFactory(CommandGatewayFactory.Builder builder)

Instantiate a CommandGatewayFactory based on the fields contained in the CommandGatewayFactory.Builder.

Will assert that the CommandBus is not null, and will throw an AxonConfigurationException if it is null.

Parameters:

builder - The CommandGatewayFactory.Builder used to instantiate a CommandGatewayFactory instance.

Method Details

builder

public static CommandGatewayFactory.Builder builder()

Instantiate a Builder to be able to create a CommandGatewayFactory.

The CommandBus is a hard requirements and as such should be provided.

Returns:

A Builder to be able to create a CommandGatewayFactory.

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 CommandGatewayFactory.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 CommandGatewayFactory.InvocationHandler that wraps undeclared exceptions in a CommandExecutionException.

wrapToFireAndForget

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

Wrap the given delegate in an CommandGatewayFactory.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 CommandGatewayFactory.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 CompletableFuture 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 CompletableFuture

Returns:

The result of the CompletableFuture, 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 CompletableFuture 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 CompletableFuture.

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 CompletableFuture, 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 CompletableFuture 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 CompletableFuture.

timeoutIndex - The index of the argument providing the timeout.

timeUnitIndex - The index of the argument providing the time unit.

Returns:

The result of the CompletableFuture, either a return value or an exception.

registerCommandCallback

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

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 CommandCallback.onResult(CommandMessage, CommandResultMessage) 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.

responseType - The actual response type of the command.

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.