Merge pull request #982 from cap-js/main

May Release

Author: renejeglinsky

.github/renovate.json

@@ -8,7 +8,8 @@
   "includePaths": [
     ".vitepress/config.ts",
     ".github/workflows/",
-    "package.json"
+    "package.json",
+    "**/*.md"
   ],
   "packageRules": [
     {
@@ -27,10 +28,15 @@
     {
       "matchDepTypes": ["action"],
       "groupName": "Github actions"
+    },
+    {
+      "matchFileNames": [ "**/*.md" ],
+      "separateMajorMinor": false
     }
   ],
-  "regexManagers": [
+  "customManagers": [
     {
+      "customType": "regex",
       "fileMatch": [ ".vitepress/config.ts" ],
       "matchStrings": [
         "java_services\\s*:\\s*'(?<currentValue>.*?)'"
@@ -40,6 +46,7 @@
       "versioningTemplate": "maven"
     },
     {
+      "customType": "regex",
       "fileMatch": [ ".vitepress/config.ts" ],
       "matchStrings": [
         "java_cds4j\\s*:\\s*'(?<currentValue>.*?)'"
@@ -49,6 +56,7 @@
       "versioningTemplate": "maven"
     },
     {
+      "customType": "regex",
       "fileMatch": ["\\.md$"],
       "matchStrings": [
         "<em>\\s*@sap/cds:\\s*</em>\\s*(?<currentValue>\\d+\\.\\d+\\.\\d+)",
@@ -58,6 +66,7 @@
       "datasourceTemplate": "npm"
     },
     {
+      "customType": "regex",
       "fileMatch": ["\\.md$"],
       "matchStrings": [
         "<em>\\s*@sap/cds-compiler:\\s*</em>\\s*(?<currentValue>\\d+\\.\\d+\\.\\d+)",
@@ -67,6 +76,7 @@
       "datasourceTemplate": "npm"
     },
     {
+      "customType": "regex",
       "fileMatch": ["\\.md$"],
       "matchStrings": [
         "<em>\\s*@sap/cds-dk:\\s*</em>\\s*(?<currentValue>\\d+\\.\\d+\\.\\d+)",
@@ -76,6 +86,7 @@
       "datasourceTemplate": "npm"
     },
     {
+      "customType": "regex",
       "fileMatch": ["\\.md$"],
       "matchStrings": [
         "<em>\\s*@sap/cds-mtxs:\\s*</em>\\s*(?<currentValue>\\d+\\.\\d+\\.\\d+)",
@@ -85,6 +96,7 @@
       "datasourceTemplate": "npm"
     },
     {
+      "customType": "regex",
       "fileMatch": ["\\.md$"],
       "matchStrings": [
         "<em>\\s*@sap/eslint-plugin-cds:\\s*</em>\\s*(?<currentValue>\\d+\\.\\d+\\.\\d+)",
@@ -94,6 +106,7 @@
       "datasourceTemplate": "npm"
     },
     {
+      "customType": "regex",
       "fileMatch": ["\\.md$"],
       "matchStrings": [
         "<em>\\s*Node.js:\\s*</em>\\s*(?<currentValue>v\\d+\\.\\d+\\.\\d+)",

.vitepress/config.ts

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

.vitepress/theme/Layout.vue

@@ -59,7 +59,7 @@ const { frontmatter } = useData()
   margin-left: auto;
 }
 
-@media (max-width: 768px) {
+@media (max-width: 960px) {
   .ImplVariantsInNavbar {
     display: none;
   }

.vitepress/theme/custom.scss

@@ -129,7 +129,7 @@ main {
           color: #032F62;
           .dark & { color: #9ECBFF; }
         }
-        &.flags {
+        &.flags, &.option, &.posArg {
           color: #005CC5;
           .dark & { color: #79B8FF; }
         }
@@ -399,3 +399,11 @@ html.node .java {
 @media (min-width: 1024px) {
   .VPNavBarSearch { padding-left: 12px; }
 }
+
+// make sidebar content scroll nicely underneath the logo
+@media (min-width: 960px) {
+  header .title {
+    background-color: var(--vp-sidebar-bg-color);
+  }
+}
+

about/features.md

@@ -40,7 +40,7 @@ Following is an index of the features currently covered by CAP, with status and
 | CLI commands                                                                    |                            |
 |---------------------------------------------------------------------------------|----------------------------|
 | [Jump-start cds-based projects](../get-started/in-a-nutshell#jumpstart)         | `cds init <project>`       |
-| Add a feature to an existing project                                            | `cds add <facets>`         |
+| [Add a feature to an existing project](../tools/cds-cli#cds-add)                | `cds add <facets>`         |
 | [Add models from external sources](../guides/using-services#local-mocking)      | `cds import <api>`         |
 | [Compile cds models to different outputs](../node.js/cds-compile)               | `cds compile <models>`     |
 | [Run your services in local server](../node.js/cds-serve)                       | `cds serve <services>`     |
@@ -162,12 +162,12 @@ Following is an index of the features currently covered by CAP, with status and
 
 <br>
 
-| Outbound Protocol Support                                 | CDS <sup>1</sup> | Node.js | Java |
-|-----------------------------------------------------------|:----------------:|:-------:|:----:|
-| [REST/OpenAPI](../node.js/cds-dk#cds-import-from-openapi) |       <X/>       |  <X/>   | <X/> |
-| OData V2                                                  |       <X/>       |  <X/>   | <X/> |
-| OData V4                                                  |       <X/>       |  <X/>   | <X/> |
-| GraphQL<sup>2</sup>                                       |       <C/>       |  <C/>   | <C/> |
+| Outbound Protocol Support                                        | CDS <sup>1</sup> | Node.js | Java |
+|------------------------------------------------------------------|:----------------:|:-------:|:----:|
+| [REST/OpenAPI](../tools/apis/cds-import#cds-import-from-openapi) |       <X/>       |  <X/>   | <X/> |
+| OData V2                                                         |       <X/>       |  <X/>   | <X/> |
+| OData V4                                                         |       <X/>       |  <X/>   | <X/> |
+| GraphQL<sup>2</sup>                                              |       <C/>       |  <C/>   | <C/> |
 
 > <sup>1</sup> Import API to CSN <br>
 > <sup>2</sup> Could be a good case for 3rd-party contribution <br>

about/index.md

@@ -36,17 +36,36 @@ CAP-based projects benefit from a **[primary focus on domain](#domain-modeling)*
 
 The CAP framework features a mix of proven and broadly adopted open-source and SAP technologies, as highlighted in the figure below.
 
-<img src="../assets/overview.drawio.svg" style="width:450px; margin: auto" alt="The graphic is explained in the accompanying text.">
+<img src="../assets/overview.drawio.svg" style="width:480px; margin: auto" alt="The graphic is explained in the accompanying text.">
 
 <div id="logos" style="text-align:center;">
   <img src="../assets/logos/nodejs.svg" style="height:40px" alt="Node.js logo" />
-  <img src="../assets/logos/express.png" style="height:30px" alt="Express logo"/>
-  <img src="../assets/logos/java.svg" style="height:44px" alt="Java logo"/>
+  <img src="../assets/logos/express.png" style="height:34px" alt="Express logo"/>
+  <img src="../assets/logos/java.svg" style="height:44px;margin-top:-10px;" alt="Java logo"/>
   <img src="../assets/logos/spring.svg" style="height:25px" alt="spring logo" />
 </div>
 
 <style scoped>
-  #logos img { display:inline-block; margin: 12px;align-items:center;vertical-align:middle }
+  #logos {
+    margin: 24px auto;
+    max-width: 280px;
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    justify-content: center;
+    align-items: center;
+    gap: 12px;
+  }
+
+  #logos img {
+    margin: 4px auto;
+  }
+
+  @media (min-width: 500px) {
+    #logos {
+      max-width: 500px;
+      grid-template-columns: repeat(4, 1fr);
+    }
+  }
 </style>
 
 On top of open source technologies, CAP mainly adds:
@@ -72,7 +91,7 @@ That might sound like a contradiction, but isn't: While CAP certainly gives *opi
 | **Higher-level concepts and APIs** abstracting from and avoiding lock-ins to low-level platform features and protocols | All abstractions follow a glass-box pattern that allows unrestricted access to lower-level things, if required |
 | **Best Practices served out of the box** with generic solutions for many recurring tasks | You can always handle things your way in [custom handlers](../guides/providing-services#custom-logic), decide whether to adopt [CQRS](#cqrs) or [Event Sourcing](#event-sourcing), for example ... while CAP simply tries to get the tedious tasks out of your way. |
 | **Out-of-the-box support** for <br> **[SAP Fiori](https://developers.sap.com/topics/ui-development.html)** and **[SAP HANA](https://developers.sap.com/topics/hana.html)** | You can also choose other UI technologies, like [Vue.js](../get-started/in-a-nutshell#vue), or databases, by providing new database integrations. |
-| **Dedicated tools support** provided in [SAP Business Application Studio](../tools/cds-editors#bastudio) or [Visual Studio Code](../tools/cds-editors#vscode). | CAP doesn't depend on those tools. Everything in CAP can be done using the [`@sap/cds-dk`](../get-started/jumpstart) CLI and any editor or IDE of your choice. |
+| **Dedicated tools support** provided in [SAP Business Application Studio](../tools/cds-editors#bas) or [Visual Studio Code](../tools/cds-editors#vscode). | CAP doesn't depend on those tools. Everything in CAP can be done using the [`@sap/cds-dk`](../get-started/jumpstart) CLI and any editor or IDE of your choice. |
 
 
 

advanced/fiori.md

@@ -436,7 +436,7 @@ You can't project from draft-enabled entities, as annotations are propagated. Ei
 :::
 
 ### Difference between Compositions and Associations
-Be aware that all compositions of the draft enabled entity are part of the same draft. Only those entities will get a `CREATE` button in SAP Fiori elements UIs as they are part of the draft. Associated entities on the other side can only be deleted or modified. Note that, for associations the changes are directly applied instead of being applied once changes are saved to the active version.
+Be aware that you must not modify associated entities through drafts. Only compositions will get a "Create" button in SAP Fiori elements UIs because they are stored as part of the same draft entity.
 
 ### Enabling Draft for [Localized Data](../guides/localized-data) {#draft-for-localized-data}
 
@@ -646,6 +646,20 @@ If you have the need for a more complex calculation, then the interesting parts
 :::
 
 
+## Cache Control
+
+CAP provides the option to set a [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header with a [max-age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#max-age) directive to indicate that a response remains fresh until _n_ seconds after it was generated .
+In the CDS model, this can be done using the `@http.CacheControl: {maxAge: <seconds>}` annotation on stream properties. The header indicates that caches can store the response and reuse it for subsequent requests while it's fresh.
+The `max-age` (in seconds) specifies the maximum age of the content before it becomes stale.
+
+:::info Elapsed time since the response was generated
+The `max-age` is the elapsed time since the response was generated on the origin server. It's not related to when the response was received.
+:::
+
+::: warning Only Java
+Cache Control feature is currently supported on the Java runtime only.
+:::
+
 <div id="client-side-validations" />
 
 <div id="fiori-compat" />

advanced/hana.md

@@ -48,6 +48,7 @@ Steps to match the signature of a database object in a facade entity:
 * Choose the names of the facade entity's elements, which are identical to the resulting database names of the existing database object's column names.
 * After applying the CDS-to-DB type mapping, check that the types of the facade entity's elements match the types of the database object's columns.
 * For a view, table function, or calculation view with parameters, check that the parameter names and types match, too.
+  Functions with table-like input parameters are not supported.
 
 > Note: If a field of that entity is defined as `not null` and you want to disable its runtime check, you can add [`@assert.notNull: false`](../guides/providing-services#assert-notNull). This is important if you want to use, for example [SAP HANA history tables](https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/d0b2c5142a19405fb912f71782cd0a84.html).
 

advanced/odata.md

@@ -656,7 +656,7 @@ The following operators and clauses of CDL are supported:
 
 * `case when ... then ... else ...` and the logical ternary operator ` ? : `
 * Logical: `and`,  `or`,  `not`
-* Relational: `=`, `<>`,  `!=`,  `<`,  `<=`,  `>`,  `>=`, `in`, `between ... and`
+* Relational: `=`, `<>`,  `!=`,  `<`,  `<=`,  `>`,  `>=`, `in`, `between ... and ...`
 * Unary `+` and `-`
 * Arithmetic: `+`,  `-`,  `*`,  `/`, `||`
 * `cast(...)`