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:

  • 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(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 manager's lifecycle is tied to the owner's lifecycle - when the owner is detached from the UI or disabled, uploads will stop working. The owner is typically the view or layout containing the upload UI components.

    • UploadManager

      public UploadManager(Component owner, UploadHandler handler)
      Creates a new upload manager with the given upload handler.
      Parameters:
      owner - The manager's lifecycle is tied to the owner's lifecycle - when the owner is detached from the UI or disabled, 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(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(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

    • setAcceptedMimeTypes

      public void setAcceptedMimeTypes(String... mimeTypes)
      Sets the accepted MIME types for uploads. Only files matching these MIME types will be accepted. Wildcard patterns like "image/*" are supported.

      MIME types are used both as a client-side hint (to filter the file picker) and for server-side validation (to reject uploads that don't match).

      If both MIME types and file extensions are configured, a file must match at least one of each (AND logic).

      Parameters:
      mimeTypes - the accepted MIME types, e.g. "image/*", "application/pdf"; or null to clear
      Throws:
      IllegalArgumentException - if any value is null, blank, or does not contain a / character

    • getAcceptedMimeTypes

      public List<String> getAcceptedMimeTypes()
      Gets the list of accepted MIME types for upload.
      Returns:
      a list of accepted MIME types, never null

    • setAcceptedFileExtensions

      public void setAcceptedFileExtensions(String... extensions)
      Sets the accepted file extensions for uploads. Only files with matching extensions will be accepted. Extensions must start with a dot, e.g. ".pdf", ".txt".

      File extensions are used both as a client-side hint and for server-side validation.

      If both MIME types and file extensions are configured, a file must match at least one of each (AND logic).

      Parameters:
      extensions - the accepted file extensions, each starting with a dot; or null to clear
      Throws:
      IllegalArgumentException - if any value is null, blank, or does not start with a dot

    • getAcceptedFileExtensions

      public List<String> getAcceptedFileExtensions()
      Gets the list of accepted file extensions for upload.
      Returns:
      a list of accepted file extensions, 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

    • setUploadFormat

      public void setUploadFormat(UploadFormat format)
      Sets the upload format to use when sending files to the server.
      Parameters:
      format - the format type

    • getUploadFormat

      public UploadFormat getUploadFormat()
      Gets the upload format used when sending files to the server.
      Returns:
      the upload format, defaults to UploadFormat.RAW

    • 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 Registration addFileRemovedListener(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 Registration addFileRejectedListener(ComponentEventListener<UploadManager.FileRejectedEvent> listener)
      Adds a listener for file-reject events fired when a file cannot be added due to some constraints: setMaxFileSize, setMaxFiles, setAcceptedMimeTypes, setAcceptedFileExtensions
      Parameters:
      listener - the listener
      Returns:
      a Registration for removing the event listener

    • addAllFinishedListener

      public Registration addAllFinishedListener(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