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

Class PromiseAction

java.lang.Object
com.vaadin.flow.component.trigger.internal.Action
com.vaadin.flow.component.trigger.internal.PromiseAction
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
CopyTextToClipboardAction, RequestFullscreenAction
public abstract class PromiseAction 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).

Two construction modes, mirroring the Geolocation API:

  • Fire-and-forget — PromiseAction() — the rendered JS is just the promise expression; the server never sees the outcome.
  • With outcome handling — PromiseAction(SerializableRunnable, SerializableConsumer) — supply an onSuccess runnable and an onError consumer (both required; pass () -> {} or err -> {} to opt out of one). 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 record 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(SerializableRunnable onSuccess, SerializableConsumer<String> onError)
      Creates an action whose promise outcome is reported back to the server. onSuccess runs after the promise resolves; onError receives the browser's error message after the promise rejects. Both run on the UI thread. Both consumers are required and must be non-null — pass () -> {} or err -> {} to opt out of one.
      Parameters:
      onSuccess - invoked on the UI thread after the client reports the promise resolved, not null
      onError - invoked on the UI thread with the browser's error message 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 result of that promise is what onSuccess/onError observe; the resolved value itself is not delivered to the server (only success vs. failure and the rejection message).
      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)
      Description copied from class: Action
      Appends this action's JS statement to out. Element references must go through JsBuilder.reference(com.vaadin.flow.dom.Element).
      Specified by:
      appendStatement in class Action
      Parameters:
      builder - collects element parameter references, not null
      out - buffer to append into, not null