Package com.vaadin.flow.component.upload

Class Upload

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.upload.Upload
All Implemented Interfaces:
AttachNotifier, DetachNotifier, HasElement, HasEnabled, HasSize, HasStyle, Serializable
@Tag("vaadin-upload") @NpmPackage(value="@vaadin/upload", version="25.0.0-alpha19") @JsModule("@vaadin/upload/src/vaadin-upload.js") public class Upload extends Component implements HasEnabled, HasSize, HasStyle
Upload is a component for uploading one or more files. It shows the upload progression and status of each file. Files can be uploaded using the Upload button or via drag and drop.
Author:
Vaadin Ltd.
See Also:

  • Constructor Details

    • Upload

      public Upload()
      Create a new instance of Upload.

      The upload handler must be set through setUploadHandler(UploadHandler) before performing an upload.

    • Upload

      @Deprecated(since="24.8", forRemoval=true) public Upload(Receiver receiver)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use Upload(UploadHandler) instead
      Create a new instance of Upload with the given receiver.
      Parameters:
      receiver - receiver that handles the upload

    • Upload

      public Upload(UploadHandler handler)
      Create a new instance of Upload with the given upload handler.
      Parameters:
      handler - upload handler that handles the upload, not null

  • Method Details

    • addAllFinishedListener

      public Registration addAllFinishedListener(ComponentEventListener<AllFinishedEvent> listener)
      Add listener that is informed on all uploads finished.
      Parameters:
      listener - all finished listener to add
      Returns:
      a Registration for removing the event listener

    • 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

    • getMaxFiles

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

    • setMaxFileSize

      public void setMaxFileSize(int 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

    • getMaxFileSize

      public int getMaxFileSize()
      Get the maximum allowed file size in the client-side, in bytes.
      Returns:
      the maximum file size in bytes

    • 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.

    • setDropAllowed

      public void setDropAllowed(boolean dropAllowed)
      Define whether the element supports dropping files on it for uploading. By default it's enabled in desktop and disabled in touch devices because mobile devices do not support drag events in general. Setting it true means that drop is enabled even in touch-devices, and false disables drop in all devices.
      Parameters:
      dropAllowed - true to allow file dropping, false otherwise

    • isDropAllowed

      public boolean isDropAllowed()
      Get whether file dropping is allowed or not. By default it's enabled in desktop and disabled in touch devices because mobile devices do not support drag events in general.
      Returns:
      true if file dropping is allowed, false otherwise.

    • setAcceptedFileTypes

      public void setAcceptedFileTypes(String... acceptedFileTypes)
      Specify the types of files that the Upload web-component 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"

      File format restrictions are checked only on the client side (browser). They indicate the hints for users as to what file types to upload. Using this method won’t restrict the uploaded file’s format on the server side. If required, it’s the responsibility of the application developer to implement application-specific restrictions on the server side in one or more of the Upload component’s event listeners (e.g., in addSucceededListener(com.vaadin.flow.component.ComponentEventListener<com.vaadin.flow.component.upload.SucceededEvent>)).

      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.

    • setUploadButton

      public void setUploadButton(Component button)
      Set the component as the actionable button inside the upload component, that opens the dialog for choosing the files to be upload.
      Parameters:
      button - the component to be clicked by the user to open the dialog, or null to reset to the default button

    • getUploadButton

      public Component getUploadButton()
      Get the component set as the upload button for the upload.
      Returns:
      the actionable button, never null.

    • setDropLabel

      public void setDropLabel(Component label)
      Set the component to show as a message to the user to drop files in the upload component. Despite of the name, the label can be any component.
      Parameters:
      label - the label to show for the users when it's possible drop files, or null to reset to the default label

    • getDropLabel

      public Component getDropLabel()
      Get the component set as the drop label.
      Returns:
      the drop label component, never null.

    • setDropLabelIcon

      public void setDropLabelIcon(Component icon)
      Set the component to show as the drop label icon. The icon is visible when the user can drop files to this upload component. Despite of the name, the drop label icon can be any component.
      Parameters:
      icon - the label icon to show for the users when it's possible to drop files, or null to reset to the default icon

    • getDropLabelIcon

      public Component getDropLabelIcon()
      Get the component set as the drop label icon.
      Returns:
      the drop label icon component, never null.

    • interruptUpload

      public void interruptUpload()
      Interrupt the upload currently being received.

      The interruption will be done by the receiving thread so this method will return immediately and the actual interrupt will happen a bit later.

      Note! this will interrupt all ongoing uploads in multi-upload mode.

    • isUploading

      public boolean isUploading()
      Is upload in progress.
      Returns:
      true if receiving upload

    • fireUpdateProgress

      @Deprecated(since="24.4") protected void fireUpdateProgress(long totalBytes, long contentLength)
      Deprecated.
      since 24.4. Use fireUpdateProgress(long, long, String)
      Emit the progress event.
      Parameters:
      totalBytes - bytes received so far
      contentLength - actual size of the file being uploaded, if known

    • fireUpdateProgress

      protected void fireUpdateProgress(long totalBytes, long contentLength, String fileName)
      Emit the progress event.
      Parameters:
      totalBytes - bytes received so far
      contentLength - actual size of the file being uploaded, if known
      fileName - name of the file being uploaded

    • addProgressListener

      @Deprecated(since="24.8", forRemoval=true) public Registration addProgressListener(ComponentEventListener<ProgressUpdateEvent> listener)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use TransferProgressListener with UploadHandler implementing the TransferProgressAwareHandler interface.
      Add a progress listener that is informed on upload progress.
      Parameters:
      listener - progress listener to add
      Returns:
      registration for removal of listener

    • addFailedListener

      @Deprecated(since="24.8", forRemoval=true) public Registration addFailedListener(ComponentEventListener<FailedEvent> listener)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use TransferProgressListener with UploadHandler implementing the TransferProgressAwareHandler interface.
      Add a succeeded listener that is informed on upload failure.
      Parameters:
      listener - failed listener to add
      Returns:
      registration for removal of listener

    • addFinishedListener

      @Deprecated(since="24.8", forRemoval=true) public Registration addFinishedListener(ComponentEventListener<FinishedEvent> listener)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use TransferProgressListener with UploadHandler implementing the TransferProgressAwareHandler interface.
      Add a succeeded listener that is informed on upload finished.
      Parameters:
      listener - finished listener to add
      Returns:
      registration for removal of listener

    • addStartedListener

      @Deprecated(since="24.8", forRemoval=true) public Registration addStartedListener(ComponentEventListener<StartedEvent> listener)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use TransferProgressListener with UploadHandler implementing the TransferProgressAwareHandler interface.
      Add a succeeded listener that is informed on upload start.
      Parameters:
      listener - start listener to add
      Returns:
      registration for removal of listener

    • addSucceededListener

      @Deprecated(since="24.8", forRemoval=true) public Registration addSucceededListener(ComponentEventListener<SucceededEvent> listener)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use TransferProgressListener with UploadHandler implementing the TransferProgressAwareHandler interface.
      Add a succeeded listener that is informed on upload succeeded.
      Parameters:
      listener - succeeded listener to add
      Returns:
      registration for removal of listener

    • addFileRejectedListener

      public Registration addFileRejectedListener(ComponentEventListener<FileRejectedEvent> listener)
      Adds a listener for file-reject events fired when a file cannot be added due to some constrains: setMaxFileSize, setMaxFiles, setAcceptedFileTypes
      Parameters:
      listener - the listener
      Returns:
      a Registration for removing the event listener

    • addFileRemovedListener

      public Registration addFileRemovedListener(ComponentEventListener<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

    • getReceiver

      @Deprecated(since="24.8", forRemoval=true) public Receiver getReceiver()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Return the current receiver.

      Will return null when used with the UploadHandler which is recommended.

      Returns:
      the StreamVariable.

    • setReceiver

      @Deprecated(since="24.8", forRemoval=true) public void setReceiver(Receiver receiver)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use setUploadHandler(UploadHandler) instead
      Set the receiver implementation that should be used for this upload component.

      Note! If the receiver doesn't implement MultiFileReceiver then the upload will be automatically set to only accept one file.

      Parameters:
      receiver - receiver to use for file reception
      See Also:

    • setUploadHandler

      public void setUploadHandler(UploadHandler handler)
      Set the upload handler to be used for this upload component.

      The given handler defines how uploaded file content is handled on the server and invoked per each single file to be uploaded. Note! This method overrides the receiver set by setReceiver(Receiver).

      Parameters:
      handler - upload handler to use for file receptions, not null

    • setI18n

      public void setI18n(UploadI18N i18n)
      Set the internationalization properties for this component.
      Parameters:
      i18n - the i18n object, not null

    • onAttach

      protected void onAttach(AttachEvent attachEvent)
      Description copied from class: Component
      Called when the component is attached to a UI.

      This method is invoked before the AttachEvent is fired for the component.

      Make sure to call super.onAttach when overriding this method.
      Overrides:
      onAttach in class Component
      Parameters:
      attachEvent - the attach event

    • getI18n

      public UploadI18N getI18n()
      Get the internationalization object previously set for this component.

      NOTE: Updating the instance that is returned from this method will not update the component if not set again using setI18n(UploadI18N)

      Returns:
      the i18n object or null if no i18n object has been set

    • clearFileList

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