feat: add UI.ensureCurrent() to provide better error message if UI is not available (#22665)

Add a new UI.ensureCurrent() method that returns a non-null UI instance
or throws IllegalStateException with a helpful error message guiding
developers to use UI.access() for background threads.

This provides a cleaner alternative to the UI.getCurrent() + null check
pattern and makes code more explicit about requiring an active UI context.

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/component/ComponentUtil.java

@@ -536,11 +536,7 @@ public static <T extends Component> T componentFromElement(Element element,
 
         try {
             Component.elementToMapTo.set(wrapData);
-            UI ui = UI.getCurrent();
-            if (ui == null) {
-                throw new IllegalStateException("UI instance is not available. "
-                        + "It looks like you are trying to execute UI code outside the UI/Servlet dispatching thread");
-            }
+            UI ui = UI.ensureCurrent();
             Instantiator instantiator = Instantiator.get(ui);
             return instantiator.createComponent(componentType);
         } finally {

flow-server/src/main/java/com/vaadin/flow/component/UI.java

@@ -322,6 +322,33 @@ public static UI getCurrent() {
         return CurrentInstance.get(UI.class);
     }
 
+    /**
+     * Gets the currently used UI, throwing an exception if none is available.
+     * Use this method when the code must run within an active UI context.
+     * <p>
+     * This method is useful when code must execute within a UI context and
+     * cannot handle the case where no UI is available. If the code can work
+     * without a UI, use {@link #getCurrent()} instead and check for null.
+     * <p>
+     * The UI is stored using a weak reference to avoid leaking memory in case
+     * it is not explicitly cleared.
+     *
+     * @return the current UI instance, never <code>null</code>
+     * @throws IllegalStateException
+     *             if no UI is bound to the current thread
+     * @see #getCurrent()
+     * @see #access(Command)
+     */
+    public static UI ensureCurrent() {
+        UI ui = getCurrent();
+        if (ui == null) {
+            throw new IllegalStateException(
+                    "No currently active UI found. This code must be run within a UI context. "
+                            + "If you are running this from a background thread, wrap the call in UI.access().");
+        }
+        return ui;
+    }
+
     /**
      * Marks this UI to be {@link #onDetach(DetachEvent) detached} from the
      * session at the end of the current request, or the next request if there

flow-server/src/main/java/com/vaadin/flow/component/page/WebStorage.java

@@ -90,7 +90,7 @@ public static void setItem(String key, String value) {
      *            the value
      */
     public static void setItem(Storage storage, String key, String value) {
-        setItem(UI.getCurrent(), storage, key, value);
+        setItem(UI.ensureCurrent(), storage, key, value);
     }
 
     /**
@@ -132,7 +132,7 @@ public static void removeItem(String key) {
      *            the key to be deleted
      */
     public static void removeItem(Storage storage, String key) {
-        removeItem(UI.getCurrent(), storage, key);
+        removeItem(UI.ensureCurrent(), storage, key);
     }
 
     /**
@@ -165,7 +165,7 @@ public static void clear() {
      *            the storage
      */
     public static void clear(Storage storage) {
-        clear(UI.getCurrent(), storage);
+        clear(UI.ensureCurrent(), storage);
     }
 
     /**
@@ -207,7 +207,7 @@ public static void getItem(String key, Callback callback) {
      *            available.
      */
     public static void getItem(Storage storage, String key, Callback callback) {
-        getItem(UI.getCurrent(), storage, key, callback);
+        getItem(UI.ensureCurrent(), storage, key, callback);
     }
 
     /**
@@ -274,7 +274,7 @@ public static CompletableFuture<String> getItem(String key) {
      */
     public static CompletableFuture<String> getItem(Storage storage,
             String key) {
-        return getItem(UI.getCurrent(), storage, key);
+        return getItem(UI.ensureCurrent(), storage, key);
     }
 
     /**

flow-server/src/main/java/com/vaadin/flow/server/StreamResourceRegistry.java

@@ -124,7 +124,7 @@ public StreamRegistration registerResource(
     public StreamRegistration registerResource(
             ElementRequestHandler elementRequestHandler) {
         return registerResource(elementRequestHandler,
-                UI.getCurrent().getElement());
+                UI.ensureCurrent().getElement());
     }
 
     /**

flow-server/src/main/java/com/vaadin/flow/server/communication/StreamRequestHandler.java

@@ -244,8 +244,8 @@ private PathData parsePath(String pathInfo) {
      * @return generated URI string
      */
     public static String generateURI(String name, String id) {
-        return DYN_RES_PREFIX + UI.getCurrent().getUIId() + PATH_SEPARATOR + id
-                + PATH_SEPARATOR + UrlUtil.encodeURIComponent(name);
+        return DYN_RES_PREFIX + UI.ensureCurrent().getUIId() + PATH_SEPARATOR
+                + id + PATH_SEPARATOR + UrlUtil.encodeURIComponent(name);
     }
 
     private static Optional<URI> getPathUri(String path) {

flow-server/src/main/java/com/vaadin/flow/server/communication/WebComponentBootstrapHandler.java

@@ -441,7 +441,7 @@ protected void writeBootstrapPage(String contentType,
             BootstrapHandler
                     .getStylesheetLinks(context, "document.css",
                             frontendDirectory)
-                    .forEach(link -> UI.getCurrent().getPage().executeJs(
+                    .forEach(link -> UI.ensureCurrent().getPage().executeJs(
                             BootstrapHandler.SCRIPT_TEMPLATE_FOR_STYLESHEET_LINK_TAG,
                             modifyPath(serviceUrl, link)));
         }

flow-server/src/test/java/com/vaadin/flow/component/UITest.java

@@ -1028,6 +1028,36 @@ public void accessLaterRunnable_detachedUi_detachHandlerCalled() {
         assertEquals("Handler should have run once", 1, runCount.get());
     }
 
+    @Test
+    public void ensureCurrent_withCurrentUI_returnsUI() {
+        UI ui = createTestUI();
+        UI.setCurrent(ui);
+
+        UI result = UI.ensureCurrent();
+
+        assertSame("ensureCurrent should return the current UI", ui, result);
+    }
+
+    @Test(expected = IllegalStateException.class)
+    public void ensureCurrent_withoutCurrentUI_throws() {
+        CurrentInstance.clearAll();
+        UI.ensureCurrent();
+    }
+
+    @Test
+    public void ensureCurrent_withoutCurrentUI_throwsWithHelpfulMessage() {
+        CurrentInstance.clearAll();
+        try {
+            UI.ensureCurrent();
+            Assert.fail("Should have thrown IllegalStateException");
+        } catch (IllegalStateException e) {
+            assertTrue("Exception message should mention UI context",
+                    e.getMessage().contains("UI context"));
+            assertTrue("Exception message should mention UI.access()",
+                    e.getMessage().contains("UI.access()"));
+        }
+    }
+
     @Test
     public void csrfToken_differentUIs_shouldBeUnique() {
         String token1 = new UI().getCsrfToken();

vaadin-spring/src/main/java/com/vaadin/flow/spring/scopes/VaadinRouteScope.java

@@ -455,12 +455,7 @@ private static String getWindowName(UI ui) {
     }
 
     private static UI getUI() {
-        UI ui = UI.getCurrent();
-        if (ui == null) {
-            throw new IllegalStateException(
-                    "There is no UI available. The route scope is not active");
-        }
-        return ui;
+        return UI.ensureCurrent();
     }
 
     private static UI findPreservingUI(UI ui) {

vaadin-spring/src/main/java/com/vaadin/flow/spring/scopes/VaadinUIScope.java

@@ -121,11 +121,6 @@ protected BeanStore getBeanStore() {
     }
 
     private UI getUI() {
-        UI ui = UI.getCurrent();
-        if (ui == null) {
-            throw new IllegalStateException(
-                    "There is no UI available. The UI scope is not active");
-        }
-        return ui;
+        return UI.ensureCurrent();
     }
 }

vaadin-spring/src/main/java/com/vaadin/flow/spring/security/AuthenticationContext.java

@@ -131,7 +131,7 @@ public boolean isAuthenticated() {
      * {@link org.springframework.security.web.authentication.logout.LogoutHandler}.
      */
     public void logout() {
-        final UI ui = UI.getCurrent();
+        final UI ui = UI.ensureCurrent();
         boolean pushWebsocketConnected = ui.getPushConfiguration()
                 .getTransport() == Transport.WEBSOCKET
                 && ui.getInternals().getPushConnection().isConnected();