Download handler

[mshabarov]

Describe your motivation

Using an OutputStream in API for downloads is preferable as this is more intuitive when your server-side code wants to downstream data to client, better aligned with the Servlet API.

Describe the solution you'd like

StreamResource is deprecated and a new DownloadHandler concept is introduced as a replacement:

@FunctionalInterface
public interface DownloadHandler {
  void handleDownloadRequest(DownloadEvent event);

  default String getUrlPostfix() {
    return null;
  }
}

This is a layer on top of the generic element-scoped request handler with helpers to give easy access to file reference, class-path resource, servlet context resource or arbitrary input stream.

The optional URL postfix allows appending an application-controlled string, e.g. the logical name of the target file, to the end of the otherwise random-looking download URL. If defined, requests that would otherwise be routable are still rejected if the postfix is missing or invalid.

Just like with StreamResource, the framework should do the regular security checks before invoking the handler. The session is not locked while the handler is run. The handler may lock the session if necessary but it's not recommended to hold the lock while writing data to the response.

All the magic is in the event object. It gives direct access to the underlying request, response and session as well as various helpers specifically for handling downloads.

// Shown as an interface to focus on the API. The actual type should probably be a class.
public interface DownloadEvent {
  // Also sets Content-Disposition to "attachment"
  void setFileName(String fileName);
  void setContentType(String contentType);
  void setFileSize(long fileSize);
   
  OutputStream getOutputStream();
  PrintWriter getWriter();

  // The component to which the download handler is bound
  Component getComponent();

  // The UI that getComponent() is attached to, provided for use with UI:access.
  UI getUI();

  VaadinRequest getRequest();
  VaadinResponse getResponse();
  VaadinSession getSession();
}

DownloadHandler can be used with various component, e.g. Anchor, Image and others:

Image image = new Image((DownloadEvent event) -> { ... }, "Alt text");
Anchor downloadLink = new Anchor((DownloadEvent event) -> { ... }, "Download report");

In addition to the callback method, the DownloadHandler interface also defines factory methods for creating a download handler instance for various common use cases.

public interface DownloadHandler {
  static DownloadHandler forFile(File file);
  static DownloadHandler forClassResource(Class<?> class, String name);
  static DownloadHandler forServletResource(String path);
  static DownloadHandler fromInputStream(Function<DownloadEvent, DownloadResponse> handler);
}

The DownloadResponse return type allows providing an InputStream to read from or a Consumer<OutputStream> to acquire a stream to write to.