Package com.vaadin.ui

Class Upload

  • All Implemented Interfaces:
    ConnectorEventListener, ContextClickEvent.ContextClickNotifier, MethodEventSource, SerializableEventListener, ClientConnector, Sizeable, VariableOwner, Connector, Component, Component.Focusable, LegacyComponent, Serializable, EventListener
    public class Upload
extends AbstractComponent
implements Component.Focusable, LegacyComponent
    Component for uploading files from client to server.

    The visible component consists of a file name input box and a browse button and an upload submit button to start uploading.

    The Upload component needs a java.io.OutputStream to write the uploaded data. You need to implement the Upload.Receiver interface and return the output stream in the receiveUpload() method.

    You can get an event regarding starting (StartedEvent), progress (ProgressEvent), and finishing (FinishedEvent) of upload by implementing StartedListener, ProgressListener, and FinishedListener, respectively. The FinishedListener is called for both failed and succeeded uploads. If you wish to separate between these two cases, you can use SucceededListener (SucceededEvenet) and FailedListener (FailedEvent).

    The upload component does not itself show upload progress, but you can use the ProgressIndicator for providing progress feedback by implementing ProgressListener and updating the indicator in updateProgress().

    Setting upload component immediate with setImmediateMode(boolean) initiates the upload as soon as a file is selected, instead of the common pattern of file selection field and upload button.

    Note! Because of browser dependent implementations of <input type="file"> element, setting size for Upload component is not supported. For some browsers setting size may work to some extend.

    Since:
    3.0
    Author:
    Vaadin Ltd.
    See Also:
    Serialized Form

    • Constructor Detail

      • Upload

        public Upload()
        Creates a new instance of Upload. The receiver must be set before performing an upload.

    • Method Detail

      • addStartedListener

        public Registration addStartedListener​(Upload.StartedListener listener)
        Adds the upload started event listener.
        Parameters:
        listener - the Listener to be added, not null
        Since:
        8.0

      • removeStartedListener

        @Deprecated
public void removeStartedListener​(Upload.StartedListener listener)
        Deprecated.
        Removes the upload started event listener.
        Parameters:
        listener - the Listener to be removed.

      • addFinishedListener

        public Registration addFinishedListener​(Upload.FinishedListener listener)
        Adds the upload received event listener.
        Parameters:
        listener - the Listener to be added, not null
        Since:
        8.0

      • removeFinishedListener

        @Deprecated
public void removeFinishedListener​(Upload.FinishedListener listener)
        Deprecated.
        Removes the upload received event listener.
        Parameters:
        listener - the Listener to be removed.

      • addFailedListener

        public Registration addFailedListener​(Upload.FailedListener listener)
        Adds the upload interrupted event listener.
        Parameters:
        listener - the Listener to be added, not null
        Since:
        8.0

      • removeFailedListener

        @Deprecated
public void removeFailedListener​(Upload.FailedListener listener)
        Deprecated.
        Removes the upload interrupted event listener.
        Parameters:
        listener - the Listener to be removed.

      • addSucceededListener

        public Registration addSucceededListener​(Upload.SucceededListener listener)
        Adds the upload success event listener.
        Parameters:
        listener - the Listener to be added, not null
        Since:
        8.0

      • removeSucceededListener

        @Deprecated
public void removeSucceededListener​(Upload.SucceededListener listener)
        Deprecated.
        Removes the upload success event listener.
        Parameters:
        listener - the Listener to be removed.

      • addProgressListener

        public Registration addProgressListener​(Upload.ProgressListener listener)
        Adds the upload progress event listener.
        Parameters:
        listener - the progress listener to be added
        Since:
        8.0

      • removeProgressListener

        @Deprecated
public void removeProgressListener​(Upload.ProgressListener listener)
        Deprecated.
        Removes the upload progress event listener.
        Parameters:
        listener - the progress listener to be removed

      • addChangeListener

        public Registration addChangeListener​(Upload.ChangeListener listener)
        Adds a filename change event listener.
        Parameters:
        listener - the Listener to add, not null
        Since:
        8.0

      • removeChangeListener

        @Deprecated
public void removeChangeListener​(Upload.ChangeListener listener)
        Deprecated.
        Removes a filename change event listener.
        Parameters:
        listener - the listener to be removed

      • fireStarted

        protected void fireStarted​(String filename,
                           String mimeType)
        Emit upload received event.
        Parameters:
        filename -
        mimeType -

      • fireUploadInterrupted

        protected void fireUploadInterrupted​(String filename,
                                     String mimeType,
                                     long length)
        Emits the upload failed event.
        Parameters:
        filename -
        mimeType -
        length -

      • fireNoInputStream

        protected void fireNoInputStream​(String filename,
                                 String mimeType,
                                 long length)

      • fireNoOutputStream

        protected void fireNoOutputStream​(String filename,
                                  String mimeType,
                                  long length)

      • fireUploadInterrupted

        protected void fireUploadInterrupted​(String filename,
                                     String mimeType,
                                     long length,
                                     Exception e)

      • fireUploadSuccess

        protected void fireUploadSuccess​(String filename,
                                 String MIMEType,
                                 long length)
        Emits the upload success event.
        Parameters:
        filename -
        MIMEType -
        length -

      • fireUpdateProgress

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

      • getReceiver

        public Upload.Receiver getReceiver()
        Returns the current receiver.
        Returns:
        the StreamVariable.

      • setReceiver

        public void setReceiver​(Upload.Receiver receiver)
        Sets the receiver.
        Parameters:
        receiver - the receiver to set.

      • setTabIndex

        public void setTabIndex​(int tabIndex)
        Sets the Tabulator index of this Focusable component.
        Specified by:
        setTabIndex in interface Component.Focusable
        Parameters:
        tabIndex - the tab order of this component. Indexes usually start from 1. Zero means that default tab order should be used. A negative value means that the field should not be included in the tabbing sequence.
        See Also:
        Component.Focusable.setTabIndex(int)

      • startUpload

        public void startUpload()
        Go into upload state. This is to prevent double uploading on same component. Warning: this is an internal method used by the framework and should not be used by user of the Upload component. Using it results in the Upload component going in wrong state and not working. It is currently public because it is used by another class.

      • interruptUpload

        public void interruptUpload()
        Interrupts 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.

      • isUploading

        public boolean isUploading()

      • getBytesRead

        public long getBytesRead()
        Gets read bytes of the file currently being uploaded.
        Returns:
        bytes

      • getUploadSize

        public long getUploadSize()
        Returns size of file currently being uploaded. Value sane only during upload.
        Returns:
        size in bytes

      • getButtonCaption

        public String getButtonCaption()
        Returns the string rendered into button that fires uploading.
        Returns:
        String to be rendered into button that fires uploading

      • getButtonStyleName

        public String getButtonStyleName()
        Returns the style name rendered into button that fires uploading.
        Returns:
        Style name to be rendered into button that fires uploading
        Since:
        8.2

      • isButtonCaptionAsHtml

        public boolean isButtonCaptionAsHtml()
        Checks whether the caption of the button that fires uploading is rendered as HTML

        The default is false, i.e. to render that caption as plain text.

        Returns:
        true if the caption is rendered as HTML, false if rendered as plain text
        Since:
        8.11

      • setButtonCaption

        public void setButtonCaption​(String buttonCaption)
        In addition to the actual file chooser, upload components have button that starts actual upload progress. This method is used to set text in that button.

        In case the button text is set to null, the button is hidden. In this case developer must explicitly initiate the upload process with submitUpload().

        In case the Upload is used in immediate mode using setImmediateMode(boolean), the file chooser (HTML input with type "file") is hidden and only the button with this text is shown.

        Note the string given is set as is to the button. HTML formatting is not stripped. Be sure to properly validate your value according to your needs.

        Parameters:
        buttonCaption - text for upload components button.

      • setButtonStyleName

        public void setButtonStyleName​(String buttonStyleName)
        In addition to the actual file chooser, upload components have button that starts actual upload progress. This method is used to set a style name to that button.

        Note: Unlike Button.setStyleName() this method overrides all the styles from the button. If you wish to preserve the default styles, enter the style name as "v-button yourStyleName".

        Parameters:
        buttonStyleName - style name for upload components button.
        Since:
        8.2
        See Also:
        about when the button is shown / hidden.

      • setButtonCaptionAsHtml

        public void setButtonCaptionAsHtml​(boolean buttonCaptionAsHtml)
        In addition to the actual file chooser, upload components have button that starts actual upload progress. This method is used to set whether the caption on that button is rendered as HTML.

        If set to true, the caption is rendered in the browser as HTML and the developer is responsible for ensuring no harmful HTML is used. If set to false, the caption is rendered in the browser as plain text.

        The default is false, i.e. to render the caption as plain text.

        Parameters:
        buttonCaptionAsHtml - true if the caption is rendered as HTML, false if rendered as plain text
        Since:
        8.11

      • submitUpload

        public void submitUpload()
        Instructs the upload component to send selected file to the server.

        In case developer wants to use this feature, he/she will most probably want to hide the upload component's internal submit button by setting its caption to null with setButtonCaption(String) method.

        Note that the upload runs asynchronously. Developer should use normal upload listeners to track the process of upload. If the file name field is empty, no upload will be triggered.

        Also note that the developer should not remove or modify the upload component in the same user transaction where the upload submit is requested. The upload component can be safely hidden or removed once the upload started event has been fired.

      • getListeners

        public Collection<?> getListeners​(Class<?> eventType)
        Description copied from class: AbstractClientConnector
        Returns all listeners that are registered for the given event type or one of its subclasses.
        Overrides:
        getListeners in class AbstractClientConnector
        Parameters:
        eventType - The type of event to return listeners for.
        Returns:
        A collection with all registered listeners. Empty if no listeners are found.

      • setImmediateMode

        public void setImmediateMode​(boolean immediateMode)
        Sets the immediate mode of the upload.

        If the upload is in immediate mode, the file upload is started immediately after the user has selected the file.

        If the upload is not in immediate mode, after selecting the file the user must click another button to start the upload.

        The default mode of an Upload component is immediate.

        Parameters:
        immediateMode - true for immediate mode, false for not
        Since:
        8.0

      • isImmediateMode

        public boolean isImmediateMode()
        Returns the immediate mode of the upload.

        The default mode of an Upload component is immediate.

        Returns:
        true if the upload is in immediate mode, false if the upload is not in immediate mode
        Since:
        8.0
        See Also:
        setImmediateMode(boolean)

      • getState

        protected UploadState getState()
        Description copied from class: AbstractComponent
        Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().
        Overrides:
        getState in class AbstractComponent
        Returns:
        updated component shared state

      • getAcceptMimeTypes

        public String getAcceptMimeTypes()
        Returns the component's list of accepted content-types. According to RFC 1867, if the attribute is present, the browser might constrain the file patterns prompted for to match those with the corresponding appropriate file extensions for the platform.
        Returns:
        comma-separated list of desired mime types to be uploaded
        Since:
        8.5
        See Also:
        setAcceptMimeTypes(java.lang.String)

      • setAcceptMimeTypes

        public void setAcceptMimeTypes​(String acceptMimeTypes)
        Sets the component's list of accepted content-types. According to RFC 1867, if the attribute is present, the browser might constrain the file patterns prompted for to match those with the corresponding appropriate file extensions for the platform. Good examples are: image/* or image/png,text/plain
        Parameters:
        acceptMimeTypes - comma-separated list of desired mime types to be uploaded
        Since:
        8.5
        See Also:
        getAcceptMimeTypes()