Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adjust docs for @cds.java.name #1274

Merged
merged 7 commits into from
Oct 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 87 additions & 16 deletions java/cds-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion java/cqn-services/persistence-services.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down