Expected behavior when RuntimeException thrown by a Command Handler method?


I’m doing some tests with Axon. First, I want to congratulate you for your excellent framework. It offers the possibility to understand CQRS, EventSourcing and DDD at the same time!

I want to understand how it behaves when exceptions happen in @CommandHandler methods.

I’ve observed a strange behavior when sending an async command (no answer expected) through a custom gateway (void method) when a RuntimeException occurs in the @CommandHandler method :

  • when the Command Handler class does not explicitelly implements the gateway interface : no RuntimeException is thrown to the caller,
  • when the Command Handler class does explictelly implements the gateway interface : the RuntimeException is thrown to the caller.

With an aync method, I guess the first case should be the normal one: no result is expected at all by the caller (even an Exception).

BTW, this is what I’ve observed when sending the same command through the CommandBus dispatch method.

Hence my questions :

  • should a Command Handler class implements its custom gateway ? In my understanding, it should since it enforces the code consistency at the compiler level,
  • why does it change the behavior on the caller side when a RuntimeException is thrown by the Command Handler method ?
    If my explanations are not clear enough, I can send a very basic Java project.

I’m using Axon 2.2 and the SImpleCommandBus implementation.


in general, CommandBus implementations will always notify result of command processing using a callback. The only exception is when the error occurs while dispatching the command (meaning it has never reached a handler). In that case, the dispatch method itself throws an exception.
The gateway is merely a facade in front of the CommandBus, that provides a cleaner API. this allows you to define meta data that you need on each command as a parameter for example. Of force a caller to block until the result is returned, etc. etc.

Your @CommandHandler beans should not implement the interface you use for the gateway. Your command handlers should only declare parameters they really care about.

Are you 100% sure that the exceptions you see in both cases you depict are identical? When an exception is thrown to the caller, it either indicates a configuration error, or the gateway declares either a return type or an exception.



Hi Allard,

Thank you for your answer. I’ve switched to Axon 2.3, cleaned my project and following your advice everything is OK now.

You’re right : the Cusom Gateway aims at being a façade in front of the Command Bus not an interface to the Command Handlers ! Maybe I’ve been badly influenced by my EJB background : you know, in the “old time” of EJB 1.x and 2.x, bean implementations were required to implement their business interfaces.

So everything is OK for me to keep on investigating Axon … And have fun !