Class WebClipboard

java.lang.Object

java.awt.datatransfer.Clipboard

vaadinx.awt.datatransfer.WebClipboard

public final class WebClipboard
extends Clipboard

The system clipboard for a Vaadin UI. Round-trips through the browser's Async Clipboard API via a small static-resource helper JS (META-INF/resources/emul/clipboard-helper.js, injected per-UI via Page.addJavaScript("context://emul/clipboard-helper.js") from Toolkit.getSystemClipboard() — see D_clipboard_helper_js. The context:// URL routes through Vaadin's static-resource handler, not Vite's bundler).

Both setContents(Transferable, ClipboardOwner) and getContents(Object) are synchronous from the caller's point of view: they park the calling virtual thread on the PendingJavaScriptResult's CompletableFuture until the browser settles. EHelper.callSwing(Runnable) provides the VT carrier that allows parking; calls from a non-VT thread or with no current UI throw IllegalStateException (R_callswing_envelope). See emulators/decisions.md §D_clipboard.

Throw / WARN split (D_clipboard_throw_warn_split).

• Deployment-fixable failures throw. Missing secure context (plain HTTP / non-localhost), missing navigator.clipboard (ancient browser) — IllegalStateException. The migrator's affordance is to deploy over HTTPS or upgrade the browser; silent no-op would hide a deployment bug.
• Per-call runtime failures WARN and degrade gracefully. NotAllowedError, document-not-focused, decode failures, unexpected browser errors — log via EHelper.onUnimplemented(String, String, Object...) and return an empty WebClipboardSnapshot (read) or fire-and-forget (write). Matches Swing's "clipboard had no data" semantics for read.

Test seam (D_clipboard_test_mode). setTestMode(boolean) bypasses executeJs entirely and holds the most-recently-set Transferable in a server-side field. Karibu unit tests opt in; production stays on the real path. Real-browser e2e validation of the executeJs round-trip is a separate harness (deferred slice).

One instance per Vaadin UI; obtain via Toolkit.getSystemClipboard().

Field Summary

Fields inherited from class Clipboard

contents, owner

Constructor Summary

Constructors

Constructor	Description
WebClipboard()

Method Summary

Modifier and Type	Method	Description
void	addFlavorListener(FlavorListener listener)
Transferable	getContents(Object requestor)
FlavorListener[]	getFlavorListeners()
boolean	isTestMode()	Whether test mode is currently engaged.
void	removeFlavorListener(FlavorListener listener)
void	setContents(Transferable contents, ClipboardOwner owner)
void	setTestMode(boolean testMode)	Toggle the in-process test mode.

Methods inherited from class Clipboard

getAvailableDataFlavors, getData, getName, isDataFlavorAvailable

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

WebClipboard

public WebClipboard()

Method Details

setTestMode

public void setTestMode(boolean testMode)

Toggle the in-process test mode. When true, both setContents(Transferable, ClipboardOwner) and getContents(Object) bypass executeJs and round-trip through a server-side Transferable field instead of the browser. Defaults to false — production code leaves the toggle alone.

isTestMode

public boolean isTestMode()

Whether test mode is currently engaged.

setContents

public void setContents(Transferable contents,
 ClipboardOwner owner)

Not synchronized, unlike the JDK's: this waits for the browser, and a monitor held across that wait deadlocks the session the moment a second UI fiber of it asks for the clipboard — that fiber keeps the session lock while it waits for the monitor, so the browser's answer can't get in. Swing's single EDT would re-enter the monitor instead.

Overrides:

setContents in class Clipboard

getContents

public Transferable getContents(Object requestor)

Not synchronized, for setContents(Transferable, ClipboardOwner)'s reason.

Overrides:

getContents in class Clipboard

addFlavorListener

public void addFlavorListener(FlavorListener listener)

Overrides:

addFlavorListener in class Clipboard

removeFlavorListener

public void removeFlavorListener(FlavorListener listener)

Overrides:

removeFlavorListener in class Clipboard

getFlavorListeners

public FlavorListener[] getFlavorListeners()

Overrides:

getFlavorListeners in class Clipboard