Improve Error Handling target API (#2252)

Prefer showing targets via Messages API, as this allows collecting
multiple error messages and should be preferred in applications.

Also reduced usage of the String-based API, as this has limitations in
draft messages scenarios.

---------

Co-authored-by: René Jeglinsky <[email protected]>

Author: beckermarc

java/event-handlers/indicating-errors.md

@@ -149,8 +149,7 @@ To know which error codes and messages are available by default, you can have a
 ## Target
 
 When SAP Fiori interprets messages it can handle an additional `target` property, which, for example, specifies which element of an entity the message refers to. SAP Fiori can use this information to display the message along the corresponding field on the UI.
-When specifying messages in the `sap-messages` HTTP header, SAP Fiori mostly ignores the `target` value.
-Therefore, specifying the `target` can only correctly be used when throwing a `ServiceException` as SAP Fiori correctly handles the `target` property in OData V4 error responses.
+SAP Fiori interprets `target` property in OData V4 error messages and [draft state messages](../../advanced/fiori#validating-drafts). You can specify the `target` when throwing a `ServiceException` or when setting a validation error using the [Messages API](#messages).
 
 A message target is always relative to an input parameter in the event context.
 For CRUD-based events this is always the `cqn` parameter, which represents and carries the payload of the request.
@@ -162,7 +161,7 @@ By default a message target always refers to the CQN statement of the event. In
 As CRUD event handlers are often called from within bound actions or functions (e.g. `draftActivate`), CAP's OData adapter adds a parameter prefix to a message target referring to the `cqn` parameter only when required.
 
 ::: info
-When using the `target(String)` API, which specifices the full target as a `String`, no additional parameter prefixes are added by CAP's OData adapter. The `target` value is used as specified.
+When using the `target(String)` API, which specifies the full target as a `String`, no additional parameter prefixes are added by CAP's OData adapter. When using this API, [draft state messages](../../advanced/fiori#validating-drafts) can't be invalidated automatically on `PATCH`.
 :::
 
 Let's illustrate this with the following example:
@@ -208,63 +207,39 @@ Here, we have a `CatalogService` that exposes et al. the `Books` entity and a `B
 
 ### CRUD Events
 
-Within a `Before` handler that triggers on inserts of new books a message target can only refer to the `cqn` parameter:
+Within a `Before` handler that triggers on inserts of new books, a message target can only refer to the `cqn` parameter. You can use generic `String`-based APIs or a typed API backed by the interfaces generated from the CDS model:
 
-``` java
+```java
 @Before
 public void validateTitle(CdsCreateEventContext context, Books book) {
-    // ...
+    Messages messages = context.getMessages();
 
     // event context contains the "cqn" key
+    // target implicitly refers to cqn
+    messages.error("No title specified").target(b -> b.get("title"));
 
-    // implicitly referring to cqn
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "No title specified")
-        .messageTarget(b -> b.get("title"));
-
-    // which is equivalent to explicitly referring to cqn
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "No title specified")
-        .messageTarget("cqn", b -> b.get("title"));
+    // which is equivalent to a target explicitly referring to cqn
+    messages.error("No title specified").target("cqn", b -> b.get("title"));
 
-    // which is the same as using plain string
-    // assuming direct POST request
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "No title specified")
-        .messageTarget("title");
-
-    // which is the same as using plain string
-    // assuming surrounding bound action request with binding parameter "in",
-    // e.g. draftActivate
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "No title specified")
-        .messageTarget("in/title");
+    // using interfaces generated from the CDS model
+    messages.error("No title specified").target(Books_.class, b -> b.title());
 }
 ```
 
-Instead of using the generic API for creating the relative message target path, CAP Java SDK also provides a typed API backed by the CDS model:
-
-``` java
-@Before
-public void validateTitle(CdsCreateEventContext context, Books book) {
-    // ...
-
-    // implicitly referring to cqn
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "No title specified")
-        .messageTarget(Books_.class, b -> b.title());
-}
-```
+Depending on the OData request context, the resulting target in this example is either `title` (assuming a `POST` or `PATCH` request) or `in/title` (assuming a bound action like `draftActivate`).
 
-This also works for nested paths with associations:
+You can also specify targets that point to elements within associations:
 
-``` java
+```java
 @Before
 public void validateAuthorName(CdsCreateEventContext context, Books book) {
-    // ...
+    Messages messages = context.getMessages();
 
-    // using un-typed API
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "No title specified")
-        .messageTarget(b -> b.to("author").get("name"));
+    // using untyped API
+    messages.error("No title specified").target(b -> b.to("author").get("name"));
 
     // using typed API
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "No author name specified")
-        .messageTarget(Books_.class, b -> b.author().name());
+    messages.error("No title specified").target(Books_.class, b -> b.author().name());
 }
 ```
 
@@ -276,30 +251,25 @@ The same applies to message targets that refer to an action or function input pa
 ``` java
 @Before
 public void validateReview(BooksAddReviewContext context) {
-    // ...
-
+    Messages messages = context.getMessages();
     // event context contains the keys "reviewer", "rating", "title", "text",
     // which are the input parameters of the action "addReview"
 
     // referring to action parameter "reviewer", targeting "firstName"
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid reviewer first name")
-        .messageTarget("reviewer", r -> r.get("firstName"));
+    messages.error("Invalid reviewer first name").target("reviewer", r -> r.get("firstName"));
 
     // which is equivalent to using the typed API
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid reviewer first name")
-        .messageTarget(BooksAddReviewContext.REVIEWER, Reviewer_.class, r -> r.firstName());
+    messages.error("Invalid reviewer first name")
+        .target(BooksAddReviewContext.REVIEWER, Reviewer_.class, r -> r.firstName());
 
     // targeting "rating"
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid review rating")
-        .messageTarget("rating");
+    messages.error("Invalid review rating").target("rating");
 
     // targeting "title"
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid review title")
-        .messageTarget("title");
+    messages.error("Invalid review title").target("title");
 
      // targeting "text"
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid review text")
-        .messageTarget("text");
+    messages.error("Invalid review text").target("text");
 }
 ```
 
@@ -310,27 +280,21 @@ For the `addReview` action that is the `Books` entity, as in the following examp
 ``` java
 @Before
 public void validateReview(BooksAddReviewContext context) {
-    // ...
-
+    Messages messages = context.getMessages();
     // referring to the bound entity `Books`
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid book description")
-        .messageTarget(b -> b.get("descr"));
-
-    // or (using the typed API, referring to "cqn" implicitly)
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid book description")
-        .messageTarget(Books_.class, b -> b.descr());
+    messages.error("Invalid book description").target(b -> b.get("descr"));
 
-    // which is the same as using plain string
-    throw new ServiceException(ErrorStatuses.BAD_REQUEST, "Invalid book description")
-        .messageTarget("in/descr");
+    // or using the typed API
+    messages.error("Invalid book description").target(Books_.class, b -> b.descr());
 }
 ```
 
+In the case of OData the resulting target is `in/descr`, assuming the default name `in` is used for the binding parameter name.
+
 ::: tip
-The previous examples showcase the target creation with the `ServiceException` API, but the same can be done with the `Message` API and the respective `target(...)` methods.
+The previous examples showcase the target creation with the `Messages` API, but the same can be done with the `ServiceException` API and the respective `messageTarget(...)` methods.
 :::
 
-
 ## Error Handler { #errorhandler}
 
 An [exception](#exceptions) thrown in an event handler will stop the processing of the request. As part of that, protocol adapters trigger the `ERROR_RESPONSE` event of the [Application Lifecycle Service](https://www.javadoc.io/doc/com.sap.cds/cds-services-api/latest/com/sap/cds/services/application/ApplicationLifecycleService.html). By default, this event combines the thrown exception and the [messages](#messages) from the `RequestContext` in a list to produce the error response. OData V4 and V2 protocol adapters will use this list to create an OData error response with the first entry being the main error and the remaining entries in the details section.