Package com.vaadin.flow.server.streams

Interface DownloadHandler

All Superinterfaces:
ElementRequestHandler, Serializable
All Known Implementing Classes:
AbstractDownloadHandler, ClassDownloadHandler, FileDownloadHandler, InputStreamDownloadHandler, ServletResourceDownloadHandler
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface DownloadHandler extends ElementRequestHandler
Provides a flexible high-level abstraction for implementing file and arbitrary content downloads from server to client in Vaadin applications.

This interface can be implemented in two ways:

The interface provides several factory methods for common download scenarios:

Example: 
 DownloadHandler.forFile(new File("/path/to/file.txt"));
All factory methods have overloads that allow adding a download progress listener and set a custom file name and URL postfix: 
 DownloadHandler.forClassResource(MyView.class, "attachment-XYZ.txt",
         "attachment.txt", new TransferProgressListener() {
             @Override
             public void onComplete(TransferContext context,
                     long transferredBytes) {
                 // update UI on complete
             }
         });

If you need to write directly to an OutputStream, you can use a lambda expression with event.getOutputStream() to access the output stream: 

 DownloadHandler handler = event -> {
     try (OutputStream out = event.getOutputStream()) {
         // Write your data to the output stream
         out.write(yourData);
     }
 };
Since:
24.8

  • Method Details

    • handleDownloadRequest

      void handleDownloadRequest(DownloadEvent event) throws IOException
      Method that is called when the client wants to download from the url stored for this specific handler registration.
      Parameters:
      event - download event containing the necessary data for writing the response
      Throws:
      IOException - if an IO error occurred during download

    • handleRequest

      default void handleRequest(VaadinRequest request, VaadinResponse response, VaadinSession session, Element owner) throws IOException
      Description copied from interface: ElementRequestHandler
      Request handler callback for handing client-server or server-client data transfer scoped to a specific (owner) element. Note: when handling requests via this API, you need to take care of typical stream handling issues, e.g. exceptions yourself. However, you do not need to close the stream yourself, Flow will handle that for you when needed.
      Specified by:
      handleRequest in interface ElementRequestHandler
      Parameters:
      request - VaadinRequest request to handle
      response - VaadinResponse response to handle
      session - VaadinSession current VaadinSession
      owner - Element owner element
      Throws:
      IOException - if an IO error occurred during data transfer

    • forFile

      static FileDownloadHandler forFile(File file)
      Get a download handler for serving given File.

      The downloaded file name is resolved as file.getName().

      Parameters:
      file - file to server for download
      Returns:
      DownloadHandler implementation for download a file

    • forFile

      static FileDownloadHandler forFile(File file, String fileNameOverride)
      Get a download handler for serving given File with the given download file name.
      Parameters:
      file - file to server for download
      fileNameOverride - download file name that overrides file.getName() and also used as a download request URL postfix
      Returns:
      DownloadHandler implementation for download a file

    • forFile

      static FileDownloadHandler forFile(File file, String fileNameOverride, TransferProgressListener listener)
      Get a download handler for serving given File with the given download file name and progress listener.
      Parameters:
      file - file to server for download
      fileNameOverride - download file name that overrides file.getName() and also used as a download request URL postfix
      listener - listener for transfer progress events
      Returns:
      DownloadHandler implementation for download a file

    • forFile

      static FileDownloadHandler forFile(File file, TransferProgressListener listener)
      Get a download handler for serving given File with the given progress listener.

      The downloaded file name is resolved as file.getName().

      Parameters:
      file - file to server for download
      listener - listener for transfer progress events
      Returns:
      DownloadHandler implementation for download a file

    • forClassResource

      static ClassDownloadHandler forClassResource(Class<?> clazz, String resourceName)
      Generate a download handler for class resource.

      For instance for the file resources/com/example/ui/MyData.json and class com.example.ui.MyData the definition would be forClassResource(MyData.class, "MyData.json").

      The downloaded file name is resolved as resourceName.

      Parameters:
      clazz - class for resource module
      resourceName - name of class resource
      Returns:
      DownloadHandler implementation for download a class resource

    • forClassResource

      static ClassDownloadHandler forClassResource(Class<?> clazz, String resourceName, String fileNameOverride)
      Generate a download handler for class resource with the given download name.

      For instance for the file resources/com/example/ui/MyData.json and class com.example.ui.MyData the definition would be forClassResource(MyData.class, "MyData.json", "Data.json")

      Parameters:
      clazz - class for resource module
      resourceName - name of class resource
      fileNameOverride - download file name that overrides resourceName and also used as a download request URL postfix
      Returns:
      DownloadHandler implementation for download a class resource

    • forClassResource

      static ClassDownloadHandler forClassResource(Class<?> clazz, String resourceName, String fileNameOverride, TransferProgressListener listener)
      Generate a download handler for class resource with the given download name and progress listener.

      For instance for the file resources/com/example/ui/MyData.json and class com.example.ui.MyData the definition would be forClassResource(MyData.class, "MyData.json", "Data.json")

      Parameters:
      clazz - class for resource module
      resourceName - name of class resource
      fileNameOverride - download file name that overrides resourceName and also used as a download request URL postfix
      listener - listener for transfer progress events
      Returns:
      DownloadHandler implementation for download a class resource

    • forClassResource

      static ClassDownloadHandler forClassResource(Class<?> clazz, String resourceName, TransferProgressListener listener)
      Generate a download handler for class resource with the given progress listener.

      For instance for the file resources/com/example/ui/MyData.json and class com.example.ui.MyData the definition would be forClassResource(MyData.class, "MyData.json", "Data.json").

      The downloaded file name is resolved as resourceName.

      Parameters:
      clazz - class for resource module
      resourceName - name of class resource
      listener - listener for transfer progress events
      Returns:
      DownloadHandler implementation for download a class resource

    • forServletResource

      static ServletResourceDownloadHandler forServletResource(String path)
      Generate a download handler for a servlet resource.

      For instance for the file webapp/WEB-INF/servlet.json the path would be /WEB-INF/servlet.json.

      The downloaded file name is resolved as the last segment in path.

      Parameters:
      path - the servlet path to the file
      Returns:
      DownloadHandler implementation for downloading a servlet resource

    • forServletResource

      static ServletResourceDownloadHandler forServletResource(String path, String fileNameOverride)
      Generate a download handler for a servlet resource with the given download file name.

      For instance for the file webapp/WEB-INF/servlet.json the path would be /WEB-INF/servlet.json

      File name override is appended to the download url as the logical name of the target file.

      Parameters:
      path - the servlet path to the file
      fileNameOverride - download file name that overrides the name taken from path and also used as a download request URL postfix
      Returns:
      DownloadHandler implementation for downloading a servlet resource

    • forServletResource

      static ServletResourceDownloadHandler forServletResource(String path, String fileNameOverride, TransferProgressListener listener)
      Generate a download handler for a servlet resource with the given download fileNameOverride and progress listener.

      For instance for the file webapp/WEB-INF/servlet.json the path would be /WEB-INF/servlet.json

      File name override is appended to the download url as the logical name of the target file.

      Parameters:
      path - the servlet path to the file
      fileNameOverride - download file name that overrides the name taken from path and also used as a download request URL postfix
      listener - listener for transfer progress events
      Returns:
      DownloadHandler implementation for downloading a servlet resource

    • forServletResource

      static ServletResourceDownloadHandler forServletResource(String path, TransferProgressListener listener)
      Generate a download handler for a servlet resource with the given progress listener.

      For instance for the file webapp/WEB-INF/servlet.json the path would be /WEB-INF/servlet.json.

      Parameters:
      path - the servlet path to the file
      listener - listener for transfer progress events
      Returns:
      DownloadHandler implementation for downloading a servlet resource

    • fromInputStream

      static InputStreamDownloadHandler fromInputStream(InputStreamDownloadCallback callback)
      Generate a function for downloading from a generated InputStream.

      DownloadResponse instances can be created using various factory methods or with new operator.

      Parameters:
      callback - a function that will be called on download
      Returns:
      DownloadHandler implementation for download from an input stream

    • fromInputStream

      static InputStreamDownloadHandler fromInputStream(InputStreamDownloadCallback callback, TransferProgressListener listener)
      Generate a function for downloading from a generated InputStream with the given progress listener.

      DownloadResponse instances can be created using various factory methods or with new operator.

      Parameters:
      callback - a function that will be called on download
      listener - listener for transfer progress events
      Returns:
      DownloadHandler implementation for download from an input stream