[Java] Document references by vmikhailenko · Pull Request #2153 · capire/docs

vmikhailenko · 2025-10-15T14:57:48Z

The application developers are now exposed to the concept of references via arguments of custom handlers.

They should now what these are and how you supposed to work with them.

We can also improve the APIs a bit as some of these look rather ugly.

renejeglinsky · 2025-11-05T11:04:49Z

Hi @vmikhailenko ,
I enabled an AI editing workflow and would like to collect your feedback on the current suggestions. Please go through the suggestions and apply the ones you deem helpful. Afterwards please send me a little feedback/summary of what you think it does good and what you didn't like. Thank you :)

Co-authored-by: René Jeglinsky <rene.jeglinsky@sap.com>

… into java-document-refs

renejeglinsky

I guess it's ok to simplify the links like that. Or have you had a certain reason not to do it?

renejeglinsky · 2025-11-12T12:27:46Z

+
+The method `asRef()` seals the reference and makes it immutable.
+
+Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.


Suggested change

Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.

Relative references do not specify the type in the first segment and are [element references](#element-refs) most of the time.

renejeglinsky · 2025-11-12T12:28:08Z

+
+Relative references do not specify the type in the first segment and are [element references](/java/working-with-cql/query-api#element-refs) most of the time.
+
+New references are constructed with [model interfaces](../cqn-services/persistence-services#model-interfaces) or via API that is also used to build [CQL statements](/java/working-with-cql/query-api#concepts). Prefer model interfaces in the application code.


Suggested change

New references are constructed with [model interfaces](../cqn-services/persistence-services#model-interfaces) or via API that is also used to build [CQL statements](/java/working-with-cql/query-api#concepts). Prefer model interfaces in the application code.

New references are constructed with [model interfaces](../cqn-services/persistence-services#model-interfaces) or via API that is also used to build [CQL statements](#concepts). Prefer model interfaces in the application code.

renejeglinsky · 2025-11-12T12:32:54Z

+CqnElementRef relativeRef = statement.items().getFirst().asRef(); // author/placeOfBirth
+```
+
+Element references can be extended with the same APIs as the entity references.


Suggested change

Element references can be extended with the same APIs as the entity references.

Element references can be extended with the same APIs as the [entity references](#entity-refs).

vmikhailenko · 2025-11-12T12:50:04Z

Go ahead. I am also OK with textual changes.

agoerler · 2025-10-15T16:08:40Z

+
+You can also get [entity references](query-execution#entity-refs) from the result of a CDS QL statement to address an entity via its key values in other statements.
+
+Each reference has ordered sequence of _segments_ that define the path from the entity's root to the certain part of it. Segment has the _identifier_ with the name of the entity or an element and optional filter _predicate_.


Suggested change

Each reference has ordered sequence of _segments_ that define the path from the entity's root to the certain part of it. Segment has the _identifier_ with the name of the entity or an element and optional filter _predicate_.

Each reference has ordered sequence of _segments_ that defines the path from the entity's root to the certain part of it. Segment has the _identifier_ with the name of the entity or an element and optional filter _predicate_.

agoerler · 2025-10-15T16:09:06Z

+
+Each reference has ordered sequence of _segments_ that define the path from the entity's root to the certain part of it. Segment has the _identifier_ with the name of the entity or an element and optional filter _predicate_.
+
+Existing reference can be reused as an object or a variable, or a new reference can be built on top of it. References are not bound to the particular model and are not checked against it while they are being built.


Suggested change

Existing reference can be reused as an object or a variable, or a new reference can be built on top of it. References are not bound to the particular model and are not checked against it while they are being built.

An existing reference can be reused as an object or a variable, or a new reference can be built on top of it. References are not bound to the particular model and are not checked against it while they are being built.

agoerler · 2025-10-15T16:09:41Z

+
+Existing reference can be reused as an object or a variable, or a new reference can be built on top of it. References are not bound to the particular model and are not checked against it while they are being built.
+
+References can be _absolute_ or _relative_. Absolute reference has fully qualified entity name as the identifier in the first segment. They usually have associations as their segments.


Suggested change

References can be _absolute_ or _relative_. Absolute reference has fully qualified entity name as the identifier in the first segment. They usually have associations as their segments.

References can be _absolute_ or _relative_. An absolute reference has a fully qualified entity name as the identifier in the first segment. They usually have associations as their segments.

agoerler · 2025-10-15T16:09:57Z

+
+References can be _absolute_ or _relative_. Absolute reference has fully qualified entity name as the identifier in the first segment. They usually have associations as their segments.
+
+You start with the reference pointing to a book with certain key. You build it using corresponding [model interfaces](../cqn-services/persistence-services#model-interfaces) providing you the methods that corresponds to the elements of the book.


Suggested change

You start with the reference pointing to a book with certain key. You build it using corresponding [model interfaces](../cqn-services/persistence-services#model-interfaces) providing you the methods that corresponds to the elements of the book.

You start with the reference pointing to a book with a certain key. You build it using corresponding [model interfaces](../cqn-services/persistence-services#model-interfaces) providing you the methods that corresponds to the elements of the book.

agoerler · 2025-10-15T16:11:15Z

+    refToAuthor.segments().subList(0, refToAuthor.segments().size() - 1)).asRef(); // Books(ID=...)
+```
+
+You can also construct ref that starts from the first segment to navigate to different path of the same root.


Suggested change

You can also construct ref that starts from the first segment to navigate to different path of the same root.

You can also construct a ref that starts from the first segment to navigate to different path of the same root.

vmikhailenko · 2025-12-05T09:39:29Z

Do we need this?

renejeglinsky · 2026-05-28T11:47:48Z

Should we finish this or is this obsolete meanwhile?

Draft

e0c19c6

vmikhailenko requested a review from smahati as a code owner October 15, 2025 14:57

vmikhailenko requested review from MattSchur and agoerler October 15, 2025 14:57

vmikhailenko commented Oct 15, 2025

View reviewed changes

Comment thread java/working-with-cql/query-api.md Outdated

Different structure

3cfdad1

vmikhailenko commented Oct 16, 2025

View reviewed changes

Comment thread java/working-with-cql/query-api.md Outdated

Update java/working-with-cql/query-api.md

36fbf31

renejeglinsky added the AI Review AI generated suggestions label Nov 5, 2025

Merge branch 'main' into java-document-refs

801631e