Java: Docs for improved event handler signatures

[beckermarc]

• Arbitrary return types
• Service arguments
• Entity reference arguments

[vmikhailenko]

Whole statements are left for generic handlers?

[BraunMatthias]

I'd omit this option as the entity argument is redundant

[beckermarc]

This matches the documentation structure that we also when describing the same concept for events based on contexts and entities based on data accessor interfaces. I'd keep it symmetrical for now.

[vmikhailenko]

Maybe we should also add some kind of "when-to-use-what" tips or guidelines: e.g. prefer tight and typed signatures for the handlers first, switch to the more generic versions if you really want to write a generic handler.

E.g. Books_ ref, CatalogService service is better because [reason], the Books book, Books_ ref, CatalogService service also possible if I want to have payload and the ref together.

[beckermarc]

Whole statements are left for generic handlers?

There is actually not really a great use case for these so far, so I'd keep that a hidden feature for now. The reference has proven much more useful.

[beckermarc]

Maybe we should also add some kind of "when-to-use-what" tips or guidelines: e.g. prefer tight and typed signatures for the handlers first, switch to the more generic versions if you really want to write a generic handler.

That's actually not so easy and highly depends on the logic that is within the event handler method I think. I guess we still need to learn from some good examples for these new possibilities to be able to document something here.

[vmikhailenko]

Maybe we should also add some kind of "when-to-use-what" tips or guidelines: e.g. prefer tight and typed signatures for the handlers first, switch to the more generic versions if you really want to write a generic handler.

That's actually not so easy and highly depends on the logic that is within the event handler method I think. I guess we still need to learn from some good examples for these new possibilities to be able to document something here.

That is exactly why "when-to-use-what" is beneficial. Hard choice.

[vmikhailenko]

Maybe also mention that event handler returning a collection of entities will lead to broken result in case of queries with $count. I remember more than one issue about this. This is very hard to figure that out without documentation. Or we should fix it for good.

[beckermarc]

Maybe also mention that event handler returning a collection of entities will lead to broken result in case of queries with $count. I remember more than one issue about this. This is very hard to figure that out without documentation. Or we should fix it for good.

That's something that is mentioned here: https://pages.github.tools.sap/cap/docs/java/cqn-services/application-services#read-result. Which is also somehow linked from this page. I will improve the link however to link to the upper section instead.

[vmikhailenko]

Whole statements are left for generic handlers?

There is actually not really a great use case for these so far, so I'd keep that a hidden feature for now. The reference has proven much more useful.

Extend the statement to fetch something in addition?

Why hide it? It will be very strange later if we decide to use it somewhere in the samples or as a recommendation.

[beckermarc]

Extend the statement to fetch something in addition?

Why hide it? It will be very strange later if we decide to use it somewhere in the samples or as a recommendation.

You can always get it from the context as well. There are rare scenarios where you would benefit from not using the context, because you are registering on multiple events. The main reason I don't want to add it now, is that I can't give good reasons when to use it. We can always add it later on, if we find great use cases for that in our samples.

[vmikhailenko]

Extend the statement to fetch something in addition?

Why hide it? It will be very strange later if we decide to use it somewhere in the samples or as a recommendation.

You can always get it from the context as well. There are rare scenarios where you would benefit from not using the context, because you are registering on multiple events. The main reason I don't want to add it now, is that I can't give good reasons when to use it. We can always add it later on, if we find great use cases for that in our samples.

Why not mention this as a technical possibility then? Not blocking anything, I just remember me being confused that I have no reference point to give to stakeholder.

[beckermarc]

Why not mention this as a technical possibility then?

To me it doesn't feel right to promote this feature at the moment, because it doesn't really fill a gap, as it:
a) Doesn't provide the possibility to get a typed object (like for data, reference and service arguments)
b) Somehow is going into the direction of getting event context arguments, which we however don't support for anything else.

Obtaining statements from the context is as good as getting them into the event handler directly (even better, as from the context we can derive event names). That's why I am hesitant to document and promote it.

[vmikhailenko]

Maybe also mention that event handler returning a collection of entities will lead to broken result in case of queries with $count. I remember more than one issue about this. This is very hard to figure that out without documentation. Or we should fix it for good.

That's something that is mentioned here: https://pages.github.tools.sap/cap/docs/java/cqn-services/application-services#read-result. Which is also somehow linked from this page. I will improve the link however to link to the upper section instead.

Maybe a warning then? It is very unexpected behaviour, especially in @After handler.
Non-blocker, again, just an ask.

[beckermarc]

Maybe a warning then? It is very unexpected behaviour, especially in @after handler.
Non-blocker, again, just an ask.

We can make the text in the application service section more explicit and add a warning to the count docs there I think.