CommandGatewayFactory (Axon Framework 4.12.1 API)

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 and 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 and Description
`protected`	`CommandGatewayFactory(CommandGatewayFactory.Builder builder)` Instantiate a `CommandGatewayFactory` based on the fields contained in the `CommandGatewayFactory.Builder`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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 Detail
  - 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 Detail
  - 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.

Class CommandGatewayFactory

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

CommandGatewayFactory

Method Detail

builder

createGateway

wrapUndeclaredExceptions

wrapToFireAndForget

wrapToWaitForResult

wrapToReturnWithFixedTimeout

wrapToReturnWithTimeoutInArguments

registerCommandCallback

registerDispatchInterceptor