Merge branch 'main' into rjegl08/switchSampleLinks

Author: renejeglinsky

get-started/in-a-nutshell.md

@@ -17,6 +17,28 @@ Build Your First App with CAP {.subtitle}
 
 
 
+::: details Optionally clone sample from GitHub ...
+
+The sections below describe a hands-on walkthrough, in which you'd create a new project and fill it with content step by step. Alternatively, you can fast forward and get the final sample content from GitHub as follows:
+
+::: code-group
+
+```sh [Node.js]
+git clone https://github.com/capire/bookshop
+cd bookshop
+npm install
+```
+
+```sh [Java]
+git clone https://github.com/sap-samples/cloud-cap-samples-java bookshop
+```
+
+Note: When comparing the code from the repo in GitHub to the snippets given in the sections below you will recognise additions showcasing enhanced features. So, what you find in there is a superset of what we describe in this getting started guide.
+
+:::
+
+
+
 ## Jumpstart a Project {#jumpstart}
 
 
@@ -88,28 +110,6 @@ After you completed the [*Initial Setup*](./), you jumpstart a project as follow
 
    :::
 
-
-::: details Optionally clone sample from GitHub ...
-
-The sections below describe a hands-on walkthrough, in which you'd create a new project and fill it with content step by step. Alternatively, you can get the final sample content from GitHub as follows:
-
-::: code-group
-
-```sh [Node.js]
-git clone https://github.com/capire/bookshop
-cd bookshop
-```
-
-```sh [Java]
-git clone https://github.com/sap-samples/cloud-cap-samples-java bookshop
-```
-
-Note: When comparing the code from the *cap/samples* on GitHub to the snippets given in the sections below you will recognise additions showcasing enhanced features. So, what you find in there is a superset of what we describe in this getting started guide.
-
-:::
-
-
-
 ## Capture Domain Models
 
 
@@ -148,7 +148,7 @@ entity Genres : sap.common.CodeList { // [!code focus]
 ```
 :::
 
-*Find this source also in `capire/bookshop` [for Node.js](https://github.com/capire/bookshop/blob/main/db/schema.cds), and [for Java](https://github.com/SAP-samples/cloud-cap-samples-java/blob/main/db/books.cds)*{ .learn-more}
+_Find this source also in the GitHub repos [for Node.js](https://github.com/capire/bookshop/tree/main/db/schema.cds), and [for Java](https://github.com/sap-samples/cloud-cap-samples-java/blob/main/db/books.cds)_{ .learn-more}
 [Learn more about **Domain Modeling**.](../guides/domain-modeling){ .learn-more}
 [Learn more about **CDS Modeling Languages**.](../cds/){ .learn-more}
 
@@ -160,7 +160,7 @@ entity Genres : sap.common.CodeList { // [!code focus]
 As soon as you save the *schema.cds* file, the still running `cds watch` reacts immediately with new output like this:
 
 ```log
-[cds] - connect to db > sqlite { database: ':memory:' }
+[cds] - connect to db > sqlite { url: ':memory:' }
 /> successfully deployed to in-memory database.
 ```
 
@@ -246,7 +246,7 @@ service CatalogService @(path:'/browse') { // [!code focus]
 ```
 :::
 
-*Find this source also on GitHub [for Node.js](https://github.com/capire/bookshop/tree/main/srv), and [for Java](https://github.com/SAP-samples/cloud-cap-samples-java/tree/main/srv)*{.learn-more}
+*Find this source also on GitHub [for Node.js](https://github.com/capire/bookshop/tree/main/srv), and [for Java](https://github.com/sap-samples/cloud-cap-samples-java/blob/main/srv)*{.learn-more}
 
 [Learn more about **Defining Services**.](../guides/providing-services){ .learn-more}
 
@@ -259,13 +259,20 @@ service CatalogService @(path:'/browse') { // [!code focus]
 This time `cds watch` reacted with additional output like this:
 
 ```log
-[cds] - serving AdminService { at: '/odata/v4/admin' }
-[cds] - serving CatalogService { at: '/browse' }
-
+[cds] - serving AdminService {
+  at: [ '/admin' ],
+  decl: 'srv/admin-service.cds:2',
+  impl: 'srv/admin-service.js'
+}
+[cds] - serving CatalogService {
+  at: [ '/browse', '/rest/catalog', '/hcql/catalog' ],
+  decl: 'srv/cat-service.cds:4',
+  impl: 'srv/cat-service.js'
+}
 [cds] - server listening on { url: 'http://localhost:4004' }
 ```
 
-As you can see, the two service definitions have been compiled and generic service providers have been constructed to serve requests on the listed endpoints _/odata/v4/admin_ and _/browse_.
+As you can see, the two service definitions have been compiled and generic service providers have been constructed to serve OData requests on the listed endpoints _/admin_ and _/browse_.
 
 </span>
 
@@ -377,7 +384,7 @@ ID,name
 ::: details `cds add data` can help you with the file and record generation
 Create empty CSV files with header lines only:
 
-```sh 
+```sh
 cds add data
 ```
 
@@ -389,24 +396,20 @@ cds add data --records 10
 [Find the full set of options here.](../tools/cds-cli.md#data){.learn-more}
 :::
 
-[Find a full set of `.csv` files in **capire/bookshop**.](https://github.com/capire/bookshop/tree/main/db/data){ .learn-more target="_blank"}
-
 <span class="impl node">
 
 After you've added these files, `cds watch` restarts the server with output, telling us that the files have been detected and their content has been loaded into the database automatically:
 
 ```log
 [cds] - connect to db > sqlite { url: ':memory:' }
-  > init from db/init.js
-  > init from db/data/sap.capire.bookshop-Genres.csv
-  > init from db/data/sap.capire.bookshop-Books.texts.csv
-  > init from db/data/sap.capire.bookshop-Books.csv
-  > init from db/data/sap.capire.bookshop-Authors.csv
+ > init from db/init.js
+ > init from db/data/sap.capire.bookshop-Authors.csv
+ > init from db/data/sap.capire.bookshop-Books.csv
+ > init from db/data/sap.capire.bookshop-Books_texts.csv
+ > init from db/data/sap.capire.bookshop-Genres.csv
 /> successfully deployed to in-memory database.
 ```
 
-> Note: This is the output when you're using the [bookshop sample](https://github.com/capire/bookshop). It's less if you've followed the manual steps here.
-
 </span>
 
 <span class="impl java">
@@ -511,7 +514,7 @@ CAP provides out-of-the-box support for SAP Fiori UIs, for example, with respect
 ### Vue.js UIs {#vue .impl .node}
 
 Besides Fiori UIs, CAP services can be consumed from any UI frontends using standard AJAX requests.
-For example, you can [find a simple Vue.js app in **capire/bookshop**](https://github.com//capire/bookshop/tree/main/app/vue), which demonstrates browsing and ordering books using OData requests to [the `CatalogService` API we defined above](#services). {.impl .node}
+For example, you can [find a simple Vue.js app in the GitHub repo](https://github.com/capire/bookshop/tree/main/app/vue), which demonstrates browsing and ordering books using OData requests to [the `CatalogService` API we defined above](#services). {.impl .node}
 
 ![Shows the famous bookshop catalog service in a simple Vue.js UI.](assets/vue-app.png){style="margin:0" .impl .node .adapt}
 
@@ -540,7 +543,7 @@ bookshop/
 └─ ...
 ```
 
-[See these files also in **capire/bookshop** in the _srv_ folder.](https://github.com//capire/bookshop/tree/main/srv){.learn-more}
+[See these files also in the GitHub repo.](https://github.com/capire/bookshop/tree/main/srv){.learn-more}
 [Learn more about providing service implementations **in Node.js**.](../node.js/core-services#implementing-services){.learn-more .impl .node}
 [Learn also **how to do that in Java** using Event Handler Classes.](../java/event-handlers/#handlerclasses){.learn-more .impl .java}
 
@@ -765,8 +768,8 @@ public class SubmitOrderHandler implements EventHandler {
 
 </span>
 
-[Find this source also in **capire/bookshop**.](https://github.com//capire/bookshop/tree/main/srv/cat-service.js){ .learn-more .impl .node target="_blank"}
-[Find this source also in **cap/samples**.](https://github.com/SAP-samples/cloud-cap-samples-java/blob/main/srv/src/main/java/my/bookshop/handlers/CatalogServiceHandler.java#L166){ .impl .java .learn-more target="_blank"}
+[Find this source also in the GitHub repo.](https://github.com/capire/bookshop/tree/main/srv/cat-service.js){ .learn-more .impl .node target="_blank"}
+[Find this source also in the GitHub repo.](https://github.com/sap-samples/cloud-cap-samples-java/blob/main/srv/src/main/java/my/bookshop/handlers/CatalogServiceHandler.java#L166){ .impl .java .learn-more target="_blank"}
 [Learn more about **connecting to services** using `cds.connect`.](../node.js/cds-connect){ .learn-more .impl .node}
 [Learn more about **connecting to services** using `@Autowired`, `com.sap.cds.ql`, etc.](../java/services){.learn-more .impl .java}
 [Learn more about **reading and writing data** using `cds.ql`.](../node.js/cds-ql){ .learn-more .impl .node}

java/cds-data.md

@@ -473,24 +473,7 @@ The name of the CDS element referred to by a getter or setter, is defined throug
 
 ### Generated Accessor Interfaces {#generated-accessor-interfaces}
 
-For all structured types of the CDS model, accessor interfaces can be generated using the [CDS Maven Plugin](./cqn-services/persistence-services#staticmodel). The generated accessor interfaces allow for hybrid access and easy serialization to JSON.
-
-By default, the accessor interfaces provide the setter and getter methods inspired by the JavaBeans specification.
-
-Following example uses accessor interfaces that have been generated with the default (JavaBeans) style:
-
-```java
-    Authors author = Authors.create();
-    author.setName("Emily Brontë");
-
-    Books book = Books.create();
-    book.setAuthor(author);
-    book.setTitle("Wuthering Heights");
-```
-
-Alternatively, you can generate accessor interfaces in _fluent style_. In this mode, the getter methods are named after the property names. To enable fluent chaining, the setter methods return the accessor interface itself.
-
-Following is an example of the fluent style:
+For all structured types of the CDS model, accessor interfaces can be generated using the [CDS Maven Plugin](/java/assets/cds-maven-plugin-site/plugin-info.html). The generated accessor interfaces allow for hybrid access and easy serialization to JSON. Code generation is executed by default at build time and is configurable.
 
 ```java
    Authors author = Authors.create().name("Emily Brontë");
@@ -505,6 +488,8 @@ The way the interfaces are generated determines only how data is accessed by cus
 
 Moreover, it doesn't change the way how event contexts and entities, delivered by CAP, look like. Such interfaces from CAP are always modelled in the default JavaBeans style.
 
+See more in [Configuring Code Generation for Typed Access](/java/developing-applications/building#codegen-config) for advanced options. {.learn-more}
+
 #### Renaming Elements in Java
 
 Element names used in the CDS model might conflict with reserved [Java keywords](https://docs.oracle.com/javase/specs/jls/se13/html/jls-3.html#jls-3.9) (`class`, `private`, `transient`, etc.). In this case, the `@cds.java.name` annotation must be used to specify an alternative property name that will be used for the generation of accessor interfaces and [static model](./cqn-services/persistence-services#staticmodel) interfaces. The element name used as key in the underlying map for [dynamic access](#entities-and-structured-types) isn't affected by this annotation.

java/developing-applications/building.md

@@ -376,7 +376,148 @@ Use the _.cdsrc.json_ file to add project specific configuration of `@sap/cds-dk
 [Learn more about configuration and `cds.env`](../../node.js/cds-env){.learn-more}
 
 
-### Using a Local cds-dk
+## Code Generation for Typed Access {#codegen-config}
+
+The [interfaces for typed access](../cds-data#generated-accessor-interfaces) are generated at each build
+by the [`cds:generate`](/java/assets/cds-maven-plugin-site/generate-mojo.html) goal of the [CDS Maven Plugin](/java/assets/cds-maven-plugin-site/plugin-info.html).
+
+You configure this goal just like any other Maven plugin via its configuration options via your application's POM. For example:
+
+```xml [pom.xml]
+<execution>
+    <id>cds.generate</id>
+    <goals>
+        <goal>generate</goal>
+    </goals>
+    <configuration>
+        <basePackage>cds.gen</basePackage>
+        ...
+    </configuration>
+</execution>
+```
+
+Each time your application is built, these interfaces are regenerated. By default, they are excluded from your version control. 
+
+### Package for Generated Code
+
+The option [`basePackage`](/java/assets/cds-maven-plugin-site/generate-mojo.html#basePackage) can be used to specify a base package prefix for generated code. The suffix package structure will reflect namespaces defined in your CDS model.
+
+### Filter for CDS Entities
+
+By default, the complete model of your application is generated including all imported or re-used models.
+You can use options [`includes`](/java/assets/cds-maven-plugin-site/generate-mojo.html#includes) and [`excludes`](/java/assets/cds-maven-plugin-site/generate-mojo.html#excludes) to specify the part of your overall model that is subject to code generation. Both inclusion and exclusion can be used together, inclusion is evaluated first, then exclusion filters out of the included set of entities.
+
+These options use patterns that are applied on the fully qualified names of the entities in CDS models. For example, the pattern `my.bookshop.*` will cover all definitions with namespace `my.bookshop` and the pattern `my.bookshop.**` will cover all definitions with fully qualified name starting with `my.bookshop`.
+
+:::warning Cross-namespace references are not resolved
+Options `includes` and `excludes` are simple filters. If included parts of your model reference types from the excluded area, the resulting code will not compile.
+:::
+
+### Style of Interfaces
+
+By default, the accessor interfaces provide the setter and getter methods inspired by the JavaBeans specification. In this style, getter and setter method names are prefixed with `get` and `set`:
+
+
+```java
+    Authors author = Authors.create();
+    author.setName("Emily Brontë");
+
+    Books book = Books.create();
+    book.setAuthor(author);
+    book.setTitle("Wuthering Heights");
+```
+
+Alternatively, you can generate accessor interfaces in _fluent style_. In this mode, the getter methods are named after the property names. To enable fluent chaining, the setter methods return the accessor interface itself:
+
+
+```java
+   Authors author = Authors.create().name("Emily Brontë");
+   Books.create().author(author).title("Wuthering Heights");
+```
+
+The generation mode is configured by the option [`methodStyle`](/java/assets/cds-maven-plugin-site/generate-mojo.html#methodStyle). The selected style affects all entities and event contexts in your services. The default value is `BEAN`, which represents JavaBeans-style interfaces.
+
+Once, when starting a project, decide on the style of the interfaces that is best for your team and project.
+
+The way the interfaces are generated only determines how data is accessed by custom code. It does not affect how the data is represented in memory and handled by the CAP Java runtime.
+
+Moreover, it doesn't change the way how event contexts, delivered by CAP, look like. Such interfaces from CAP are always modelled in the default JavaBeans style.
+
+### Code Generation Features
+
+Other options in this goal enable or disable certain features that change the way generated code looks in a certain aspect. These changes can be incompatible with the existing code and require manual adaptation.
+
+- [`strictSetters`](/java/assets/cds-maven-plugin-site/generate-mojo.html#strictSetters)
+
+  This switch changes the signature of the setter methods in typed access interfaces so that they require concrete type instead of generic `Map` interface.
+  For example:
+
+  ```java
+  void setManager(Map<String, ?> manager); // [!code --]
+  void setManager(Manager manager); // [!code ++]
+  ```
+
+  It does not introduce any additional type checks at runtime, the correctness of the assignment is checked only at the time of compilation.
+
+- [`interfacesForAspects`](/java/assets/cds-maven-plugin-site/generate-mojo.html#interfacesForAspects)
+
+  If your entity is modelled with the [composition of aspects](/cds/cdl#with-named-targets), the generated interfaces always reference original aspect as type for setters and getters.
+  When this switch is enabled, the code generator uses the type generated by the compiler instead of the type of the aspect itself and will include methods to fetch keys, for example.
+
+  :::warning Limitations
+  This is supported only for the named aspects (inline targets are not supported) and does not respect all possible options how such entities might be exposed by services.
+  :::
+
+- [`betterNames`](/java/assets/cds-maven-plugin-site/generate-mojo.html#betterNames)
+
+  CDS models from external sources might include elements that have some special characters in their names or include elements that clash with Java keywords. Such cases always can be solved with the [renaming features](/java/cds-data#renaming-elements-in-java) provided by code generator, but in case of large models, this is tedious.
+  When this switch is enabled, characters `/` and `$` behave as a separators for the name during case conversions, similar to `_` and `.`. For example, `GET_MATERIAL` yields `GetMaterial` (or `getMaterial` for attributes and methods). The same now applies for the names with `/`, for example, name `/DMO/GET_MATERIAL` will be converted to `DmoGetMaterial`.
+  
+  The following conversions are applied:  
+    - Names from CDS model that are Java keywords are suffixed with `_`.
+    - Names from CDS model that use characters that are not valid as Java identifiers, are replaced by `_`. This, however, might lead to a conflicts between names that yield the same name in Java.
+    - Leading `_` will remain in the name after conversions. This supports conventions where an association and its foreign key have names like `_assoc` and `assoc`.
+  These conversions no longer influence the splitting.
+
+- [`cqnServiceGetters`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnServiceGetters)
+
+  The method `getService()` in generated [event-specific Event Context interfaces](../event-handlers/#eventcontext) is overridden to return the typed service interface instead of the generic `Service` type.
+
+:::warning Check migration guides!
+In major releases of CAP Java, some of these switches can be made the new default and some other switches might be removed. This might introduce compile errors
+in your application that needs to be fixed.
+:::
+
+See [Maven Plugin Documentation](/java/assets/cds-maven-plugin-site/generate-mojo.html) for actual status of deprecation and switches that are not described here. {.learn-more}
+
+### Annotation Detail Level
+
+The option [`annotationDetailLevel`](/java/assets/cds-maven-plugin-site/generate-mojo.html#annotationDetailLevel) lets you choose the amount of the details for the Java annotation [`@Generated`](https://docs.oracle.com/en/java/javase/21/docs/api/java.compiler/javax/annotation/processing/Generated.html) added to each interface. This annotation has no effect at runtime but is evaluated by static code analysis tools to identify the artifacts as generated.
+
+Following levels of the details are available:
+- `MINIMAL` (default) - only the annotation is added, no additional information is added.
+
+   ```java
+    @CdsName("service.Entity")
+    @Generated("cds-maven-plugin")
+    public interface Entity extends CdsData {  }
+   ```
+
+- `FULL` - annotation contains the timestamp of the generation.
+
+  ```java
+  @CdsName("service.Entity")
+  @Generated(
+      value = "cds-maven-plugin",
+      date = "9999-12-31T23:59:59.999999Z",
+      comments = ""
+  )
+  public interface Entity extends CdsData {  }
+  ```
+
+- `NONE` - no `@Generated` annotation is added. This is not recommended.
+
+## Using a Local cds-dk
 
 Starting with version 3.6.0 of the `cds-services-archetype`, the default setup of a newly created CAP Java project has changed. The `@sap/cds-dk` is maintained as a `devDependency` in `package.json` and installed with an `npm ci` during the Maven build.
 The `install-cdsdk` goal is no longer used to install the `@sap/cds-dk` locally and it's also marked as deprecated. The version of the `@sap/cds-dk` is no longer maintained in _pom.xml_, it's configured in the _package.json_: