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 function by overriding toPromiseJs(Trigger).

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 wraps the subclass JsFunction in a shared observer 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

    • toPromiseJs

      protected abstract JsFunction toPromiseJs(Trigger trigger)
      Subclasses return a JsFunction that, when invoked with the trigger's event, evaluates to a Promise. 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 inside the function body — for example, copying a string and resolving with it: 
      
 return JsFunction.of(
         "return ((v) => navigator.clipboard.writeText(v).then(() => v))($0(event))",
         textInput.toJs(trigger)).withArguments("event");
      Parameters:
      trigger - the surrounding trigger this render is for, not null
      Returns:
      the promise-yielding JS function, not null

    • toJs

      protected final JsFunction toJs(Trigger trigger)
      Final by design — subclasses customise the rendered JS through toPromiseJs(com.vaadin.flow.component.trigger.internal.Trigger), 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:
      toJs in class Action
      Parameters:
      trigger - the surrounding trigger this render is for, not null
      Returns:
      the action's JS function, not null