Dedicated chapter about code generation configuration

java/cds-data.md

@@ -469,37 +469,9 @@ 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.
+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.
 
-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:
-
-```java
-   Authors author = Authors.create().name("Emily Brontë");
-   Books.create().author(author).title("Wuthering Heights");
-```
-
-The generation mode is configured by the property [`<methodStyle>`](./assets/cds-maven-plugin-site/generate-mojo.html#methodstyle) of the goal `cds:generate` provided by the CDS Maven Plugin. The selected `<methodStyle>` 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. We recommend the default JavaBeans style.
-
-The way the interfaces are generated determines only 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 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/configuring#codegen-config) for advanced options. {.learn-more}
 
 #### Renaming Elements in Java
 

java/developing-applications/configuring.md

@@ -63,3 +63,143 @@ properties:
 :::warning SAP Business Application Studio
 If you develop your application in SAP Business Application Studio and Java 21 is not available there, use the Java 17, instead.
 :::
+
+## Configuring Code Generation for Typed Access {#codegen-config}
+
+The [interfaces for typed access](../cds-data#generated-accessor-interfaces) are generated at each build 
+by the [goal `cds:generate`](/java/assets/cds-maven-plugin-site/generate-mojo.html) of the [CDS Maven Plugin](/java/assets/cds-maven-plugin-site/plugin-info.html). 
+Each time your application is built, these interfaces are regenerated so you should exclude them from your version control system.
+
+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>
+```
+
+### Package for Generated Code
+
+The option [`basePackage`](/java/assets/cds-maven-plugin-site/generate-mojo.html#basePackage) can be used to specify package as the root for generated code. The underlying package structure will reflect namespaces defined in your CDS model.
+
+### Filter for CDS Entities
+
+By default, 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 evaluated first, then exclusion filter out 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.
+
+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:
+
+```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. We recommend the default JavaBeans style.
+
+The way the interfaces are generated determines only 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, instead of the following:
+
+  ```java
+  void setManager(Map<String, ?> manager);
+  ```  
+  you get the following: 
+
+  ```java
+  void setManager(Manager manager);
+  ```
+  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, code generator will use type generated by the compiler instead of 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 [renaming features](/java/cds-data#renaming-elements-in-java) provided by code generator, but in case of large models, this is tedious.
+  This switch enables following conversions on the names coming from CDS models to reduce the amount of renaming that needs to be done:
+
+  - 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.
+  - Characters `/` and `$` behave as a separator 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`.  
+  - Leading `_` will remain in the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`.
+
+:::warning Check migration guides!
+In major releases of CAP Java, some of these switches can be made 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
+
+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.
+
+Following levels of the details are available:
+- `MINIMAL` - only annotation is added, no additional information is added.
+
+   ```java
+    @CdsName("service.Entity")
+    @Generated("cds-maven-plugin")
+    public interface Entity extends CdsData {  }
+   ```
+
+- `FULL` - annotation contains date and time 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` - annotation is not added at all. This is not recommended.