Merge branch 'main' into rjegl01/secReview

Author: renejeglinsky

.vitepress/theme/components/indexFilter.ts

@@ -1,25 +1,23 @@
+const { base, themeConfig: { sidebar }} = global.VITEPRESS_CONFIG.site
 import { join } from 'node:path'
-import { ContentData, DefaultTheme, SiteConfig} from 'vitepress'
-type SBItem = DefaultTheme.SidebarItem
-
-// @ts-ignore
-const site = (global.VITEPRESS_CONFIG as SiteConfig<DefaultTheme.Config>).site
-const sidebar = site.themeConfig.sidebar! as SBItem[]
+import { ContentData, DefaultTheme } from 'vitepress'
 
 type ContentDataCustom = ContentData & {
   title?:string
 }
 
+type SBItem = DefaultTheme.SidebarItem
+
 export default (pages:ContentDataCustom[], basePath:string):ContentDataCustom[] => {
   let items = findInItems(basePath, sidebar) || []
   items = items.map(item => { return { ...item, link: item.link?.replace(/\.md$/, '') }})
-  const itemLinks = items.map(item => join(site.base, item.link||''))
+  const itemLinks = items.map(item => join(base, item.link||''))
 
   return pages
     .map(p => {
       const res = { ...p } // do not mutate original data
       res.url = res.url?.replaceAll('@external/', '')?.replace(/\/index$/, '/') || ''
-      res.url = join(site.base, res.url)
+      res.url = join(base, res.url)
       return res
     })
     .filter(p => {
@@ -40,20 +38,11 @@ export default (pages:ContentDataCustom[], basePath:string):ContentDataCustom[]
     }))
 }
 
-import {inspect} from 'node:util'
-inspect.defaultOptions.depth = 111
-
-function findInItems(url:string, items:SBItem[]=[], all:SBItem[]=[]) : SBItem[] {
+function findInItems(url:string, items:SBItem[]=[]):SBItem[]|undefined {
+  let res = items.find(item => item.link?.includes(url))
+  if (res)  return res.items
   for (const item of items) {
-    if (item.link?.includes(url)) {
-      // console.log(url, item.link)
-      all.push(item)
-    }
-    if (item.items) {
-      // console.log('>>', item.link || item.text)
-      findInItems(url, item.items, all)
-    }
-
+    const result = findInItems(url, item.items)
+    if (result)  return result
   }
-  return all
 }

guides/databases/index.md

@@ -25,9 +25,9 @@ The illustration below shows what happens automatically under the hood:
 > [!tip] Following the Calesi Pattern
 > The implementations of the CAP database layers follow the design principles of CAP-level Service Integration:
 > - Database Services are CAP services themselves, which...
-> - allows applications to extend them using standard CAP APIs
 > - provide database-agnostic interfaces to applications
 > - provide mocks for local development out of the box
+> - can be extended through event handlers, as any other CAP service
 
 > [!tip] Promoting Fast Inner-Loop Development
 > Through the ability to easily swap production-grade databases like SAP HANA with SQLite or H2 in-memory databases during development, without any changes to CDS models nor implementations, we greatly promote inner-loop development with fast turnaround cycles, as well as speeding up test pipelines and minimize TCD.

guides/databases/initial-data.md

@@ -41,7 +41,7 @@ You can also specify other folders by providing the `--out` option, e.g.:
 cds add data -o test/data
 ```
 
-
+Each file contains a CSV header line reflecting the structure of the entity to which it corresponds.
 
 ## Editing `.csv` Files 
 
@@ -68,7 +68,7 @@ cds add data --records 10
 ```
 
 > [!tip] AI-Generated Data
-> For more realistic domain-specific data, you can use AI tools, like CoPilot in VS Code, to assist you in that. This works particularly well for small to medium-sized datasets. Even more as CDS models provide easy to reason domain models, combined with strong typing information that AIs can leverage to generate fitting data samples.
+> For more realistic domain-specific data, you can use AI tools, like CoPilot in VS Code, to assist you in that. This works particularly well for small to medium-sized datasets. Moreover, CDS models provide domain models that are easy to reason about, with strong typing information, meaning that AIs can generate better fitting data samples.
 
 
 
@@ -78,7 +78,7 @@ Common rules apply to text content in `.csv` files, like:
 | ------------------------------------------------------------ | --------------------------- |
 | If texts contain commas, or line breaks, or trailing whitespaces | -> enclose in double quotes |
 | If texts contain double quotes                               | -> escape by doubling them  |
-| Numeric content shall be treated as texts                    | -> enclose in double quotes |
+| Numeric content should be treated as texts                   | -> enclose in double quotes |
 
 
 
@@ -158,13 +158,13 @@ myproject/
 
 All `db/data/*.csv` and  `srv/data/*.csv` files are automatically loaded, because they are located in a `data` folder next to `.cds` model sources.
 
-Additionally, this _in-the-neighborhood-of-models_ technique enables reuse packages, which's main purpose is to provide initial data. Such packages get installed via `npm` or `mvn`, and hence their content will reside under `node_modules` folders, or Maven `target` folders. As long as they also provide models through `.cds` sources, their data will be found and loaded.
+This is especially useful for remote service definitions imported with `cds import` (by default into `srv/external/`) so that data for such services can also be served when mocking.
 
 
 
 ## From Reuse Packages
 
-The [_in-the-neighborhood-of-models_](#next-to-cds-files) technique enables reuse packages, which's main purpose is to provide initial data. 
+The [_in-the-neighborhood-of-models_](#next-to-cds-files) technique enables reuse packages whose main purpose is to provide initial data. 
 
 Find an example for such a content reuse package at [*@capire/common*](https://github.com/capire/common) which showcases how one could provide ISO reuse data for `Countries`, `Currencies` and `Languages` code lists, as defined in [`@sap/cds/common`](../../cds/common). It essentially consists of these files as content:
 

guides/deploy/index.data.ts

@@ -2,8 +2,10 @@ import { basename } from 'node:path'
 import { createContentLoader } from 'vitepress'
 import filter from '../../.vitepress/theme/components/indexFilter.ts'
 
-export default createContentLoader([`**/guides/deploy/*.md`, `**/guides/multitenancy/*.md`], {
+const basePath = basename(__dirname)
+
+export default createContentLoader([`**/${basePath}/*.md`, `**/guides/multitenancy/*.md`], {
   transform(rawData) {
-    return filter(rawData, `/guides/`)
+    return filter(rawData, `/${basePath}/`)
   }
 })

guides/security/_menu.md

@@ -1,13 +1,13 @@
 
-# [Security Overview](overview)
-# [Authentication](authentication)
-# [CAP Users](cap-users)
-# [CAP Authorization](authorization)
-# [Remote Authentication](remote-authentication)
-# [Data Privacy Overview](data-privacy)
+# [Concepts & Architecture](overview)
+# [CAP-level Authentication](authentication)
+## [CAP Users](cap-users)
+## [Remote Authentication](remote-authentication)
+# [CAP-level Authorization](authorization)
+# [Data Protection](data-protection)
+# [Data Privacy](data-privacy)
 # [Annotating Personal Data](dpp-annotations)
 # [Automatic Audit Logging](dpp-audit-logging)
 # [Personal Data Management](dpp-pdm)
   <!-- ## [Data Retention Management](dpp-drm) -->
-# [Product Security Overview](data-protection)
 # [Product Security Standard](../../../guides/security/product-standards) <!-- INTERNAL -->

java/cds-data.md

@@ -668,6 +668,52 @@ Note, that the propagated annotation `@cds.java.name` creates attribute and meth
 This feature requires version 8.2.0 of the [CDS Command Line Interface](../tools/cds-cli).
 :::
 
+#### Excluding Elements
+
+You can exclude elements from accessor interfaces with the annotation `@cds.java.ignore`. 
+
+For example, you can exclude an element from the entity like this: 
+
+```cds
+namespace my.bookshop;
+
+entity Books {
+  key ID : Integer;
+  title  : localized String;
+  stock  : Integer;
+  @cds.java.ignore
+  ignored : String;
+}
+```
+
+This provides an interface that has no methods for the attribute `ignored`.
+
+On the service level, you can exclude elements from projections as well as operations and their arguments like this:
+
+```cds
+service CatalogService {
+  entity Books as
+    projection on my.Books {
+      ID,
+      @cds.java.ignore title,
+      stock,
+      ignored
+    }
+    actions {
+      @cds.java.ignore action act(@cds.java.ignore arg: String);
+      function                func(arg: String, @cds.java.ignore ignored: String) returns String;
+    }
+}
+```
+
+This annotation propagates across projections and they also omit the ignored elements. This can be overridden with the following annotation: 
+
+```cds
+annotate Books:ignored with @cds.java.ignore: false;
+```
+
+If you want to exclude a set of entities, prefer [filters](/java/developing-applications/building#filter-for-cds-entities) for the code generator.
+
 #### 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/index.data.ts

@@ -2,8 +2,10 @@ import { basename } from 'node:path'
 import { createContentLoader } from 'vitepress'
 import filter from '../.vitepress/theme/components/indexFilter.ts'
 
-export default createContentLoader([`**/java/*.md`, `**/java/**/index.md`], {
+const basePath = basename(__dirname)
+
+export default createContentLoader([`**/${basePath}/*.md`, `**/${basePath}/**/index.md`], {
   transform(rawData) {
-    return filter(rawData, `/java/`)
+    return filter(rawData, `/${basePath}/`)
   }
 })

menu.md

@@ -13,11 +13,11 @@
    ## [Domain Modeling](guides/domain/_menu.md)
    ## [Services & APIs](guides/services/_menu.md)
    ## [Serving UIs](guides/uis/_menu.md)
-   ## [Protocols](guides/protocols/_menu.md)
-   ## [Querying](guides/querying/_menu.md) <!-- UNRELEASED -->
    ## [Databases](guides/databases/_menu.md)
+   ## [Querying](guides/querying/_menu.md) <!-- UNRELEASED -->
+   ## [Protocols](guides/protocols/_menu.md)
+   ## [Integration](guides/integration/_menu.md)
    ## [Data Federation](guides/federation/_menu.md) <!-- UNRELEASED -->
-   ## [Service Integration](guides/integration/_menu.md)
    ## [Events & Messaging](guides/events/_menu.md)
    ## [Security & Data Privacy](guides/security/_menu.md)
    ## [Extensibility](guides/extensibility/_menu.md)

node.js/fiori.md

@@ -67,6 +67,10 @@ The `NEW` event is triggered when the user created a new draft.
 As a result `MyEntity.drafts` is created in the database.
 You can modify the initial draft data in a `before` handler.
 
+:::warning Known Limitation
+With the [`hdb` SAP HANA driver](https://www.npmjs.com/package/hdb), trying to `INSERT` draft entities with fields that use the [`LargeBinary` type](../cds/types#core-built-in-types) will cause a deadlock.
+The known workaround is to [configure your CAP app](../guides/databases/hana#setup-configuration) to use the [`hana-client` SAP HANA driver](https://www.npmjs.com/package/@sap/hana-client) instead.
+:::
 
 ### `EDIT`