EntityNotFoundException behavior around @EntityCreator usage for Entity-centric and Stateful-Handler-based instance command handling

[smcvb]

This pull request is under discussion on purpose, as the team is not fully aligned yet on the direction.
What it provides, is a new test suite in the axon-integrationtest module.
The test includes 6 different entity+command handling+creation approaches:

1. Entity-centric, no-arg entity creator
2. Entity-centric, id-based entity creator
3. Entity-centric, first-event-based entity creator
4. Stateful-command-handler-centric, no-arg entity creator
5. Stateful-command-handler-centric, id-based entity creator
6. Stateful-command-handler-centric, first-event-based entity creator

For all 6 styles, we have two tests:

1. Dispatch creational command for the entity - should succeed always
2. Dispatch instance command for the entity - fails for entity-centric, succeeds for stateful-command-handler-centric.

To ensure the above is true, I made some minor changes, which are:

1. Introduce the EntityNotFoundException, akin to the AggregateNotFoundException. This can be thrown when applicable.
2. Adjust the AnnotationBasedEventSourcedEntityFactory to throw an EntityNotFoundException when there is no initial event, regardless of the entity-creator choice.
3. Adjust the InjectEntityParameterResolver to catch the EntityNotFoundException to return null for the entity when it couldn't be found.

What's up to debate, and why this is still in under discussion, is whether we agree with the (1) test domains and (2) instance command handler outcomes per test.

[laura-devriendt-lemon]

My read on this issue

What I think works really well

Entity-centric instance commands throwing EntityNotFoundException when the entity was never created feels exactly right. You can't run a method "on" something that doesn't exist yet, and it stays consistent across all three creator styles.

The part I'm trying to understand

For stateful (@InjectEntity) handlers, the same "command before the entity exists" situation behaves differently depending on the creator style:

Creator style	Injected entity when not yet created
no-arg	non-null, empty
id-based	non-null, id already filled in
event-based	null

The no-arg and id-based handlers get a non-null entity even though the entity was never created, because those constructors don't need an event, so the framework can build one. In plain Java that is logical, but from a user's point of view it feels surprising: you ask for an entity that was never created and get back a real-looking instance instead of "nothing".

The id-based case is the one I find most confusing. Because the id is already set, I couldn't find a reliable way for the handler to tell that the entity was never created

The docs also present the entity-centric and stateful styles as basically interchangeable, so I wasn't sure users would expect them to diverge here.

A direction I'd suggest

Treat "no events yet means the entity doesn't exist" the same way for every creator style and every handler style:

• @InjectEntity GiftCard card (the normal case): if it doesn't exist, the framework reports EntityNotFoundException for you, so you can't accidentally act on a blank one.
• @InjectEntity @Nullable GiftCard card: you get null when it doesn't exist, so you can do create-or-update yourself.

That gives one existence rule everywhere, independent of which constructor the entity uses.

Pros and cons of that approach

Pros	Cons
One rule everywhere. The "does it exist?" check is identical for all creator styles and both handler styles.	It is a behavior change on released code (5.1 is GA), so it would target 5.2 and needs a migration note.
Removes the case where a command on a never-created entity silently succeeds.	Handlers that today expect a non-null empty entity need a one-line tweak: mark the parameter @Nullable and check entity == null instead of a field.
The common case needs no null check and can't go wrong, because the framework guards it.	It needs new framework support (reading @Nullable on the parameter).
"May not exist" becomes explicit in the handler signature via @Nullable.	It is a bigger change than this PR, since it touches how the entity is loaded, so there is more to review.

There may well be reasons this direction is not feasible that I'm not aware of, and I realize it would be a larger redesign that needs more analysis. I mainly wanted to share my initial thoughts early and hear how you see it.