Consolidate Entity discovery for Entity-centric and Stateful-Handler-centric

[smcvb]

First and foremost, this pull request introduces a new test suite in the axon-integrationtest module.
The test includes 9 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, non-nullable entity injection, no-arg entity creator
5. Stateful-command-handler-centric, nullable entity injection, no-arg entity creator
6. Stateful-command-handler-centric, non-nullable entity injection, id-based entity creator
7. Stateful-command-handler-centric, nullable entity injection,id-based entity creator
8. Stateful-command-handler-centric, non-nullable entity injection, first-event-based entity creator
9. Stateful-command-handler-centric, nullable entity injection,first-event-based entity creator

For all 9 styles, we have two tests:

1. Dispatch creational command for the entity - succeeds for entity-centric and nullable entity stateful-command-handler-centric. Fails for non-null entity stateful-command-handler-centric since non-null is expected.
2. Dispatch instance command for the entity - fails for entity-centric, fails for non-null entity stateful-command-handler-centric, succeeds for nullable entity 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.
4. Adjust the InjectEntityParameterResolver to check for the @Nullable annotation, as well as document this behavior.

[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.

[MateuszNaKodach]

Good job, but I (and my friend Klaudiusz) had a few finidings :)

[hatzlj]

I like the addition to support Optional and @Nullable, that makes a very clear API for handler methods. Only some nits and one comment/idea on the EventSourcedEntityFactory.create contract

[MateuszNaKodach]

Good job! :) I left one minor thing and replied your comments. I believe you will introduce the change with the exceptions :)

[MateuszNaKodach]

No, I agree - I believe it's a must, but we need to make it clear :)

[MateuszNaKodach]

Yes, I'd keep just EntityNotFoundException.