Interface UploadHandler

All Superinterfaces:
ElementRequestHandler, Serializable
All Known Implementing Classes:
AbstractFileUploadHandler, FileUploadHandler, InMemoryUploadHandler, TemporaryFileUploadHandler
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 UploadHandler extends ElementRequestHandler
Provides a flexible high-level abstraction for implementing file and arbitrary content uploads from client to server in Vaadin applications.

This interface can be implemented in two ways:

  • By creating a lambda expression that implements the handleUploadRequest(UploadEvent) method
  • By creating a child or anonymous class that implements this interface

The interface provides several factory methods for common upload scenarios:

Example:
 UploadHandler.inMemory((metadata, bytes) -> {
     // validate and save data
 });
 
All factory methods have overloads that allow adding a transfer progress listener:
 UploadHandler.toFile((metadata, file) -> {
     // validate and save file
 }, filename -> new File("/path/to/file", filename),
         new TransferProgressListener() {
             @Override
             public void onComplete(TransferContext context,
                     long transferredBytes) {
                 // show notification about file upload completion
             }
         });
 

You can use a lambda expression to handle uploads directly:

 UploadHandler handler = event -> {
     var name = event.getContentType();
     var size = event.getFileSize();
     // validate file
     try (InputStream inputStream = event.getInputStream()) {
         // process input stream
     }
 };
 
Since:
24.8
  • Method Details

    • handleUploadRequest

      void handleUploadRequest(UploadEvent event) throws IOException
      Method that is called when the client wants to upload data to the url stored for this specific handler registration.

      After upload of all files is done the method responseHandled(boolean, VaadinResponse) will be called.

      Parameters:
      event - upload event containing the necessary data for getting the request
      Throws:
      IOException - if an error occurs during upload
    • responseHandled

      default void responseHandled(boolean success, VaadinResponse response)
      Method called by framework when handleUploadRequest(UploadEvent) methods have been called for all files.

      This method sets the http response return codes according to internal exception handling in the framework.

      If you want custom exception handling and to set the return code, implement this method and overwrite the default functionality.

      Parameters:
      success - is there was no exception thrown for upload
      response - the response object for the upload request
    • 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
    • getRequestSizeMax

      default long getRequestSizeMax()
      The maximum allowed size of a complete request, as opposed to getFileSizeMax(). Only targets stream multipart uploads.

      The default value of -1 indicates, that there is no limit.

      Returns:
      The maximum allowed size, in bytes
    • getFileSizeMax

      default long getFileSizeMax()
      The maximum allowed size of a single uploaded file, as opposed to getRequestSizeMax(). Only targets stream multipart uploads.

      The default value of -1 indicates, that there is no limit.

      Returns:
      Maximum size of a single uploaded file, in bytes
    • getFileCountMax

      default long getFileCountMax()
      The maximum number of files allowed per request. Only targets stream multipart uploads.

      Default is 10000.

      Returns:
      the maximum number of files allowed, -1 means no limit
    • toFile

      static FileUploadHandler toFile(FileUploadCallback successCallback, FileFactory fileFactory)
      Generate an upload handler for storing upload stream into a file.
      Parameters:
      successCallback - consumer to be called when upload successfully completes
      fileFactory - factory for generating file to write to
      Returns:
      file upload handler
    • toFile

      static FileUploadHandler toFile(FileUploadCallback successCallback, FileFactory fileFactory, TransferProgressListener listener)
      Generate an upload handler for storing upload stream into a file with progress handling.
      Parameters:
      successCallback - consumer to be called when upload successfully completes
      fileFactory - factory for generating file to write to
      listener - listener for transfer progress events
      Returns:
      file upload handler instance with progress listener
    • toTempFile

      static TemporaryFileUploadHandler toTempFile(FileUploadCallback successCallback)
      Generate an upload handler for storing upload stream into a temporary file.
      Parameters:
      successCallback - consumer to be called when upload successfully completes
      Returns:
      temporary file upload handler instance
    • toTempFile

      static TemporaryFileUploadHandler toTempFile(FileUploadCallback successCallback, TransferProgressListener listener)
      Generate an upload handler for storing upload stream into a temporary file with progress handling.
      Parameters:
      successCallback - consumer to be called when upload successfully completes
      listener - listener for transfer progress events
      Returns:
      temporary file upload handler instance with progress listener
    • inMemory

      static InMemoryUploadHandler inMemory(InMemoryUploadCallback successCallback)
      Generate upload handler for storing download into in-memory byte[].
      Parameters:
      successCallback - consumer to be called when upload successfully completes
      Returns:
      in-memory upload handler
    • inMemory

      static InMemoryUploadHandler inMemory(InMemoryUploadCallback successCallback, TransferProgressListener listener)
      Generate upload handler for storing download into in-memory byte[] with progress handling.
      Parameters:
      successCallback - consumer to be called when upload successfully completes
      listener - listener for transfer progress events
      Returns:
      in-memory upload handler with progress listener