Skip to content

Commit 0c5a3df

Browse files
beckermarcagoerlerrenejeglinsky
authored
Adjust docs for @cds.java.name (#1274)
Co-authored-by: Adrian Görler <[email protected]> Co-authored-by: Rene Jeglinsky <[email protected]>
1 parent 512796e commit 0c5a3df

File tree

2 files changed

+88
-17
lines changed

2 files changed

+88
-17
lines changed

java/cds-data.md

+87-16
Original file line numberDiff line numberDiff line change
@@ -512,48 +512,119 @@ See the following example:
512512
entity Equity {
513513
@cds.java.name : 'clazz'
514514
class : String;
515-
...
516515
}
517516
```
518517

519518
```java
520519
interface Equity {
520+
521+
@CdsName("class")
521522
String getClazz();
522523

524+
@CdsName("class")
523525
void setClazz(String clazz);
524-
...
526+
525527
}
526528
```
527529

528530
#### Renaming Types in Java
529531

530-
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.
532+
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.
533+
The annotation `@cds.java.this.name` - in contrast to `@cds.java.name` - is not propagated, along projections, includes or from types to elements.
531534

532-
See the following example:
535+
::: warning Unexpected effects of `@cds.java.name` on entities and types
536+
The annotation propagation behaviour applied to `@cds.java.name` can have unexpected side effects when used to rename entities or types,
537+
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,
538+
where the base entity and the projected entity should be renamed in the same way.
539+
:::
540+
541+
See the following example, renaming an entity:
533542

534543
```cds
535-
@cds.java.this.name: 'MyJavaClass'
536-
entity Class {
537-
key ID: String;
544+
@cds.java.this.name: 'Book'
545+
entity Books {
546+
// ...
538547
}
539548
```
540549

541550
```java
542-
@CdsName("javaNames.Class")
543-
public interface MyJavaClass extends CdsData {
544-
String ID = "ID";
551+
@CdsName("Books")
552+
public interface Book extends CdsData {
553+
// ...
554+
}
555+
```
545556

546-
@CdsName(ID)
547-
String id();
557+
Here is another example, renaming a type:
548558

549-
@CdsName(ID)
550-
MyJavaClass id(String id);
559+
```cds
560+
@cds.java.this.name: 'MyName'
561+
type Name {
562+
firstName: String;
563+
lastName: String;
564+
}
565+
566+
entity Person {
567+
publicName: Name;
568+
secretName: Name;
569+
}
570+
```
571+
572+
```java
573+
@CdsName("Name")
574+
public interface MyName extends CdsData {
575+
// ...
576+
}
551577

552-
// rest of the interface
578+
@CdsName("Person")
579+
public interface Person extends CdsData {
580+
String PUBLIC_NAME = "publicName";
581+
String SECRET_NAME = "secretName";
582+
583+
MyName getPublicName();
584+
void setPublicName(MyName publicName);
585+
586+
MyName getSecretName();
587+
void setSecretName(MyName secretName);
588+
}
589+
```
590+
591+
::: details See how the previous example would turn out with `@cds.java.name`
592+
593+
```cds
594+
@cds.java.name: 'MyName'
595+
type Name {
596+
firstName: String;
597+
lastName: String;
598+
}
599+
600+
entity Person {
601+
publicName: Name;
602+
secretName: Name;
553603
}
554604
```
555605

556-
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.
606+
```java
607+
@CdsName("Name")
608+
public interface MyName extends CdsData {
609+
// ...
610+
}
611+
612+
@CdsName("Person")
613+
public interface Person extends CdsData {
614+
String MY_NAME = "publicName";
615+
String MY_NAME = "secretName";
616+
617+
MyName getMyName();
618+
void setMyName(MyName myName);
619+
620+
MyName getMyName();
621+
void setMyName(MyName myName);
622+
}
623+
```
624+
625+
Note, that the propagated annotation `@cds.java.name` creates attribute and method conflicts in `Person`.
626+
627+
:::
557628

558629
::: warning
559630
This feature requires version 8.2.0 of the [CDS Command Line Interface](/tools/cds-cli).

java/cqn-services/persistence-services.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -579,7 +579,7 @@ See [Class JdbcTemplate](https://docs.spring.io/spring-framework/docs/current/ja
579579
The static model and accessor interfaces can be generated using the [CDS Maven Plugin](../developing-applications/building#cds-maven-plugin).
580580

581581
::: warning _❗ Warning_
582-
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).
582+
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).
583583
:::
584584

585585
#### Static Model in the Query Builder

0 commit comments

Comments
 (0)