Merge branch 'main' into deprecate-v2

.vitepress/config.ts

@@ -23,8 +23,8 @@ if (!siteURL.pathname.endsWith('/'))  siteURL.pathname += '/'
 const redirectLinks: Record<string, string> = {}
 
 const latestVersions = {
-  java_services: '3.1.1',
-  java_cds4j: '3.1.0'
+  java_services: '3.2.0',
+  java_cds4j: '3.2.0'
 }
 
 const localSearchOptions = {

.vitepress/theme/components/ScrollToTop.vue

@@ -24,15 +24,20 @@ export default {
   },
   methods: {
     scrollToTop() {
-      window.scrollTo({ top: 0, behavior: 'auto' });
+      window.scrollTo({ top: 0, behavior: 'smooth' });
     },
   },
   mounted() {
-    window.addEventListener('scroll', () => {
-      const isVisible = window.scrollY > 240;
-      this.enableFadeInClass = isVisible;
-      this.enableFadeOutClass = !isVisible;
-    });
+    const isIOS = /iPad|iPhone|iPod/i.test(window.navigator.userAgent);
+    if (isIOS) { // iOS already has a system-wide scroll-to-top button at the top
+      this.visible = false;
+    } else {
+      window.addEventListener('scroll', () => {
+        const isVisible = window.scrollY > 240;
+        this.enableFadeInClass = isVisible;
+        this.enableFadeOutClass = !isVisible;
+      });
+    }
   },
 };
 </script>

advanced/hybrid-testing.md

@@ -329,6 +329,27 @@ cds bind --to-app-services bookshop-srv
 ```
 > This shortcut is only possible if you don't need to provide a `kind`.
 
+If your application has multiple service bindings of the same kind, `cds bind` will log warnings since they can not be resolved automatically. In this case you can resolve the ambiguities by adding the correct service instance name to the cds service configuration using the `vcap.name` property.
+
+Here is an example of adding `vcap.name` for services of kind `xsuaa`.
+
+```json
+"requires": {
+  "auth": {
+    "kind": "xsuaa",
+    "vcap": {
+      "name": "bookshop-auth1"
+    }
+  },
+  "auth2": {
+    "kind": "xsuaa",
+    "vcap": {
+      "name": "bookshop-auth2"
+    }
+  }
+}
+```
+
 ## `cds bind` Usage { #cds-bind-usage}
 
 ### By Cloud Service Only

get-started/troubleshooting.md

@@ -460,14 +460,6 @@ Options in [Saas Provisioning Service upgrade API](../guides/multitenancy/mtxs#e
 
 <div id="hana-ips" />
 
-#### Deployment fails — _Connection failed (RTE:[89013] Socket closed by peer_ {#connection-failed-89013}
-
-|  | Explanation |
-| --- | ---- |
-| _Root Cause_ | Your HANA Cloud instance is not accessible from your Kyma cluster. |
-| _Solution_ | Specify the trusted source IP addresses for your SAP HANA Cloud instance as described in this tutorial at [Step 11: Check SAP HANA Cloud trusted IP addresses](https://developers.sap.com/tutorials/btp-app-kyma-deploy-application.html#6dca3a73-b42a-4432-892d-a74803389e79).
-
-
 #### Deployment fails — _In USING declarations only main artifacts can be accessed, not sub artifacts of \<name\>_
 This error occurs if all of the following applies:
 + You [added native SAP HANA objects](../advanced/hana#add-native-objects) to your CAP model.

guides/databases-postgres.md

@@ -15,7 +15,7 @@ This guide focuses on the new PostgreSQL Service provided through *[@cap-js/post
 
 <div markdown="1" class="impl java">
 
-CAP Java SDK is tested on [PostgreSQL](https://www.postgresql.org/) 15. Most CAP features are supported on PostgreSQL.
+CAP Java 3 is tested on [PostgreSQL](https://www.postgresql.org/) 16 and most CAP features are supported on PostgreSQL.
 
 [Learn more about features and limitations of using CAP with PostgreSQL](../java/cqn-services/persistence-services#postgresql){.learn-more}
 
@@ -314,7 +314,7 @@ cds deploy --profile pg
 When deploying to Cloud Foundry, this can be accomplished by providing a simple deployer app. Similar to SAP HANA deployer apps, it is auto-generated for PostgreSQL-enabled projects by running
 
 ```sh
-cds build
+cds build --production
 ```
 
 ::: details What `cds build` does…

guides/providing-services.md

@@ -1033,6 +1033,8 @@ service Sue {
   entity Foo { key ID:Integer } actions {
     function getStock() returns Integer;
     action order (x:Integer) returns Integer;
+    //bound to the collection and not a specific instance of Foo
+    action customCreate (in: many $self, x: String) returns Foo;
   }
 }
 ```
@@ -1046,12 +1048,7 @@ The differentiation between *Actions* and *Functions* as well as *bound* and *un
 - **Actions** modify data in the server
 - **Functions** retrieve data
 - **Unbound** actions/functions are like plain unbound functions in JavaScript.
-- **Bound** actions/functions always receive the bound entity's primary key as implicit first argument, similar to `this` pointers in Java or JavaScript.
-
-::: tip Prefer *Unbound* Actions/Functions
-From CDS perspective we recommend **preferring unbound** actions/functions, as these are much more straightforward to implement and invoke.
-:::
-
+- **Bound** actions/functions always receive the bound entity's primary key as implicit first argument, similar to `this` pointers in Java or JavaScript. The exception are bound actions to collections, which are bound against the collection and not a specific instance of the entity. An example use case are custom create actions for the SAP Fiori elements UI.
 
 
 ### Implementing Actions / Functions

java/cds-data.md

@@ -432,7 +432,7 @@ book.put("ID", 97);
 book.put("title", "Dracula");
 ```
 
-You can now either define an accessor interface or use a [generated accessor interface](#generated-accessor-interfaces). 
+You can now either define an accessor interface or use a [generated accessor interface](#generated-accessor-interfaces).
 If you define an interface yourself, it could look like the following example:
 
 ```java
@@ -525,6 +525,40 @@ interface Equity {
 }
 ```
 
+#### Renaming Types in Java
+
+You might also want to rename the type of the entity. For this you can use annotation `@cds.java.this.name` to specify alternative name for the  accessor interfaces and [static model](./cqn-services/persistence-services#staticmodel) interfaces. This annotation can be used only on definitions and is ignored everywhere else.
+
+See the following example:
+
+```cds
+@cds.java.this.name: 'MyJavaClass'
+entity Class {
+  key ID: String;
+}
+```
+
+```java
+@CdsName("javaNames.Class")
+public interface MyJavaClass extends CdsData {
+  String ID = "ID";
+
+  @CdsName(ID)
+  String id();
+
+  @CdsName(ID)
+  MyJavaClass id(String id);
+
+  // rest of the interface
+}
+```
+
+In contrast with the annotation `@cds.java.name`, the annotation `@cds.java.this.name` does not rename projections of the annotated entity. If you want to rename chain of entities, you must annotate each of them individually.
+
+::: warning
+This feature requires version 8.2.0 of the [CDS Command Line Interface](/tools/cds-cli).
+:::
+
 #### Entity Inheritance in Java
 
 In CDS models it is allowed to extend a definition (for example, of an entity) with one or more named [aspects](../cds/cdl#aspects). The aspect allows to define elements or annotations that are common to all extending definitions in one place.

java/cqn-services/persistence-services.md

@@ -581,7 +581,7 @@ See [Class JdbcTemplate](https://docs.spring.io/spring-framework/docs/current/ja
 The static model and accessor interfaces can be generated using the [CDS Maven Plugin](../developing-applications/building#cds-maven-plugin).
 
 ::: warning _❗ Warning_
-Currently, the generator doesn't support using reserved [Java keywords](https://docs.oracle.com/javase/specs/jls/se13/html/jls-3.html#jls-3.9) as identifiers in the CDS model. Conflicting element names can be renamed in Java using the [@cds.java.name](../cds-data#renaming-elements-in-java) annotation.
+Currently, the generator doesn't support using reserved [Java keywords](https://docs.oracle.com/javase/specs/jls/se13/html/jls-3.html#jls-3.9) as identifiers in the CDS model. Conflicting element names can be renamed in Java using the [@cds.java.name](../cds-data#renaming-elements-in-java) annotation. For entities, you can use [@cds.java.this.name](../cds-data#renaming-types-in-java).
 :::
 
 #### Static Model in the Query Builder

node.js/cds-log.md

@@ -383,7 +383,7 @@ Since `@sap/cds^7.5`, running `cds add kibana-logging` or setting `cds.env.featu
 
 Further, there are two formatting aspects that are activated automatically, if appropriate, and add the following information to the loggable object:
 1. Running on Cloud Foundry: `tenant_subdomain`, `CF_INSTANCE_IP` and information from `VCAP_APPLICATION`
-1. Bound to an instance of the [SAP Application Logging Service for the Cloud Foundry Environment](https://help.sap.com/docs/application-logging-service/sap-application-logging-service/sap-application-logging-service-for-cloud-foundry-environment): `categories` and *custom fields* as described in [Custom Fields](#als-custom-fields)
+1. Bound to an instance of the [SAP Application Logging Service](https://help.sap.com/docs/application-logging-service/sap-application-logging-service/sap-application-logging-service-for-cloud-foundry-environment) or [SAP Cloud Logging](https://help.sap.com/docs/cloud-logging/sap-cloud-logging/what-is-sap-cloud-logging): `categories` and *custom fields* as described in [Custom Fields](#custom-fields)
 
 The following screenshot shows the log output for the rejection in the previous example with the JSON log formatter including the two aspects.
 
@@ -403,19 +403,20 @@ In case your application shares any sensitive data (for example, secrets) via he
 :::
 
 
-### Custom Fields { #als-custom-fields }
+### Custom Fields { #custom-fields }
 
 Information that is not included in the [list of supported fields](https://help.sap.com/docs/application-logging-service/sap-application-logging-service/supported-fields) of the SAP Application Logging Service can be shown as additional information. This information needs to be provided as custom fields.
 
-By default, the JSON formatter uses the following custom fields configuration, which is configurable using [cds.env](cds-env#cds-env):
+By default, the JSON formatter uses the following custom fields configuration for SAP Application Logging Service:
 
 ```jsonc
 {
   "log": {
     "als_custom_fields": {
       // <key>: <index>
-      "query": 0,               //> sql
-      "target": 1, "details": 2 //> generic validations
+      "query": 0,                //> sql
+      "target": 1, "details": 2, //> generic validations
+      "reason": 3                //> errors
     }
   }
 }
@@ -467,6 +468,22 @@ Without the additional custom field `query` and it's respective value, it would
 Before `@sap/cds^7.5`, the configuration property was called `kibana_custom_fields`. As Kibana is the dashboard technology and the custom fields are actually a feature of the SAP Application Logging Service, we changed the name to `als_custom_fields`. `kibana_custom_fields` is supported until `@sap/cds^8`.
 :::
 
+For SAP Cloud Logging, the JSON formatter uses the following default configuration:
+
+```jsonc
+{
+  "log": {
+    "cls_custom_fields": [
+      "query",             //> sql
+      "target", "details", //> generic validations
+      "reason"             //> errors
+    ]
+  }
+}
+```
+
+As always, both defaults are overridable via [cds.env](cds-env#cds-env).
+
 
 ## Request Correlation { #node-observability-correlation }
 
@@ -483,6 +500,13 @@ if (!cds.context) cds.context = { id }
 req.headers['x-correlation-id'] = cds.context.id
 ```
 
-The following screenshot shows an example for log correlation in a log analytic dashboard of the [SAP BTP Application Logging Service for Cloud Foundry Environment](https://help.sap.com/docs/application-logging-service).
+Subsequently, the JSON log formatter (see [Logging in Production](#logging-in-production)) sets the following fields:
+- `cds.context.id` &rarr; `correlation_id`
+- Request header `x_vcap_request_id` &rarr; `request_id`
+- Request header `traceparent` (cf. [W3C Trace Context](https://www.w3.org/TR/trace-context/)) &rarr; `w3c_traceparent`
+
+Specifically field `w3c_traceparent` is then used by both SAP Application Logging Service and SAP Cloud Logging to determine field `trace_id` in order to correlate requests, logs, and traces across multiple applications.
+
+The following screenshot shows an example for log correlation based on field `correlation_id` in a log analytic dashboard of the [SAP Application Logging Service for SAP BTP](https://help.sap.com/docs/application-logging-service).
 
 ![Default Formatter Output](assets/correlation.png)

node.js/fiori.md

@@ -23,20 +23,6 @@ See [Cookbook > Serving UIs > Draft Support](../advanced/fiori#draft-support) fo
 
 Lean draft is a new approach which makes it easier to differentiate between drafts and active instances in your code. This new architecture drastically reduces the complexity and enables more features like storing active instances in remote systems while keeping the corresponding drafts in the local persistence.
 
-### Enablement
-
-Lean draft is enabled by default. Add this to your `cds` configuration to disable the feature:
-
-```json
-{
-  "cds": {
-    "fiori": {
-      "lean_draft": false
-    }
-  }
-}
-```
-
 ### Handlers Registration {#draft-support}
 
 Class `ApplicationService` provides built-in support for Fiori Draft. All CRUD events are supported for both, active and draft entities.

tools/cds-cli.md

@@ -44,11 +44,11 @@ Use `cds version` to get information about your installed package version:
 <span class="cwd">$</span> <span class="cmd">cds</span> <span class="args">version</span>
 
 <em>@capire/samples:</em> 2.0.0
-<em>@sap/cds:</em> 8.1.1
-<em>@sap/cds-compiler:</em> 5.1.2
-<em>@sap/cds-dk:</em> 8.1.2
+<em>@sap/cds:</em> 8.2.1
+<em>@sap/cds-compiler:</em> 5.2.0
+<em>@sap/cds-dk:</em> 8.2.0
 <em>@sap/cds-dk (global):</em> 7.9.3
-<em>@sap/cds-mtxs:</em> 2.0.6
+<em>@sap/cds-mtxs:</em> 2.1.0
 <em>@sap/eslint-plugin-cds:</em> 3.0.4
 <em>Node.js:</em> v18.13.0
 <em>home:</em> .../node_modules/@sap/cds
@@ -58,9 +58,9 @@ Use `cds version` to get information about your installed package version:
 | @capire/samples        | https://github.com/sap-samples/cloud-cap-samples.git |
 |------------------------|------------------------------------------------------|
 | Node.js                | v18.13.0                                             |
-| @sap/cds               | 8.1.1                                                |
-| @sap/cds-compiler      | 5.1.2                                                |
-| @sap/cds-dk            | 8.1.2                                                |
+| @sap/cds               | 8.2.1                                                |
+| @sap/cds-compiler      | 5.2.0                                                |
+| @sap/cds-dk            | 8.2.0                                                |
 | @sap/eslint-plugin-cds | 3.0.4                                                |
 </pre>