Package com.vaadin.flow.component.upload

Class UploadManager

java.lang.Object
com.vaadin.flow.component.upload.UploadManager
All Implemented Interfaces:
Serializable
public class UploadManager extends Object implements Serializable
A non-visual manager that handles file upload state and XHR requests. It creates a JavaScript UploadManager instance that UI components can connect to.

Unlike the Upload component which provides a complete upload UI, this manager is invisible and UI components connect to it by setting this manager as their target. This allows more freedom in designing the upload experience.

For upload progress monitoring (start, progress, success, failure events), use an UploadHandler that implements TransferProgressAwareHandler.

Example usage: 

 // Create the manager with an upload handler
 var manager = new UploadManager(this,
         UploadHandler.inMemory((metadata, data) -> {
             // Process uploaded file
         }));

 // Create UI components linked to the manager
 var dropZone = new UploadDropZone(manager);
 var addButton = new UploadButton(manager);
 var fileList = new UploadFileList(manager);

 // Add UI components to the layout
 add(dropZone, addButton, fileList);
Author:
Vaadin Ltd.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    UploadManager.AllFinishedEvent
    Event fired when all uploads have finished (either successfully, failed, or aborted).
    static class 
    UploadManager.FileRejectedEvent
    Event fired when a file is rejected by the upload manager due to constraints like max file size, max files, or accepted file types.
    static class 
    UploadManager.FileRemovedEvent
    Event fired when a file is removed from the upload manager.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    FEATURE_FLAG_ID
    The feature flag ID for modular upload components (UploadManager and related components).

  • Constructor Summary

    Constructors
    Constructor
    Description
    UploadManager(com.vaadin.flow.component.Component owner)
    Creates a new upload manager without an upload handler.
    UploadManager(com.vaadin.flow.component.Component owner, com.vaadin.flow.server.streams.UploadHandler handler)
    Creates a new upload manager with the given upload handler.

  • Method Summary

    Modifier and Type
    Method
    Description
    com.vaadin.flow.shared.Registration
    addAllFinishedListener(com.vaadin.flow.component.ComponentEventListener<UploadManager.AllFinishedEvent> listener)
    Add a listener that is informed when all uploads have finished.
    com.vaadin.flow.shared.Registration
    addFileRejectedListener(com.vaadin.flow.component.ComponentEventListener<UploadManager.FileRejectedEvent> listener)
    Adds a listener for file-reject events fired when a file cannot be added due to some constraints: setMaxFileSize, setMaxFiles, setAcceptedFileTypes
    com.vaadin.flow.shared.Registration
    addFileRemovedListener(com.vaadin.flow.component.ComponentEventListener<UploadManager.FileRemovedEvent> listener)
    Adds a listener for events fired when a file is removed.
    void
    clearFileList()
    Clear the list of files being processed, or already uploaded.
    List<String>
    getAcceptedFileTypes()
    Get the list of accepted file types for upload.
    int
    getMaxFiles()
    Get the maximum number of files allowed for the user to select to upload.
    long
    getMaxFileSize()
    Get the maximum allowed file size in the client-side, in bytes.
    boolean
    isAutoUpload()
    Get the auto upload status.
    boolean
    isEnabled()
    Gets whether the upload manager is enabled.
    boolean
    isUploading()
    Checks if an upload is currently in progress.
    void
    setAcceptedFileTypes(String... acceptedFileTypes)
    Specify the types of files that the upload accepts.
    void
    setAutoUpload(boolean autoUpload)
    When false, it prevents uploads from triggering immediately upon adding file(s).
    void
    setEnabled(boolean enabled)
    Sets whether the upload manager is enabled.
    void
    setMaxFiles(int maxFiles)
    Limit of files to upload, by default it is unlimited.
    void
    setMaxFileSize(long maxFileSize)
    Specify the maximum file size in bytes allowed to upload.
    void
    setUploadHandler(com.vaadin.flow.server.streams.UploadHandler handler)
    Sets the upload handler that processes uploaded files.
    void
    setUploadHandler(com.vaadin.flow.server.streams.UploadHandler handler, String targetName)
    Sets the upload handler that processes uploaded files.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • FEATURE_FLAG_ID

      public static final String FEATURE_FLAG_ID
      The feature flag ID for modular upload components (UploadManager and related components).
      See Also:

  • Constructor Details

    • UploadManager

      public UploadManager(com.vaadin.flow.component.Component owner)
      Creates a new upload manager without an upload handler. The handler must be set using setUploadHandler(UploadHandler) before uploads can work.
      Parameters:
      owner - the component that owns this manager. The manager's lifecycle is tied to the owner's lifecycle - when the owner is detached from the UI, uploads will stop working. The owner is typically the view or layout containing the upload UI components.

    • UploadManager

      public UploadManager(com.vaadin.flow.component.Component owner, com.vaadin.flow.server.streams.UploadHandler handler)
      Creates a new upload manager with the given upload handler.
      Parameters:
      owner - the component that owns this manager. The manager's lifecycle is tied to the owner's lifecycle - when the owner is detached from the UI, uploads will stop working. The owner is typically the view or layout containing the upload UI components.
      handler - the upload handler to use

  • Method Details

    • setUploadHandler

      public void setUploadHandler(com.vaadin.flow.server.streams.UploadHandler handler)
      Sets the upload handler that processes uploaded files.

      This overload uses the default upload target name "upload", which becomes the last segment of the dynamically generated upload URL.

      Parameters:
      handler - the upload handler, not null

    • setUploadHandler

      public void setUploadHandler(com.vaadin.flow.server.streams.UploadHandler handler, String targetName)
      Sets the upload handler that processes uploaded files.
      Parameters:
      handler - the upload handler, not null
      targetName - the endpoint name (single path segment), used as the last path segment of the dynamically generated upload URL; must not be blank

    • setMaxFiles

      public void setMaxFiles(int maxFiles)
      Limit of files to upload, by default it is unlimited. If the value is set to one, the native file browser will prevent selecting multiple files.
      Parameters:
      maxFiles - the maximum number of files allowed for the user to select, or 0 for unlimited

    • getMaxFiles

      public int getMaxFiles()
      Get the maximum number of files allowed for the user to select to upload.
      Returns:
      the maximum number of files, or 0 if unlimited

    • setMaxFileSize

      public void setMaxFileSize(long maxFileSize)
      Specify the maximum file size in bytes allowed to upload. Notice that it is a client-side constraint, which will be checked before sending the request.
      Parameters:
      maxFileSize - the maximum file size in bytes, or 0 for unlimited

    • getMaxFileSize

      public long getMaxFileSize()
      Get the maximum allowed file size in the client-side, in bytes.
      Returns:
      the maximum file size in bytes, or 0 if unlimited

    • setAcceptedFileTypes

      public void setAcceptedFileTypes(String... acceptedFileTypes)
      Specify the types of files that the upload accepts. Syntax: a MIME type pattern (wildcards are allowed) or file extensions. Notice that MIME types are widely supported, while file extensions are only implemented in certain browsers, so it should be avoided.

      Example: "video/*","image/tiff" or ".pdf","audio/mp3"

      Parameters:
      acceptedFileTypes - the allowed file types to be uploaded, or null to clear any restrictions

    • getAcceptedFileTypes

      public List<String> getAcceptedFileTypes()
      Get the list of accepted file types for upload.
      Returns:
      a list of allowed file types, never null

    • setAutoUpload

      public void setAutoUpload(boolean autoUpload)
      When false, it prevents uploads from triggering immediately upon adding file(s). The default is true.
      Parameters:
      autoUpload - true to allow uploads to start immediately after selecting files, false otherwise

    • isAutoUpload

      public boolean isAutoUpload()
      Get the auto upload status.
      Returns:
      true if the upload of files should start immediately after they are selected, false otherwise

    • setEnabled

      public void setEnabled(boolean enabled)
      Sets whether the upload manager is enabled. When disabled, uploads cannot be started from any linked UI components (buttons, drop zones).

      This is the authoritative server-side control for preventing uploads. Disabling individual UI components only affects the UI but does not prevent a malicious client from initiating uploads. Use this method to securely prevent uploads.

      Parameters:
      enabled - true to enable uploads, false to disable

    • isEnabled

      public boolean isEnabled()
      Gets whether the upload manager is enabled.
      Returns:
      true if uploads are enabled, false otherwise

    • isUploading

      public boolean isUploading()
      Checks if an upload is currently in progress.
      Returns:
      true if receiving upload, false otherwise

    • clearFileList

      public void clearFileList()
      Clear the list of files being processed, or already uploaded.

    • addFileRemovedListener

      public com.vaadin.flow.shared.Registration addFileRemovedListener(com.vaadin.flow.component.ComponentEventListener<UploadManager.FileRemovedEvent> listener)
      Adds a listener for events fired when a file is removed.
      Parameters:
      listener - the listener
      Returns:
      a Registration for removing the event listener

    • addFileRejectedListener

      public com.vaadin.flow.shared.Registration addFileRejectedListener(com.vaadin.flow.component.ComponentEventListener<UploadManager.FileRejectedEvent> listener)
      Adds a listener for file-reject events fired when a file cannot be added due to some constraints: setMaxFileSize, setMaxFiles, setAcceptedFileTypes
      Parameters:
      listener - the listener
      Returns:
      a Registration for removing the event listener

    • addAllFinishedListener

      public com.vaadin.flow.shared.Registration addAllFinishedListener(com.vaadin.flow.component.ComponentEventListener<UploadManager.AllFinishedEvent> listener)
      Add a listener that is informed when all uploads have finished.
      Parameters:
      listener - all finished listener to add
      Returns:
      a Registration for removing the event listener