Patch Release (#1819)

Author: renejeglinsky

about/best-practices.md

@@ -597,7 +597,7 @@ The *[Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architectur
 
 ... and he illustrated that like this:
 
-![Hexagonal architecture basic.gif](https://alistair.cockburn.us/wp-content/uploads/2018/02/Hexagonal-architecture-basic-1.gif)
+![Hexagonal architecture basic.gif](https://alistair.cockburn.us/hexFig1.png)
 
 In a nutshell, this introduction to the objectives of hexagonal architecture translates to that in our world of cloud-based business applications:
 

get-started/troubleshooting.md

@@ -397,11 +397,24 @@ On trial, your SAP HANA Cloud instance will be automatically stopped overnight,
 | _Root Cause_ | SAP HANA still claims exclusive ownership of the data that was once deployed through `hdbtabledata` artifacts, even though the CSV files are now deleted in your project.
 | _Solution_ | Add an _undeploy.json_ file to the root of your database module (the _db_ folder by default). This file defines the files **and data** to be deleted. See section [HDI Delta Deployment and Undeploy Allow List](https://help.sap.com/docs/HANA_CLOUD_DATABASE/c2b99f19e9264c4d9ae9221b22f6f589/ebb0a1d1d41e4ab0a06ea951717e7d3d.html) for more details.
 
-::: tip
-If you want to keep the data from _.csv_ files and data you've already added, see [SAP Note 2922271](https://me.sap.com/notes/2922271) for more details.
+
+#### How do I keep existing data?
+If you want to keep the data from _.csv_ files and data you've already added, apply [SAP Note 2922271](https://me.sap.com/notes/2922271).
+Depending on whether you have a single-tenant or multi-tenant application, see the following details for how to set the `path_parameter` and `undeploy` parameters:
+
+:::details Single-tenant applications {open}
+
+Use the _db/undeploy.json_ file as given in the SAP note.
+The _package.json_ file that is mentioned in the SAP note is located in the _db/_ folder.
+- If you don't find a _db/package.json_ file, use _gen/db/package.json_ (created by `cds build`) as a template and copy it to _db/package.json_.
+- After the modification, run `cds build --production` and verify your changes have been copied to _gen/db/package.json_.
+- Don't modify _gen/db/package.json_ as it is overwritten on every build.
+
 :::
 
-You can apply this solution also when using the `cds-mtxs` library. You can either set the options via the environment variable [`HDI_DEPLOY_OPTIONS`](https://help.sap.com/docs/SAP_HANA_PLATFORM/4505d0bdaf4948449b7f7379d24d0f0d/a4bbc2dd8a20442387dc7b706e8d3070.html), the CDS configuration or you can add them to the model update request as `hdi` parameter:
+:::details Multi-tenant applications
+
+Instead of configuring the static deployer application in _db/package.json_, use environment variable [`HDI_DEPLOY_OPTIONS`](https://help.sap.com/docs/SAP_HANA_PLATFORM/4505d0bdaf4948449b7f7379d24d0f0d/a4bbc2dd8a20442387dc7b706e8d3070.html), the `cds` configuration in _package.json_, or add the options to the model update request as `hdi` parameter:
 
 CDS configuration for [Deployment Service](../guides/multitenancy/mtxs#deployment-config)
 ```json
@@ -439,6 +452,11 @@ Options in [Saas Provisioning Service upgrade API](../guides/multitenancy/mtxs#e
 }
 ```
 
+:::
+
+After you have successfully deployed these changes to all affected HDI (tenant) containers (in all spaces, accounts etc.), you can remove the configuration again.
+
+
 ### How Do I Resolve Deployment Errors?
 
 #### Deployment fails — _Cyclic dependencies found_ or _Cycle between files_

guides/providing-services.md

@@ -771,6 +771,8 @@ The same applies for fields with the [OData Annotations](../advanced/odata#annot
 Do not use the `@readonly` annotation on keys in all variants.
 :::
 
+<div id="readonlywithexpressions"/>
+
 ### `@mandatory`
 
 Elements marked with `@mandatory` are checked for nonempty input: `null` and (trimmed) empty strings are rejected.
@@ -792,7 +794,7 @@ In addition to server-side input validation as introduced above, this adds a cor
 </Annotations>
 ```
 
-
+<div id="mandatorywithexpressions"/>
 
 ### `@Common.FieldControl`
 {#common-fieldcontrol}
@@ -962,7 +964,7 @@ entity Foo {
 }
 ```
 
-
+<div id="assertconstraints" />
 
 ## Custom Logic
 

java/_menu.md

@@ -20,6 +20,7 @@
 # [Messaging](messaging)
 # [Audit Logging](auditlog)
 # [Change Tracking](../../java/change-tracking)
+# [State Transitions](../../java/flows)
 # [Transactional Outbox](outbox)
 # [Multitenancy](../../java/multitenancy)
   ## [Multitenancy (Classic)](../../java/multitenancy-classic)

java/developing-applications/testing.md

@@ -21,7 +21,7 @@ As described in [Modular Architecture](building#starter-bundles#modular_architec
 Typical areas that require testing are the [services](../cqn-services/#cdsservices) that dispatch events to [event handlers](../event-handlers/), the event handlers themselves that implement the behaviour of the services, and finally the APIs that the application services define and that are exposed to clients through [OData](../cqn-services/application-services#odata-requests).
 
 ::: tip
-Aside from [JUnit](https://junit.org/junit5/), the [Spring framework](https://docs.spring.io/spring-framework/docs/current/reference/html/index.html) provides much convenience for both unit and integration testing, like dependency injection via [*autowiring*](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-factory-autowire) or the usage of [MockMvc](https://docs.spring.io/spring-framework/docs/current/reference/html/testing.html#spring-mvc-test-framework) and [*mocked users*]( https://docs.spring.io/spring-security/reference/servlet/test/method.html#test-method-withmockuser). So whenever possible, it's recommended to use it for writing tests.
+Aside from [JUnit](https://junit.org/junit5/), the [Spring framework](https://docs.spring.io/spring-framework/docs/current/reference/html/index.html) provides much convenience for both unit and integration testing, like dependency injection via [*autowiring*](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-factory-autowire) or the usage of [MockMvc](https://docs.spring.io/spring-framework/reference/testing/mockmvc.html) and [*mocked users*](https://docs.spring.io/spring-security/reference/servlet/test/method.html#test-method-withmockuser). So whenever possible, it's recommended to use it for writing tests.
 :::
 
 ## Sample Tests
@@ -222,7 +222,7 @@ For a more extensive version of the previous `CatalogServiceTest` snippets, have
 
 Integration tests enable us to verify the behavior of a custom event handler execution doing a roundtrip starting at the protocol adapter layer and going through the whole CAP architecture until it reaches the service and event handler layer and then back again through the protocol adapter.
 
-As the services defined in our `CDS model` are exposed as `OData` endpoints, by using [MockMvc](https://docs.spring.io/spring-framework/docs/current/reference/html/testing.html#spring-mvc-test-framework) we can simply invoke a specific `OData` request and assert the response from the addressed service.
+As the services defined in our `CDS model` are exposed as `OData` endpoints, by using [MockMvc](https://docs.spring.io/spring-framework/reference/testing/mockmvc.html) we can simply invoke a specific `OData` request and assert the response from the addressed service.
 
 The following demonstrates this by invoking a `GET` request to the `OData` endpoint of our `Books` entity, which triggers the execution of the `discountBooks` method of the `CatalogServiceHandler` in our example:
 
@@ -254,4 +254,4 @@ public class CatalogServiceITest {
 
 ::: tip
 Check out the version in our [CAP Java bookshop sample project](https://github.com/SAP-samples/cloud-cap-samples-java/blob/main/srv/src/test/java/my/bookshop/CatalogServiceITest.java) for additional examples of integration testing.
-:::
+:::

java/operating-applications/optimizing.md

@@ -17,7 +17,7 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/
 
 To minimize overhead at runtime, [monitoring](observability#monitoring) information is gathered rather on a global application level and hence might not be sufficient to troubleshoot specific issues.
 In such a situation, the use of more focused profiling tools can be an option.
-Typically, such tools are capable of focusing on a specific aspect of an application (for instance CPU or Memory management), but they come with an additional overhead and should only be enabled when needed. Hence, they need to meet the following requirements:
+Typically, such tools can focus on a specific aspect of an application (for instance CPU or Memory management), but they come with an additional overhead and should only be enabled when needed. Hence, they need to meet the following requirements:
 
 * Switchable at runtime
 * Use a communication channel not exposed to unauthorized users
@@ -28,20 +28,13 @@ How can dedicated Java tools access the running services in a secure manner? The
 ![This screenshot is explained in the accompanying text.](./assets/remote-tracing.png){width="600px"}
 
 As an authorized operator, you can access the container and start tools [locally](#profiling-local) in a CLI session running with the same user as the target process. Depending on the protocol, the JVM supports on-demand connections, for example, JVM diagnostic tools such as `jcmd`. Alternatively, additional JVM configuration is required as a prerequisite (JMX).
-A bunch of tools also support [remote](#profiling-remote) connections in a secure way. Instead of running the tool locally, a remote daemon is started as a proxy in the container, which connects the JVM with a remote profiling tool via an ssh tunnel.
 
 ### Local Tools { #profiling-local}
 
 Various CLI-based tools for JVMs are delivered with the SDK. Popular examples are [diagnostic tools](https://docs.oracle.com/javase/8/docs/technotes/guides/troubleshoot/toc.html) such as `jcmd`, `jinfo`, `jstack`, and `jmap`, which help to fetch basic information about the JVM process regarding all relevant aspects. You can take stack traces, heap dumps, fetch garbage collection events and read Java properties and so on.
 The SAP JVM comes with additional handy profiling tools: `jvmmon` and `jvmprof`. The latter, for instance,  provides a helpful set of traces that allow a deep insight into JVM resource consumption. The collected data is stored within a `prf`-file and can be analyzed offline in the [SAP JVM Profiler frontend](https://wiki.scn.sap.com/wiki/display/ASJAVA/Features+and+Benefits).
 
-### Remote Tools { #profiling-remote}
-
-It's even more convenient to interact with the JVM with a frontend client running on a local machine. As already mentioned, a remote daemon as the endpoint of an ssh tunnel is required. Some representative tools are:
-
-- [SAP JVM Profiler](https://wiki.scn.sap.com/wiki/display/ASJAVA/Features+and+Benefits) for SAP JVM with [Memory Analyzer](https://www.eclipse.org/mat/) integration. Find a detailed documentation how to set up a secure remote connection on [Profiling an Application Running on SAP JVM](https://help.sap.com/products/BTP/65de2977205c403bbc107264b8eccf4b/e7097737709842b7bb1c3b9bf3d688b6.html).
-
-- [JProfiler](https://www.ej-technologies.com/products/jprofiler/overview.html) is a popular Java profiler available for different platforms and IDEs.
+<span id="cfclijava" />
 
 ### Remote JMX-Based Tools { #profiling-jmx}
 

project-words.txt

@@ -17,3 +17,4 @@ Undeploying
 undiscloses
 unlocalized
 Woltmann
+asprof