Adjust docs for @cds.java.name

java/cds-data.md

@@ -512,48 +512,119 @@ See the following example:
 entity Equity {
   @cds.java.name : 'clazz'
   class : String;
-  ...
 }
 ```
 
 ```java
 interface Equity {
+
+  @CdsName("class")
   String getClazz();
 
+  @CdsName("class")
   void setClazz(String clazz);
-	...
+
 }
 ```
 
 #### Renaming Types in Java
 
-You might also want to rename the type of the entity. For this you can use annotation `@cds.java.this.name` to specify alternative name for the  accessor interfaces and [static model](./cqn-services/persistence-services#staticmodel) interfaces. This annotation can be used only on definitions and is ignored everywhere else.
+For entities and types it is recommended to use `@cds.java.this.name` to specify an alternative name for the accessor interfaces and [static model](./cqn-services/persistence-services#staticmodel) interfaces.
+The annotation `@cds.java.this.name` - in contrast to `@cds.java.name` - is not propagated, along projections, includes or from types to elements.
 
-See the following example:
+::: warning Unexpected effects of `@cds.java.name` on entities and types
+The annotation propagation behaviour applied to `@cds.java.name` can have unexpected side effects when used to rename entities or types,
+as it is propagated along projections, includes or from structured types to (flattened) elements. Nevertheless it might be useful in simple 1:1-projection scenarios,
+where the base entity and the projected entity should be renamed in the same way.
+:::
+
+See the following example, renaming an entity:
 
 ```cds
-@cds.java.this.name: 'MyJavaClass'
-entity Class {
-  key ID: String;
+@cds.java.this.name: 'Book'
+entity Books {
+  // ...
 }
 ```
 
 ```java
-@CdsName("javaNames.Class")
-public interface MyJavaClass extends CdsData {
-  String ID = "ID";
+@CdsName("Books")
+public interface Book extends CdsData {
+  // ...
+}
+```
 
-  @CdsName(ID)
-  String id();
+Here is another example, renaming a type:
 
-  @CdsName(ID)
-  MyJavaClass id(String id);
+```cds
+@cds.java.this.name: 'MyName'
+type Name {
+  firstName: String;
+  lastName: String;
+}
+
+entity Person {
+  publicName: Name;
+  secretName: Name;
+}
+```
+
+```java
+@CdsName("Name")
+public interface MyName extends CdsData {
+  // ...
+}
 
-  // rest of the interface
+@CdsName("Person")
+public interface Person extends CdsData {
+  String PUBLIC_NAME = "publicName";
+  String SECRET_NAME = "secretName";
+
+  MyName getPublicName();
+  void setPublicName(MyName publicName);
+
+  MyName getSecretName();
+  void setSecretName(MyName secretName);
+}
+```
+
+::: details See how the previous example would turn out with `@cds.java.name`
+
+```cds
+@cds.java.name: 'MyName'
+type Name {
+  firstName: String;
+  lastName: String;
+}
+
+entity Person {
+  publicName: Name;
+  secretName: Name;
 }
 ```
 
-In contrast with the annotation `@cds.java.name`, the annotation `@cds.java.this.name` does not rename projections of the annotated entity. If you want to rename chain of entities, you must annotate each of them individually.
+```java
+@CdsName("Name")
+public interface MyName extends CdsData {
+  // ...
+}
+
+@CdsName("Person")
+public interface Person extends CdsData {
+  String MY_NAME = "publicName";
+  String MY_NAME = "secretName";
+
+  MyName getMyName();
+  void setMyName(MyName myName);
+
+  MyName getMyName();
+  void setMyName(MyName myName);
+}
+```
+
+Note, that the propagated annotation `@cds.java.name` creates attribute and method conflicts in `Person`.
+
+:::
 
 ::: warning
 This feature requires version 8.2.0 of the [CDS Command Line Interface](/tools/cds-cli).

java/cqn-services/persistence-services.md

@@ -581,7 +581,7 @@ See [Class JdbcTemplate](https://docs.spring.io/spring-framework/docs/current/ja
 The static model and accessor interfaces can be generated using the [CDS Maven Plugin](../developing-applications/building#cds-maven-plugin).
 
 ::: warning _❗ Warning_
-Currently, the generator doesn't support using reserved [Java keywords](https://docs.oracle.com/javase/specs/jls/se13/html/jls-3.html#jls-3.9) as identifiers in the CDS model. Conflicting element names can be renamed in Java using the [@cds.java.name](../cds-data#renaming-elements-in-java) annotation. For entities, you can use [@cds.java.this.name](../cds-data#renaming-types-in-java).
+Currently, the generator doesn't support using reserved [Java keywords](https://docs.oracle.com/javase/specs/jls/se13/html/jls-3.html#jls-3.9) as identifiers in the CDS model. Conflicting element names can be renamed in Java using the [@cds.java.name](../cds-data#renaming-elements-in-java) annotation. For entities it is recommended to use [@cds.java.this.name](../cds-data#renaming-types-in-java).
 :::
 
 #### Static Model in the Query Builder