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 {@link MetaData @MetaData} are will cause the parameter values to be added asmeta data values to the outgoing message.
- If the last two parameters are of type {@link Long long} and {@link 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 {@link Future} return type will always result in a non-blocking operation. A future is returnedthat 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 {@link TimeoutException} will throw that exception when a configured timeout expires. If no suchexception is declared, but a timeout is configured, the method will return
null. - Declaring an {@link InterruptedException} will throw that exception when a thread blocked while waiting for aresponse 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
Finally, the {@link Timeout @Timeout} annotation can be used to define a timeout on a method. This will always causea 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 {@link TimeUnit} and {@link Long long}, or
- The method is annotated with {@link Timeout @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.
@author Allard Buijze
@since 2.0