Package com.vaadin.flow.component.trigger.internal

Class PromiseAction<T>

java.lang.Object
com.vaadin.flow.component.trigger.internal.Action
com.vaadin.flow.component.trigger.internal.PromiseAction<T>
Type Parameters:
T - type the JS promise resolves with, decoded once on the server
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ReadFromClipboardAction, RequestFullscreenAction, WriteToClipboardAction
public abstract class PromiseAction<T> extends Action
Base class for actions that run a JS expression yielding a Promise and optionally report the outcome back to the server.

Many gesture-bound browser APIs are asynchronous — clipboard, fullscreen, file picker, share, web payment, … — and follow the same shape: call the API, then handle the resolved value or the rejection. This class collapses that pattern into one place so subclasses only need to emit the promise-yielding JS expression by overriding appendPromiseExpression(JsBuilder, StringBuilder).

The type parameter T is the type of value the JS promise resolves with: it gets Jackson-decoded once before onSuccess sees it, so subclasses don't write per-action adapters. Use Void when the promise resolves with no meaningful value (e.g. requestFullscreen).

Two construction modes:

  • Fire-and-forget — PromiseAction() — the rendered JS is just the promise expression; the server never sees the outcome.
  • With outcome handling — PromiseAction(Class, SerializableConsumer, SerializableConsumer) — supply the payload type, an onSuccess consumer receiving the decoded value (or null if the promise resolved with undefined), and an onError consumer receiving an PromiseAction.Error record (all required; pass v -> {} or err -> {} to opt out). The handlers run on the UI thread after the client reports the outcome of the promise.
Under the hood, the with-outcome mode renders one call to a shared JsFunction that subscribes to the promise and pushes an PromiseAction.Outcome through a lazily-registered ReturnChannelRegistration on the trigger host node.

For internal use only. May be renamed or removed in a future release.

See Also:

  • Constructor Details

    • PromiseAction

      protected PromiseAction()
      Creates a fire-and-forget action: the promise's outcome is not reported back to the server.

    • PromiseAction

      protected PromiseAction(Class<T> payloadType, SerializableConsumer<@Nullable T> onSuccess, SerializableConsumer<PromiseAction.Error> onError)
      Creates an action whose promise outcome is reported back to the server. onSuccess runs after the promise resolves and receives the decoded value (or null if the promise resolved with undefined); onError runs after the promise rejects and receives an PromiseAction.Error record with the browser's error name and message. Both run on the UI thread.
      Parameters:
      payloadType - type to deserialise the promise's resolved value to, not null; use Void.class when the promise has no meaningful value
      onSuccess - invoked on the UI thread with the decoded value after the client reports the promise resolved, not null
      onError - invoked on the UI thread with the browser's error after the client reports the promise rejected, not null

  • Method Details

    • appendPromiseExpression

      protected abstract void appendPromiseExpression(com.vaadin.flow.component.trigger.internal.JsBuilder builder, StringBuilder out)
      Subclasses append a JS expression that evaluates to a Promise when the trigger fires. The value the promise resolves with is decoded to T on the server and handed to onSuccess. To deliver a typed value, subclasses can wrap their API call in an IIFE — for example, copying a string and resolving with it: 
      
 ((v) => navigator.clipboard.writeText(v).then(() => v))(<textExpr>)
      Parameters:
      builder - collects element parameter references, not null
      out - buffer to append into, not null

    • appendStatement

      protected final void appendStatement(com.vaadin.flow.component.trigger.internal.JsBuilder builder, StringBuilder out)
      Final by design — subclasses customise the rendered JS through appendPromiseExpression(com.vaadin.flow.component.trigger.internal.JsBuilder, java.lang.StringBuilder), never by overriding the wiring that subscribes to the promise. Keeping the .then/.catch glue identical across subclasses is what makes the PromiseAction.Outcome wire contract stable.
      Specified by:
      appendStatement in class Action
      Parameters:
      builder - collects element parameter references, not null
      out - buffer to append into, not null