Package com.vaadin.ui

Class Upload

  • All Implemented Interfaces:
    ConnectorEventListener, ContextClickEvent.ContextClickNotifier, MethodEventSource, 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 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 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

      • changeVariables

        public void changeVariables​(Object source,
                            Map<String,​Object> variables)
        Invoked when the value of a variable has changed.
        Specified by:
        changeVariables in interface VariableOwner
        Parameters:
        source - the Source of the variable change. This is the origin of the event. For example in Web Adapter this is the request.
        variables - the Mapping from variable names to new variable values.
        See Also:
        com.vaadin.ui.AbstractComponent#changeVariables(java.lang.Object, java.util.Map)

      • addStartedListener

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

      • removeStartedListener

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

      • addFinishedListener

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

      • removeFinishedListener

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

      • addFailedListener

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

      • removeFailedListener

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

      • addSucceededListener

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

      • removeSucceededListener

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

      • addProgressListener

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

      • removeProgressListener

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

      • addChangeListener

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

      • removeChangeListener

        public void removeChangeListener​(Upload.ChangeListener listener)
        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 -
        length -

      • 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:
        String to be rendered into button that fires uploading

      • 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 AbstractComponent.setImmediate(boolean), the file choose (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.

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

      • 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