feat: add download handler to html components (#21338)

Adds a download handler callback to those flow html components that fulfil data download from server.
Replaces the stream resource API.

Part of #21255

Author: caalador

flow-html-components/src/main/java/com/vaadin/flow/component/html/Anchor.java

@@ -27,6 +27,8 @@
 import com.vaadin.flow.component.PropertyDescriptors;
 import com.vaadin.flow.component.Tag;
 import com.vaadin.flow.server.AbstractStreamResource;
+import com.vaadin.flow.server.DownloadHandler;
+import com.vaadin.flow.server.ElementRequestHandler;
 import com.vaadin.flow.server.StreamResource;
 import com.vaadin.flow.server.StreamResourceRegistry;
 
@@ -110,6 +112,24 @@ public Anchor(AbstractStreamResource href, String text) {
         setText(text);
     }
 
+    /**
+     * Creates an anchor component with the given text content and a callback
+     * that handles data download from the server to the client when clicking an
+     * anchor.
+     *
+     * @see #setHref(DownloadHandler)
+     * @see #setText(String)
+     *
+     * @param downloadHandler
+     *            the callback that handles data download, not null
+     * @param text
+     *            the text content to set
+     */
+    public Anchor(DownloadHandler downloadHandler, String text) {
+        setHref(downloadHandler);
+        setText(text);
+    }
+
     /**
      * Creates an anchor component with the given href and components as
      * children of this component.
@@ -174,6 +194,21 @@ public void setHref(AbstractStreamResource href) {
         assignHrefAttribute();
     }
 
+    /**
+     * Sets the URL that this anchor links to and that is bound to a given
+     * {@link DownloadHandler} callback on the server for handling data download
+     * from the server to the client when clicking an anchor.
+     *
+     * @param downloadHandler
+     *            the callback that handles data download, not null
+     */
+    public void setHref(DownloadHandler downloadHandler) {
+        this.href = new StreamResourceRegistry.ElementStreamResource(
+                downloadHandler, this.getElement());
+        setRouterIgnore(true);
+        assignHrefAttribute();
+    }
+
     /**
      * The routing mechanism in Vaadin by default intercepts all anchor elements
      * with relative URL. This method can be used make the router ignore this

flow-html-components/src/main/java/com/vaadin/flow/component/html/HtmlObject.java

@@ -26,7 +26,9 @@
 import com.vaadin.flow.component.PropertyDescriptors;
 import com.vaadin.flow.component.Tag;
 import com.vaadin.flow.server.AbstractStreamResource;
+import com.vaadin.flow.server.DownloadHandler;
 import com.vaadin.flow.server.StreamResource;
+import com.vaadin.flow.server.StreamResourceRegistry;
 
 /**
  * Component representing a <code>&lt;object&gt;</code> element.
@@ -131,6 +133,47 @@ public HtmlObject(AbstractStreamResource data, String type,
         add(params);
     }
 
+    /**
+     * Creates a new <code>&lt;object&gt;</code> component with given
+     * {@link DownloadHandler} callback for providing an object data and type
+     * value.
+     *
+     * @see #setData(AbstractStreamResource)
+     * @see #setType(String)
+     *
+     * @param data
+     *            the callback for providing resource data, not null
+     * @param type
+     *            a type attribute value
+     */
+    public HtmlObject(DownloadHandler data, String type) {
+        setData(data);
+        setType(type);
+    }
+
+    /**
+     * Creates a new <code>&lt;object&gt;</code> component with given data
+     * resource, type value and "param" components.
+     *
+     * @see #setData(String)
+     * @see #setType(String)
+     * @see #add(Component...)
+     *
+     *
+     * @param data
+     *            a data attribute value
+     * @param type
+     *            a type attribute value
+     * @param params
+     *            parameter components
+     */
+    public HtmlObject(DownloadHandler data, String type, Param... params) {
+        setData(new StreamResourceRegistry.ElementStreamResource(data,
+                this.getElement()));
+        setType(type);
+        add(params);
+    }
+
     /**
      * Creates a new <code>&lt;object&gt;</code> component with given data and
      * "param" components.
@@ -199,6 +242,19 @@ public void setData(AbstractStreamResource data) {
         getElement().setAttribute("data", data);
     }
 
+    /**
+     * Sets the URL for {@link DownloadHandler} callback as "data" attribute
+     * value .
+     *
+     * @param data
+     *            a "data" attribute value,, not {@code null}
+     */
+    public void setData(DownloadHandler data) {
+        getElement().setAttribute("data",
+                new StreamResourceRegistry.ElementStreamResource(data,
+                        this.getElement()));
+    }
+
     /**
      * Gets the "data" attribute value.
      *

flow-html-components/src/main/java/com/vaadin/flow/component/html/IFrame.java

@@ -21,7 +21,9 @@
 import com.vaadin.flow.component.PropertyDescriptors;
 import com.vaadin.flow.component.Tag;
 import com.vaadin.flow.server.AbstractStreamResource;
+import com.vaadin.flow.server.DownloadHandler;
 import com.vaadin.flow.server.StreamResource;
+import com.vaadin.flow.server.StreamResourceRegistry;
 
 import java.util.Optional;
 import java.util.stream.Collectors;
@@ -134,6 +136,18 @@ public IFrame(String src) {
         setSrc(src);
     }
 
+    /**
+     * Creates a new iframe with download handler callback that provides a
+     * resource from server.
+     *
+     * @param downloadHandler
+     *            the download handler callback that provides a resource from
+     *            server, not null
+     */
+    public IFrame(DownloadHandler downloadHandler) {
+        setSrc(downloadHandler);
+    }
+
     /**
      * Sets the source of the iframe. If the contents at the src of the IFrame
      * has changed and you want to refresh it in the user's browser, the src
@@ -159,6 +173,21 @@ public void setSrc(AbstractStreamResource src) {
         getElement().setAttribute("src", src);
     }
 
+    /**
+     * Sets the source of the iframe with a source URL with the URL of the given
+     * {@link DownloadHandler} callback.
+     *
+     * @see #setSrc(String)
+     *
+     * @param downloadHandler
+     *            the download handler resource, not null
+     */
+    public void setSrc(DownloadHandler downloadHandler) {
+        getElement().setAttribute("src",
+                new StreamResourceRegistry.ElementStreamResource(
+                        downloadHandler, this.getElement()));
+    }
+
     /**
      * Gets the source of the iframe.
      *

flow-html-components/src/main/java/com/vaadin/flow/component/html/Image.java

@@ -24,7 +24,9 @@
 import com.vaadin.flow.component.PropertyDescriptors;
 import com.vaadin.flow.component.Tag;
 import com.vaadin.flow.server.AbstractStreamResource;
+import com.vaadin.flow.server.DownloadHandler;
 import com.vaadin.flow.server.StreamResource;
+import com.vaadin.flow.server.StreamResourceRegistry;
 
 /**
  * Component representing a <code>&lt;img&gt;</code> element.
@@ -85,6 +87,27 @@ public Image(AbstractStreamResource src, String alt) {
         setAlt(alt);
     }
 
+    /**
+     * Creates an image with the given download handler callback for providing
+     * an image data and an alternative text.
+     * <p>
+     * The alternative text given to constructor is always set even if it is the
+     * default empty string which is not retained with {@link #setAlt(String)}.
+     *
+     * @param downloadHandler
+     *            the download handler callback that provides an image data, not
+     *            null
+     * @param alt
+     *            the alternate text
+     *
+     * @see #setSrc(AbstractStreamResource)
+     * @see #setAlt(String)
+     */
+    public Image(DownloadHandler downloadHandler, String alt) {
+        setSrc(downloadHandler);
+        setAlt(alt);
+    }
+
     /**
      * Gets the image URL.
      *
@@ -114,6 +137,19 @@ public void setSrc(AbstractStreamResource src) {
         getElement().setAttribute("src", src);
     }
 
+    /**
+     * Sets the image URL with the URL of the given {@link DownloadHandler}
+     * callback.
+     *
+     * @param downloadHandler
+     *            the download handler resource, not null
+     */
+    public void setSrc(DownloadHandler downloadHandler) {
+        getElement().setAttribute("src",
+                new StreamResourceRegistry.ElementStreamResource(
+                        downloadHandler, this.getElement()));
+    }
+
     /**
      * Sets the alternate text for the image.
      *

flow-html-components/src/test/java/com/vaadin/flow/component/html/AnchorTest.java

@@ -24,6 +24,7 @@
 import com.vaadin.flow.component.Text;
 import com.vaadin.flow.component.UI;
 import com.vaadin.flow.server.AbstractStreamResource;
+import com.vaadin.flow.server.DownloadHandler;
 
 public class AnchorTest extends ComponentTest {
 
@@ -270,6 +271,45 @@ public String getName() {
         Assert.assertNotEquals(href, anchor.getHref());
     }
 
+    @Test
+    public void disabledAnchor_setDownload_hrefIsRemoved_enableAnchor_hrefIsRestored() {
+        mockUI();
+        DownloadHandler downloadHandler = event -> event.getWriter()
+                .write("foo");
+        Anchor anchor = new Anchor(downloadHandler, "bar");
+        String href = anchor.getHref();
+        anchor.setEnabled(false);
+
+        Assert.assertFalse(anchor.getElement().hasAttribute("href"));
+        Assert.assertEquals(href, anchor.getHref());
+
+        anchor.setEnabled(true);
+        Assert.assertEquals(href, anchor.getHref());
+    }
+
+    @Test
+    public void disabledAnchor_setDownloadWhenDisabled_hrefIsPreserved() {
+        mockUI();
+        DownloadHandler downloadHandler = event -> event.getWriter()
+                .write("foo");
+        Anchor anchor = new Anchor(downloadHandler, "bar");
+        String href = anchor.getHref();
+        anchor.setEnabled(false);
+
+        anchor.setHref(new AbstractStreamResource() {
+
+            @Override
+            public String getName() {
+                return "baz";
+            }
+        });
+
+        anchor.setEnabled(true);
+
+        Assert.assertTrue(anchor.getElement().hasAttribute("href"));
+        Assert.assertNotEquals(href, anchor.getHref());
+    }
+
     private void mockUI() {
         ui = new UI();
         UI.setCurrent(ui);

flow-html-components/src/test/java/com/vaadin/flow/component/html/HtmlComponentSmokeTest.java

@@ -49,6 +49,7 @@
 import com.vaadin.flow.internal.StateNode;
 import com.vaadin.flow.internal.change.NodeChange;
 import com.vaadin.flow.server.AbstractStreamResource;
+import com.vaadin.flow.server.DownloadHandler;
 
 public class HtmlComponentSmokeTest {
 
@@ -248,6 +249,29 @@ private static boolean isSpecialSetter(Method method) {
             return true;
         }
 
+        if (method.getDeclaringClass() == IFrame.class
+                && method.getName().startsWith("setSrc")) {
+            return true;
+        }
+
+        if (method.getDeclaringClass() == HtmlObject.class
+                && method.getName().startsWith("setData")
+                && method.getParameterTypes()[0] == DownloadHandler.class) {
+            return true;
+        }
+
+        if (method.getDeclaringClass() == Anchor.class
+                && method.getName().startsWith("setHref")
+                && method.getParameterTypes()[0] == DownloadHandler.class) {
+            return true;
+        }
+
+        if (method.getDeclaringClass() == Image.class
+                && method.getName().startsWith("setSrc")
+                && method.getParameterTypes()[0] == DownloadHandler.class) {
+            return true;
+        }
+
         return false;
     }
 

flow-html-components/src/test/java/com/vaadin/flow/component/html/HtmlObjectTest.java

@@ -15,6 +15,7 @@
  */
 package com.vaadin.flow.component.html;
 
+import java.io.IOException;
 import java.net.URI;
 
 import org.junit.After;
@@ -76,4 +77,29 @@ public void setData_dataAsAResourceinCTOR() {
         Assert.assertEquals(uri.toASCIIString(),
                 object.getElement().getAttribute("data"));
     }
+
+    @Test
+    public void setDownloadHandlerData_dataAsAResource() {
+        UI ui = new UI();
+        UI.setCurrent(ui);
+        HtmlObject object = new HtmlObject();
+        object.setData(event -> event.getWriter().write("foo"));
+
+        Assert.assertTrue("Data should be set as dynamic resource.",
+                object.getElement().getAttribute("data")
+                        .startsWith("VAADIN/dynamic/resource/-1/"));
+    }
+
+    @Test
+    public void setDownloadHandlerData_dataAsAResourceinCTOR() {
+        UI ui = new UI();
+        UI.setCurrent(ui);
+
+        HtmlObject object = new HtmlObject(
+                event -> event.getWriter().write("foo"), "foo");
+
+        Assert.assertTrue("Data should be set as dynamic resource.",
+                object.getElement().getAttribute("data")
+                        .startsWith("VAADIN/dynamic/resource/-1/"));
+    }
 }