com.vaadin.ui.
Class Upload
- java.lang.Object
-
- com.vaadin.server.AbstractClientConnector
-
- com.vaadin.ui.AbstractComponent
-
- com.vaadin.ui.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:
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Upload.ChangeEvent
Upload.ChangeEvent event is sent when the value (filename) of the upload changes.
static interface
Upload.ChangeListener
Listener for
Upload.ChangeEvent
.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 interface com.vaadin.server.ClientConnector
ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener
-
Nested classes/interfaces inherited from interface com.vaadin.ui.Component
Component.ErrorEvent, Component.Event, Component.Focusable, Component.Listener
-
Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable
Sizeable.Unit
-
-
Field Summary
-
Fields inherited from class com.vaadin.ui.AbstractComponent
DESIGN_ATTR_PLAIN_TEXT
-
Fields inherited from interface com.vaadin.server.Sizeable
SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS
-
-
Constructor Summary
Constructors Constructor Description Upload()
Creates a new instance of Upload.
Upload(String caption, Upload.Receiver uploadReceiver)
-
Method Summary
All Methods Modifier and Type Method Description Registration
addChangeListener(Upload.ChangeListener listener)
Adds a filename change event listener.
Registration
addFailedListener(Upload.FailedListener listener)
Adds the upload interrupted event listener.
Registration
addFinishedListener(Upload.FinishedListener listener)
Adds the upload received event listener.
Registration
addProgressListener(Upload.ProgressListener listener)
Adds the upload progress event listener.
Registration
addStartedListener(Upload.StartedListener listener)
Adds the upload started event listener.
Registration
addSucceededListener(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
Component.Focusable
.String
getAcceptMimeTypes()
Returns the component's list of accepted content-types.
String
getButtonCaption()
Returns the string rendered into button that fires uploading.
String
getButtonStyleName()
Returns the style name rendered into button that fires uploading.
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.Receiver
getReceiver()
Returns the current receiver.
protected UploadState
getState()
Returns the shared state bean with information to be sent from the server to the client.
protected UploadState
getState(boolean markAsDirty)
Returns the shared state for this connector.
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
isButtonCaptionAsHtml()
Checks whether the caption of the button that fires uploading is rendered as HTML
boolean
isImmediateMode()
Returns the immediate mode of the upload.
boolean
isUploading()
void
markAsDirty()
Marks that this connector's state might have changed.
void
paintContent(PaintTarget target)
Paints the content of this component.
void
removeChangeListener(Upload.ChangeListener listener)
Deprecated.
void
removeFailedListener(Upload.FailedListener listener)
Deprecated.
void
removeFinishedListener(Upload.FinishedListener listener)
Deprecated.
void
removeProgressListener(Upload.ProgressListener listener)
Deprecated.
void
removeStartedListener(Upload.StartedListener listener)
Deprecated.
void
removeSucceededListener(Upload.SucceededListener listener)
Deprecated.
void
setAcceptMimeTypes(String acceptMimeTypes)
Sets the component's list of accepted content-types.
void
setButtonCaption(String buttonCaption)
In addition to the actual file chooser, upload components have button that starts actual upload progress.
void
setButtonCaptionAsHtml(boolean buttonCaptionAsHtml)
In addition to the actual file chooser, upload components have button that starts actual upload progress.
void
setButtonStyleName(String buttonStyleName)
In addition to the actual file chooser, upload components have button that starts actual upload progress.
void
setImmediateMode(boolean immediateMode)
Sets the immediate mode of the upload.
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()
Instructs the upload component to send selected file to the server.
-
Methods inherited from class com.vaadin.ui.AbstractComponent
addContextClickListener, addListener, addShortcutListener, addStyleName, attach, beforeClientResponse, detach, findAncestor, fireComponentErrorEvent, fireComponentEvent, getActionManager, getCaption, getComponentError, getCustomAttributes, getData, getDebugId, getDescription, getErrorMessage, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isCaptionAsHtml, isConnectorEnabled, isEnabled, isOrHasAncestor, isReadOnly, isRequiredIndicatorVisible, isResponsive, isVisible, readDesign, removeContextClickListener, removeListener, removeShortcutListener, removeStyleName, setCaption, setCaptionAsHtml, setComponentError, setData, setDebugId, setDescription, setDescription, setEnabled, setHeight, setHeight, setHeightFull, setHeightUndefined, setIcon, setId, setLocale, setParent, setPrimaryStyleName, setReadOnly, setRequiredIndicatorVisible, setResponsive, setSizeFull, setSizeUndefined, setStyleName, setVisible, setWidth, setWidth, setWidthFull, setWidthUndefined, writeDesign
-
Methods inherited from class com.vaadin.server.AbstractClientConnector
addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, equals, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hashCode, hasListeners, isAttached, isThis, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource, updateDiffstate
-
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface com.vaadin.server.ClientConnector
addAttachListener, addDetachListener, beforeClientResponse, detach, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler
-
Methods inherited from interface com.vaadin.ui.Component
addListener, addStyleName, addStyleNames, attach, getCaption, getDescription, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getUI, isEnabled, isVisible, readDesign, removeListener, removeStyleName, removeStyleNames, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setStyleName, setStyleName, setVisible, writeDesign
-
Methods inherited from interface com.vaadin.shared.Connector
getConnectorId
-
Methods inherited from interface com.vaadin.server.Sizeable
getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeightFull, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull, setWidthUndefined
-
Methods inherited from interface com.vaadin.server.VariableOwner
isEnabled
-
-
-
-
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 interfaceVariableOwner
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:
VariableOwner.changeVariables(java.lang.Object, java.util.Map)
-
paintContent
public void paintContent(PaintTarget target) throws PaintException
Paints the content of this component.
Specified by:
paintContent
in interfaceLegacyComponent
Parameters:
target
- Target to paint the content on.Throws:
PaintException
- if the paint operation failed.
-
addStartedListener
public Registration addStartedListener(Upload.StartedListener listener)
Adds the upload started event listener.
Parameters:
listener
- the Listener to be added, not nullSince:
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 nullSince:
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 nullSince:
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 nullSince:
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 addedSince:
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 nullSince:
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
-
-
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 farcontentLength
- 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
Component.Focusable
.Specified by:
focus
in interfaceComponent.Focusable
Overrides:
focus
in classAbstractComponent
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 interfaceComponent.Focusable
Returns:
tab index set for the
Focusable
componentSee Also:
-
setTabIndex
public void setTabIndex(int tabIndex)
Sets the Tabulator index of this Focusable component.
Specified by:
setTabIndex
in interfaceComponent.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:
-
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 textSince:
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:
-
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 tofalse
, 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 textSince:
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.
-
markAsDirty
public void markAsDirty()
Description copied from interface:
ClientConnector
Marks that this connector's state might have changed. When the framework is about to send new data to the client-side, it will run
ClientConnector.beforeClientResponse(boolean)
followed byClientConnector.encodeState()
for all connectors that are marked as dirty and send any updated state info to the client.Specified by:
markAsDirty
in interfaceClientConnector
Specified by:
markAsDirty
in interfaceLegacyComponent
Overrides:
markAsDirty
in classAbstractClientConnector
See Also:
-
getStreamVariable
protected StreamVariable getStreamVariable()
-
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 classAbstractClientConnector
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 notSince:
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 modeSince:
8.0
See Also:
-
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 classAbstractComponent
Returns:
updated component shared state
-
getState
protected UploadState getState(boolean markAsDirty)
Description copied from class:
AbstractClientConnector
Returns the shared state for this connector.
Overrides:
getState
in classAbstractComponent
Parameters:
markAsDirty
- true if the connector should automatically be marked dirty, false otherwiseReturns:
The shared state for this connector. Never null.
See Also:
-
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
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/*
orimage/png,text/plain
Parameters:
acceptMimeTypes
- comma-separated list of desired mime types to be uploadedSince:
8.5
See Also:
-
-