Package com.vaadin.flow.server.streams

Class ServletResourceDownloadHandler

java.lang.Object
com.vaadin.flow.server.streams.TransferProgressAwareHandler<DownloadEvent,ServletResourceDownloadHandler>
com.vaadin.flow.server.streams.AbstractDownloadHandler<ServletResourceDownloadHandler>
com.vaadin.flow.server.streams.ServletResourceDownloadHandler
All Implemented Interfaces:
DownloadHandler, ElementRequestHandler, Serializable
public class ServletResourceDownloadHandler extends AbstractDownloadHandler<ServletResourceDownloadHandler>
Download handler for serving a servlet resource for client download.

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

Byte range requests, which media players use to seek and browsers use to resume a download, are not answered by default. A resource is read as a stream from its start up to each range, and in a packaged war it may be compressed, depending on the servlet container, so each seek may inflate all the bytes before it again, which adds up for large media that a player fetches in many small ranges. Call enableRangeRequests() to answer them anyway, or use DownloadHandler.forFile(java.io.File), which answers ranges by seeking in the file.

Since:
24.8
See Also:

  • Constructor Details

    • ServletResourceDownloadHandler

      public ServletResourceDownloadHandler(String path)
      Create download handler for servlet resource. Uses url postfix as file name from path.

      The downloaded file name and download URL postfix will be set to the file name from path. If you want to use a different file name, use ServletResourceDownloadHandler(String, String) instead.

      Parameters:
      path - path of servlet resource

    • ServletResourceDownloadHandler

      public ServletResourceDownloadHandler(String path, String fileNameOverride)
      Create download handler for servlet resource.

      The downloaded file fileNameOverride and download URL postfix will be set to fileNameOverride.

      Parameters:
      path - path of servlet resource
      fileNameOverride - download file name that overrides the name taken from path and also used as a download request URL postfix

  • Method Details

    • handleDownloadRequest

      public void handleDownloadRequest(DownloadEvent downloadEvent) throws IOException
      Description copied from interface: DownloadHandler
      Method that is called when the client wants to download from the url stored for this specific handler registration.

      Once this method has been called, the download is no longer bound to the owner component's lifecycle and is not interrupted by detaching the owner or by closing the browser tab, see the class-level documentation.

      Parameters:
      downloadEvent - download event containing the necessary data for writing the response
      Throws:
      IOException - if an IO error occurred during download

    • enableRangeRequests

      public ServletResourceDownloadHandler enableRangeRequests()
      Enables answering byte range requests, which media players use to seek and browsers use to resume a download. Safari does not play audio or video without them.

      Each range is read by skipping the resource up to its start. For a file on disk that is a seek, but a resource inside a packaged war may have to be read, and inflated if compressed, from its start for every range, depending on the servlet container. That is costly for large media that a player fetches in many small ranges.

      Returns:
      this instance for method chaining

    • isRangeRequestsEnabled

      public boolean isRangeRequestsEnabled()
      Returns whether this handler answers byte range requests, which media players use to seek and browsers use to resume a download. Safari does not play audio or video from a handler that does not answer them.

      A handler that does not answer them sends the whole content for every request. A handler that does may still send the whole content for a particular response, for example when the length of its content is not known. The default implementation returns false.

      In development mode, a built-in handler logs a warning the first time that a handler of its class serves the whole content for a byte range request, for example because ranges are not enabled or the length of the content is unknown.

      Range requests are answered after enableRangeRequests().

      Returns:
      true if the handler is configured to answer byte range requests

    • getUrlPostfix

      public String getUrlPostfix()
      Description copied from interface: ElementRequestHandler
      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. Postfix changes the last segment in the resource url.
      Returns:
      String optional URL postfix, or null for "".