From 96f0cfe0b4d457fff03e8b67fae747bf2d3efa95 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Thu, 15 May 2025 12:38:38 +0200 Subject: [PATCH 01/12] First draft --- java/cds-data.md | 32 +---- java/developing-applications/configuring.md | 140 ++++++++++++++++++++ 2 files changed, 142 insertions(+), 30 deletions(-) diff --git a/java/cds-data.md b/java/cds-data.md index e24f4fa9e..1cd16fb61 100644 --- a/java/cds-data.md +++ b/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 [``](./assets/cds-maven-plugin-site/generate-mojo.html#methodstyle) of the goal `cds:generate` provided by the CDS Maven Plugin. The selected `` 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 diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index 352434e5f..d00a20b0c 100644 --- a/java/developing-applications/configuring.md +++ b/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 [generated interfaces for typed access](../cds-data#generated-accessor-interfaces) are generated by CAP 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] + + cds.generate + + generate + + + cds.gen + ... + + +``` + +### 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) or [`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. + +For example, the pattern `my.bookshop.*` will exclude all definitions with namespace `my.bookshop` and the pattern `my.bookshop.**` will exclude 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 other 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 and entities, 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 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 prefixed 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 same name in Java. + - Characters `/` and `$` behave just like `_`: they used to provide camel-cased name and provide better support for models coming from ABAP systems. + - If the name of the element is prefixed by `_`, this character will remain 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. \ No newline at end of file From d736bf83d6ab15a9df46782a65dc4becb6b1ccbb Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Thu, 15 May 2025 15:42:48 +0200 Subject: [PATCH 02/12] Add two switches --- java/developing-applications/configuring.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index d00a20b0c..cd56f9b48 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -170,6 +170,14 @@ Other options in this goal enable or disable certain features that change the wa - Characters `/` and `$` behave just like `_`: they used to provide camel-cased name and provide better support for models coming from ABAP systems. - If the name of the element is prefixed by `_`, this character will remain the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`. +- [`cqnService`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnService) + + This switch enables generation of [typed service interfaces](/java/cqn-services/application-services#trigger-action-or-function). This switch is deprecated and should not be disabled. + +- [`eventContext`](/java/assets/cds-maven-plugin-site/generate-mojo.html#eventContext) + + This switch enables generation of interfaces representing contexts for actions, functions and events that are modelled through CDS. This switch is deprecated and should not be disabled. + :::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. From c7cb8a5a663041a21ddfeeda7be2ecdb1e2278fc Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Fri, 16 May 2025 16:25:52 +0200 Subject: [PATCH 03/12] Feedback --- java/developing-applications/configuring.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index cd56f9b48..66aa2130e 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -92,12 +92,12 @@ The option [`basePackage`](/java/assets/cds-maven-plugin-site/generate-mojo.html ### 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) or [`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. +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. -For example, the pattern `my.bookshop.*` will exclude all definitions with namespace `my.bookshop` and the pattern `my.bookshop.**` will exclude all definitions with fully qualified name starting with `my.bookshop`. +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 other parts of your model reference types from the excluded area, the resulting code will not compile. +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 @@ -165,9 +165,9 @@ Other options in this goal enable or disable certain features that change the wa 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 prefixed 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 same name in Java. - - Characters `/` and `$` behave just like `_`: they used to provide camel-cased name and provide better support for models coming from ABAP systems. + - 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 separator for name, just like `_` does. `_` used to convert name of CDS entity to camel case or screaming case (for constants). - If the name of the element is prefixed by `_`, this character will remain the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`. - [`cqnService`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnService) From 28a33a9819c3e77e5c39fb337380103d5ade88ee Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Fri, 16 May 2025 16:27:12 +0200 Subject: [PATCH 04/12] Feedback --- java/developing-applications/configuring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index 66aa2130e..203fd8a2e 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -167,7 +167,7 @@ Other options in this goal enable or disable certain features that change the wa - 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 separator for name, just like `_` does. `_` used to convert name of CDS entity to camel case or screaming case (for constants). + - Characters `/` and `$` behave as separator for name during case conversions, just like `_` does. - If the name of the element is prefixed by `_`, this character will remain the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`. - [`cqnService`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnService) From 83d4d870b12cd540398c4eefcbe36e2c077b5555 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Fri, 16 May 2025 16:34:57 +0200 Subject: [PATCH 05/12] Feedback --- java/developing-applications/configuring.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index 203fd8a2e..dde7b0d35 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -130,7 +130,7 @@ Once, when starting a project, decide on the style of the interfaces that is bes 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. +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 @@ -168,7 +168,7 @@ Other options in this goal enable or disable certain features that change the wa - 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 separator for name during case conversions, just like `_` does. - - If the name of the element is prefixed by `_`, this character will remain the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`. + - Leading `_` will remain in the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`. - [`cqnService`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnService) From 99fd58dfee4601c31127d2146575f698f30370c4 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Fri, 16 May 2025 16:44:22 +0200 Subject: [PATCH 06/12] Update --- java/developing-applications/configuring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index dde7b0d35..ecdbd3583 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -167,7 +167,7 @@ Other options in this goal enable or disable certain features that change the wa - 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 separator for name during case conversions, just like `_` does. + - Characters `/` and `$` behave as a separator for the name during case conversions, similar to `_` and `.`. - Leading `_` will remain in the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`. - [`cqnService`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnService) From ec69759bf8bd2d3afa938fde2fbc485e9942ce85 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Fri, 16 May 2025 16:48:58 +0200 Subject: [PATCH 07/12] Update --- java/developing-applications/configuring.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index ecdbd3583..877ce4b0b 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -172,11 +172,11 @@ Other options in this goal enable or disable certain features that change the wa - [`cqnService`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnService) - This switch enables generation of [typed service interfaces](/java/cqn-services/application-services#trigger-action-or-function). This switch is deprecated and should not be disabled. + This switch enables generation of [typed service interfaces](/java/cqn-services/application-services#trigger-action-or-function). This switch is deprecated and should not be used. - [`eventContext`](/java/assets/cds-maven-plugin-site/generate-mojo.html#eventContext) - This switch enables generation of interfaces representing contexts for actions, functions and events that are modelled through CDS. This switch is deprecated and should not be disabled. + This switch enables generation of interfaces representing contexts for actions, functions and events that are modelled through CDS. This switch is deprecated and should not be used. :::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 From beecdc036eddfc8559a8affd27aaa2f96a9635d1 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Fri, 16 May 2025 17:46:20 +0200 Subject: [PATCH 08/12] Update --- java/developing-applications/configuring.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index 877ce4b0b..a59488a9f 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -170,14 +170,6 @@ Other options in this goal enable or disable certain features that change the wa - Characters `/` and `$` behave as a separator for the name during case conversions, similar to `_` and `.`. - Leading `_` will remain in the name after conversions. This supports convention where association and its foreign key have names like `_assoc` and `assoc`. -- [`cqnService`](/java/assets/cds-maven-plugin-site/generate-mojo.html#cqnService) - - This switch enables generation of [typed service interfaces](/java/cqn-services/application-services#trigger-action-or-function). This switch is deprecated and should not be used. - -- [`eventContext`](/java/assets/cds-maven-plugin-site/generate-mojo.html#eventContext) - - This switch enables generation of interfaces representing contexts for actions, functions and events that are modelled through CDS. This switch is deprecated and should not be used. - :::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. From 1fd9a5f2bd3a05cf8bb88a4be511fc6c9af9ae98 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Mon, 19 May 2025 10:07:20 +0200 Subject: [PATCH 09/12] Add an example --- java/developing-applications/configuring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index a59488a9f..1557ebce4 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -167,7 +167,7 @@ Other options in this goal enable or disable certain features that change the wa - 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 `.`. + - 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! From c4c734b625a466cd2f767ff0d6c050d2183af611 Mon Sep 17 00:00:00 2001 From: Vladimir Date: Mon, 19 May 2025 15:42:07 +0200 Subject: [PATCH 10/12] Update java/developing-applications/configuring.md Co-authored-by: Marc Becker --- java/developing-applications/configuring.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index 1557ebce4..362e2f152 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -66,7 +66,7 @@ If you develop your application in SAP Business Application Studio and Java 21 i ## Configuring Code Generation for Typed Access {#codegen-config} -The [generated interfaces for typed access](../cds-data#generated-accessor-interfaces) are generated by CAP at each build +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. From d61ed744ab380a93a973d9d4fe5a5381b2cf05e5 Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Mon, 16 Jun 2025 11:06:06 +0200 Subject: [PATCH 11/12] Move the chapter --- java/developing-applications/building.md | 140 +++++++++++++++++++ java/developing-applications/configuring.md | 142 +------------------- 2 files changed, 141 insertions(+), 141 deletions(-) diff --git a/java/developing-applications/building.md b/java/developing-applications/building.md index 17115a7a0..d646512bc 100644 --- a/java/developing-applications/building.md +++ b/java/developing-applications/building.md @@ -378,6 +378,146 @@ 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} +## 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] + + cds.generate + + generate + + + cds.gen + ... + + +``` + +### 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 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. + ### 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. diff --git a/java/developing-applications/configuring.md b/java/developing-applications/configuring.md index 362e2f152..6ccb86c4f 100644 --- a/java/developing-applications/configuring.md +++ b/java/developing-applications/configuring.md @@ -62,144 +62,4 @@ 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] - - cds.generate - - generate - - - cds.gen - ... - - -``` - -### 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 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. \ No newline at end of file +::: \ No newline at end of file From 75e7b7cb0a8a4881b36d6909b4e3cb58a3e1530e Mon Sep 17 00:00:00 2001 From: Vladimir Mikhaylenko Date: Mon, 16 Jun 2025 16:43:20 +0200 Subject: [PATCH 12/12] Fix broken link --- java/cds-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/cds-data.md b/java/cds-data.md index 064be6c03..7a9ed6c0f 100644 --- a/java/cds-data.md +++ b/java/cds-data.md @@ -471,7 +471,7 @@ The name of the CDS element referred to by a getter or setter, is defined throug 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. -See more in [Configuring Code Generation for Typed Access](/java/developing-applications/configuring#codegen-config) for advanced options. {.learn-more} +See more in [Configuring Code Generation for Typed Access](/java/developing-applications/building#codegen-config) for advanced options. {.learn-more} #### Renaming Elements in Java