Repository navigation
docs: document typed JavaScript definition results - #6609
Conversation
Add a Typed Results section to Calling JavaScript, and update the surrounding text to cover declaring JavaScriptResult<T> as a method return type alongside PendingJavaScriptResult. Documents vaadin/flow#26890 (`d0a07b236e5ee3ef6ff112c89bc75cc7ac57b29f`).
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6609.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from 89946d8 |
heruan
left a comment
There was a problem hiding this comment.
The rest matches JavaScriptResult on Flow main: the example, the Jackson conversion, the handling of a value that can't be converted, and the rules for the type argument. One sentence is wrong, see the inline comment.
|
|
||
| The type argument has to be known from the interface: either a concrete type, such as `JavaScriptResult<Integer>`, or a type variable of an interface the definition extends and binds to a concrete type -- `T` in `JavaScriptResult<T>` when the definition extends `ValueJs<Integer>`. A raw or wildcard [classname]`JavaScriptResult`, or a type variable the definition doesn't bind to a concrete type, is refused (see <<#declaring-javascript,Declaring JavaScript in Java>>). | ||
|
|
||
| [classname]`JavaScriptResult<JsonNode>` behaves like [classname]`PendingJavaScriptResult`: its handlers get the JSON as the browser sent it, and [methodname]`then()` can still be called with a [classname]`Class` or [classname]`TypeReference` to choose the Java type to convert to (see <<#deserializing-generic-types-with-typereference,Deserializing Generic Types with TypeReference>>). |
There was a problem hiding this comment.
The second half is not correct. then(Class, ...) and then(TypeReference, ...) are declared on PendingJavaScriptResult only. A method declared as JavaScriptResult<JsonNode> has just then(handler), then(handler, errorHandler) and toCompletableFuture().
Suggestion: keep the first half (the handlers get the JSON as the browser sent it) and say that a method must return PendingJavaScriptResult to choose the Java type at the call site.
There was a problem hiding this comment.
@heruan Fixed. The sentence now keeps only the first half: with JavaScriptResult<JsonNode> the handlers get the JSON as the browser sent it. It then says that to choose the Java type at the call site with then(Class, ...) or then(TypeReference, ...), the method must return PendingJavaScriptResult.
|
@totally-not-ai Address the review comments of this PR. |
vaadin-review-bot
left a comment
There was a problem hiding this comment.
Reviewed the changes — left 3 comments and collected 1 finding below that could not be attached to the diff.
| Finding | |
|---|---|
The browser page still says a declared method returns only PendingJavaScriptResult. |
|
| 💬 | The type-variable rule illustrates itself with a ValueJs interface the page never shows. |
| 📐 | The note now packs the whole type-argument rule into one 48-word sentence and repeats the new section. |
| 📐 | The new Typed Results heading has no since badge. |
PendingJavaScriptResult.
A method that declares a return value can use the returned [classname]
PendingJavaScriptResultthe same way [methodname]executeJs(String, Object...)does.
Page.executeJs(Class) goes through the same JsDefinitionProxy.create as Element.executeJs(Class) (flow-server/src/main/java/com/vaadin/flow/component/page/Page.java:550), so a page definition can return JavaScriptResult<T> as well. After this PR the two pages disagree on what a declared method may return.
Suggestion: "A method that declares a return value answers with a [classname]PendingJavaScriptResult, or with a [classname]JavaScriptResult with a type argument, the same way a declaration on an element does."
browser-access.adoc:116 · accuracy
|
|
||
| The value is converted with Jackson, so any type Jackson can deserialize works, including beans and generic types such as `List<Person>`. A value that can't be converted to the declared type goes to the error handler passed to [methodname]`then()`, and fails a future obtained from [methodname]`toCompletableFuture()`; without an error handler, it's logged as a warning. | ||
|
|
||
| The type argument has to be known from the interface: either a concrete type, such as `JavaScriptResult<Integer>`, or a type variable of an interface the definition extends and binds to a concrete type -- `T` in `JavaScriptResult<T>` when the definition extends `ValueJs<Integer>`. A raw or wildcard [classname]`JavaScriptResult`, or a type variable the definition doesn't bind to a concrete type, is refused (see <<#declaring-javascript,Declaring JavaScript in Java>>). |
There was a problem hiding this comment.
💬 The type-variable rule illustrates itself with a ValueJs interface the page never shows.
TinJavaScriptResult<T>when the definition extendsValueJs<Integer>
ValueJs appears nowhere else on the page, so the reader has to invent the interface (something like interface ValueJs<T> { @JsExpression("…") JavaScriptResult<T> readValue(); }) before the sentence means anything. The sentence is also ~45 words with the example folded into it.
Either show the two interfaces as a short code block, or drop the named example and say: "a type variable that an interface the definition extends binds to a concrete type."
calling-javascript.adoc:180 · clarity
There was a problem hiding this comment.
Dropped the ValueJs example and split the rule into short sentences: the type argument is either a concrete type such as JavaScriptResult<Integer>, or a type variable that an interface the definition extends binds to a concrete type. Raw, wildcard, and unbound type arguments are refused, because nothing says what to convert the value to.
|
|
||
| [NOTE] | ||
| The interface is checked when [methodname]`executeJs(Class)` hands out the implementation. It must be annotated with [annotationname]`@JsDefinition`, and every method must be annotated with [annotationname]`@JsExpression` and return `void` or [classname]`PendingJavaScriptResult`. A `default` or `static` method is refused, since it's implemented in Java rather than declaring JavaScript to run in the browser. | ||
| The interface is checked when [methodname]`executeJs(Class)` hands out the implementation. It must be annotated with [annotationname]`@JsDefinition`, and every method must be annotated with [annotationname]`@JsExpression` and return `void`, [classname]`PendingJavaScriptResult`, or [classname]`JavaScriptResult` with a type argument that's known from the interface -- either a concrete type, or a type variable that an interface the definition extends binds to a concrete type. A raw or wildcard [classname]`JavaScriptResult`, or one whose type argument is a type variable the interface doesn't bind to a concrete type, is refused, since nothing says what to convert the value to. A `default` or `static` method is refused, since it's implemented in Java rather than declaring JavaScript to run in the browser. |
There was a problem hiding this comment.
📐 The note now packs the whole type-argument rule into one 48-word sentence and repeats the new section.
The note's first sentence runs to about 48 words, and the two sentences together restate the rule that the new Typed Results section gives in full at line 180 — which then links back here for it.
CONVENTIONS.md: "When a sentence that you add or change is too long, split it. Give an aside or an example its own sentence. When a list of three or more items makes the sentence long, turn it into a bulleted list."
Keeping the note to the return types and pointing forward would fix both: "… and return void, [classname]PendingJavaScriptResult, or [classname]JavaScriptResult with a type argument that's known from the interface (see <<#typed-results,Typed Results>>)."
calling-javascript.adoc:105 · conventions
There was a problem hiding this comment.
The note now just lists the allowed return types (void, PendingJavaScriptResult, or JavaScriptResult with a type argument known from the interface) and links forward to Typed Results. The full type-argument rules now appear only in that section, which no longer links back to the note.
|
|
||
|
|
||
| [[typed-results]] | ||
| === Typed Results |
There was a problem hiding this comment.
📐 The new Typed Results heading has no since badge.
JavaScriptResult is @since 25.4 (flow-server/src/main/java/com/vaadin/flow/component/page/JavaScriptResult.java:73), but the new subsection sits under == Return Values, which carries no badge and also covers the older executeJs(String, …) API.
CONVENTIONS.md: "Mark new features with a since badge instead: the [role="since:com.vaadin:vaadin@V25.2"] attribute above a section heading".
Add [role="since:com.vaadin:vaadin@V25.4"] above === Typed Results.
calling-javascript.adoc:151 · conventions
There was a problem hiding this comment.
Added [role="since:com.vaadin:vaadin@V25.4"] above === Typed Results.
|
Also updated |
heruan
left a comment
There was a problem hiding this comment.
Thanks, the fix is correct: only PendingJavaScriptResult lets the caller choose the type with then().
Documentation for vaadin/flow#26890 by
@totally-not-ai[bot].Note
The source pull request is merged, so this documentation describes the final
shape of the change. Please review it and mark it ready for review.
Change categories: NEW_FEATURE, API_CHANGE
articles/flow/component-internals/element-api/calling-javascript.adocJavaScriptResult<T>as a return type to get a converted value with no type token at the call site, update the surrounding return-type and interface-checking text to cover it, and add a new Typed Results subsection.articles/flow/advanced/browser-access.adoc@JsDefinitionmethods can also return a typedJavaScriptResult, and link to Typed Results.Auto-generated by the Documentation Bot — review before merging.