com.vaadin.ui.


Class Upload

java.lang.Object
  com.vaadin.ui.AbstractComponent
      com.vaadin.ui.Upload

All Implemented Interfaces:

MethodEventSource, Paintable, Sizeable, VariableOwner, Component, Component.Focusable, Serializable, EventListener

public class Upload
extends AbstractComponent
implements Component.Focusable

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

Version:

6.8.18

Author:

Vaadin Ltd.

See Also:

Serialized Form

Nested Class Summary
static class Upload.FailedEvent
          Upload.FailedEvent event is sent when the upload is received, but the reception is interrupted for some reason.
static interface Upload.FailedListener
          Receives events when the uploads are finished, but unsuccessful.
static class Upload.FinishedEvent
          Upload.FinishedEvent is sent when the upload receives a file, regardless of whether the reception was successful or failed.
static interface Upload.FinishedListener
          Receives the events when the uploads are ready.
static class Upload.NoInputStreamEvent
          FailedEvent that indicates that an input stream could not be obtained.
static class Upload.NoOutputStreamEvent
          FailedEvent that indicates that an output stream could not be obtained.
static interface Upload.ProgressListener
          ProgressListener receives events to track progress of upload.
static interface Upload.Receiver
          Interface that must be implemented by the upload receivers to provide the Upload component an output stream to write the uploaded data.
static class Upload.StartedEvent
          Upload.StartedEvent event is sent when the upload is started to received.
static interface Upload.StartedListener
          Receives the events when the upload starts.
static class Upload.SucceededEvent
          Upload.SucceededEvent event is sent when the upload is received successfully.
static interface Upload.SucceededListener
          Receives events when the uploads are successfully finished.
 
Nested classes/interfaces inherited from class com.vaadin.ui.AbstractComponent
AbstractComponent.ComponentErrorEvent, AbstractComponent.ComponentErrorHandler
 
Nested classes/interfaces inherited from interface com.vaadin.ui.Component
Component.ErrorEvent, Component.ErrorListener, Component.Event, Component.Focusable, Component.Listener
 
Nested classes/interfaces inherited from interface com.vaadin.terminal.Paintable
Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener
 
Field Summary
 
Fields inherited from interface com.vaadin.terminal.Sizeable
SIZE_UNDEFINED, UNIT_SYMBOLS, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS
 
Constructor Summary
Upload()
          Creates a new instance of Upload.
Upload(String caption, Upload.Receiver uploadReceiver)
           
 
Method Summary
 void addListener(Upload.FailedListener listener)
          Adds the upload interrupted event listener.
 void addListener(Upload.FinishedListener listener)
          Adds the upload received event listener.
 void addListener(Upload.ProgressListener listener)
          Adds the upload success event listener.
 void addListener(Upload.StartedListener listener)
          Adds the upload started event listener.
 void addListener(Upload.SucceededListener listener)
          Adds the upload success event listener.
 void changeVariables(Object source, Map<String,Object> variables)
          Invoked when the value of a variable has changed.
protected  void fireNoInputStream(String filename, String MIMEType, long length)
           
protected  void fireNoOutputStream(String filename, String MIMEType, long length)
           
protected  void fireStarted(String filename, String MIMEType)
          Emit upload received event.
protected  void fireUpdateProgress(long totalBytes, long contentLength)
          Emits the progress event.
protected  void fireUploadInterrupted(String filename, String MIMEType, long length)
          Emits the upload failed event.
protected  void fireUploadInterrupted(String filename, String MIMEType, long length, Exception e)
           
protected  void fireUploadSuccess(String filename, String MIMEType, long length)
          Emits the upload success event.
 void focus()
          Sets the focus for this component if the component is Focusable.
 String getButtonCaption()
           
 long getBytesRead()
          Gets read bytes of the file currently being uploaded.
 Collection<?> getListeners(Class<?> eventType)
          Returns all listeners that are registered for the given event type or one of its subclasses.
 Upload.ProgressListener getProgressListener()
          Deprecated. Replaced with addListener/removeListener
 Upload.Receiver getReceiver()
          Returns the current receiver.
protected  StreamVariable getStreamVariable()
           
 int getTabIndex()
          Gets the Tabulator index of this Focusable component.
 long getUploadSize()
          Returns size of file currently being uploaded.
 void interruptUpload()
          Interrupts the upload currently being received.
 boolean isUploading()
           
 void paintContent(PaintTarget target)
          Paints the content of this component.
 void removeListener(Upload.FailedListener listener)
          Removes the upload interrupted event listener.
 void removeListener(Upload.FinishedListener listener)
          Removes the upload received event listener.
 void removeListener(Upload.ProgressListener listener)
          Removes the upload success event listener.
 void removeListener(Upload.StartedListener listener)
          Removes the upload started event listener.
 void removeListener(Upload.SucceededListener listener)
          Removes the upload success event listener.
 void requestRepaint()
          Requests that the paintable should be repainted as soon as possible.
 void setButtonCaption(String buttonCaption)
          In addition to the actual file chooser, upload components have button that starts actual upload progress.
 void setProgressListener(Upload.ProgressListener progressListener)
          Deprecated. Use addListener(ProgressListener) instead.
 void setReceiver(Upload.Receiver receiver)
          Sets the receiver.
 void setTabIndex(int tabIndex)
          Sets the Tabulator index of this Focusable component.
 void startUpload()
          Go into upload state.
 void submitUpload()
          Forces the upload the send selected file to the server.
 
Methods inherited from class com.vaadin.ui.AbstractComponent
addListener, addListener, addListener, addListener, addListener, addStyleName, attach, childRequestedRepaint, detach, fireComponentErrorEvent, fireComponentEvent, fireEvent, getApplication, getCaption, getComponentError, getData, getDebugId, getDescription, getErrorHandler, getErrorMessage, getHeight, getHeightUnits, getIcon, getLocale, getParent, getStyle, getStyleName, getWidth, getWidthUnits, getWindow, handleError, hasListeners, isEnabled, isImmediate, isReadOnly, isVisible, paint, removeListener, removeListener, removeListener, removeListener, removeListener, removeListener, removeStyleName, requestRepaintRequests, setCaption, setComponentError, setData, setDebugId, setDescription, setEnabled, setErrorHandler, setHeight, setHeight, setHeight, setHeightUnits, setIcon, setImmediate, setLocale, setParent, setReadOnly, setSizeFull, setSizeUndefined, setStyle, setStyleName, setVisible, setWidth, setWidth, setWidth, setWidthUnits
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.vaadin.ui.Component
addListener, addStyleName, attach, childRequestedRepaint, detach, getApplication, getCaption, getIcon, getLocale, getParent, getStyleName, getWindow, isEnabled, isReadOnly, isVisible, removeListener, removeStyleName, setCaption, setEnabled, setIcon, setParent, setReadOnly, setStyleName, setVisible
 
Methods inherited from interface com.vaadin.terminal.Paintable
addListener, getDebugId, paint, removeListener, requestRepaintRequests, setDebugId
 
Methods inherited from interface com.vaadin.terminal.VariableOwner
isImmediate
 
Methods inherited from interface com.vaadin.terminal.Sizeable
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeight, setHeightUnits, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidth, setWidthUnits
 

Constructor Detail

Upload

public Upload()

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

Upload

public Upload(String caption,
              Upload.Receiver uploadReceiver)
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
Overrides:
changeVariables in class AbstractComponent

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:
AbstractComponent.changeVariables(java.lang.Object, java.util.Map)

paintContent

public void paintContent(PaintTarget target)
                  throws PaintException

Paints the content of this component.

Overrides:
paintContent in class AbstractComponent

Parameters:
target - Target to paint the content on.
Throws:
PaintException - if the paint operation failed.

addListener

public void addListener(Upload.StartedListener listener)

Adds the upload started event listener.

Parameters:
listener - the Listener to be added.

removeListener

public void removeListener(Upload.StartedListener listener)

Removes the upload started event listener.

Parameters:
listener - the Listener to be removed.

addListener

public void addListener(Upload.FinishedListener listener)

Adds the upload received event listener.

Parameters:
listener - the Listener to be added.

removeListener

public void removeListener(Upload.FinishedListener listener)

Removes the upload received event listener.

Parameters:
listener - the Listener to be removed.

addListener

public void addListener(Upload.FailedListener listener)

Adds the upload interrupted event listener.

Parameters:
listener - the Listener to be added.

removeListener

public void removeListener(Upload.FailedListener listener)

Removes the upload interrupted event listener.

Parameters:
listener - the Listener to be removed.

addListener

public void addListener(Upload.SucceededListener listener)

Adds the upload success event listener.

Parameters:
listener - the Listener to be added.

removeListener

public void removeListener(Upload.SucceededListener listener)

Removes the upload success event listener.

Parameters:
listener - the Listener to be removed.

addListener

public void addListener(Upload.ProgressListener listener)

Adds the upload success event listener.

Parameters:
listener - the Listener to be added.

removeListener

public void removeListener(Upload.ProgressListener listener)

Removes the upload success 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.

focus

public void focus()

Sets the focus for this component if the component is Focusable.

Specified by:
focus in interface Component.Focusable
Overrides:
focus in class AbstractComponent

See Also:
FieldEvents, FieldEvents.FocusEvent, FieldEvents.FocusListener, FieldEvents.BlurEvent, FieldEvents.BlurListener

getTabIndex

public int getTabIndex()

Gets the Tabulator index of this Focusable component.

Specified by:
getTabIndex in interface Component.Focusable

Returns:
tab index set for the Focusable component
See Also:
Component.Focusable.getTabIndex()

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 tread 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

setProgressListener

@Deprecated
public void setProgressListener(Upload.ProgressListener progressListener)

Deprecated. Use addListener(ProgressListener) instead.

This method is deprecated, use addListener(ProgressListener) instead.

Parameters:
progressListener -

getProgressListener

@Deprecated
public Upload.ProgressListener getProgressListener()

Deprecated. Replaced with addListener/removeListener

This method is deprecated.

Returns:
listener

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()

Forces the upload the send selected file to the server.

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

Note, that the upload runs asynchronous. Developer should use normal upload listeners to trac the process of upload. If the field is empty uploaded the file name will be empty string and file length 0 in the upload finished event.

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

requestRepaint

public void requestRepaint()

Description copied from interface: Paintable

Requests that the paintable should be repainted as soon as possible.

Specified by:
requestRepaint in interface Paintable
Overrides:
requestRepaint in class AbstractComponent

getStreamVariable

protected StreamVariable getStreamVariable()

getListeners

public Collection<?> getListeners(Class<?> eventType)

Description copied from class: AbstractComponent

Returns all listeners that are registered for the given event type or one of its subclasses.

Overrides:
getListeners in class AbstractComponent

Parameters:
eventType - The type of event to return listeners for.
Returns:
A collection with all registered listeners. Empty if no listeners are found.