/*
* Copyright 2000-2014 Vaadin Ltd.
- *
+ *
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
/**
* Component for uploading files from client to server.
- *
+ *
* <p>
* The visible component consists of a file name input box and a browse button
* and an upload submit button to start uploading.
- *
+ *
* <p>
* 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.
- *
+ *
* <p>
* You can get an event regarding starting (StartedEvent), progress
* (ProgressEvent), and finishing (FinishedEvent) of upload by implementing
* 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).
- *
+ *
* <p>
* 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().
- *
+ *
* <p>
* 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.
- *
+ *
* <p>
* 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.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
/**
* Creates a new instance of Upload.
- *
+ *
* The receiver must be set before performing an upload.
*/
public Upload() {
/**
* Invoked when the value of a variable has changed.
- *
+ *
* @see com.vaadin.ui.AbstractComponent#changeVariables(java.lang.Object,
* java.util.Map)
*/
/**
* Paints the content of this component.
- *
+ *
* @param target
* Target to paint the content on.
* @throws PaintException
/**
* Interface that must be implemented by the upload receivers to provide the
* Upload component an output stream to write the uploaded data.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
/**
* Invoked when a new upload arrives.
- *
+ *
* @param filename
* the desired filename of the upload, usually as specified
* by the client.
* of whether the reception was successful or failed. If you wish to
* distinguish between the two cases, use either SucceededEvent or
* FailedEvent, which are both subclasses of the FinishedEvent.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
private final String filename;
/**
- *
+ *
* @param source
* the source of the file.
* @param filename
/**
* Uploads where the event occurred.
- *
+ *
* @return the Source of the event.
*/
public Upload getUpload() {
/**
* Gets the file name.
- *
+ *
* @return the filename.
*/
public String getFilename() {
/**
* Gets the MIME Type of the file.
- *
+ *
* @return the MIME type.
*/
public String getMIMEType() {
/**
* Gets the length of the file.
- *
+ *
* @return the length.
*/
public long getLength() {
/**
* Upload.FailedEvent event is sent when the upload is received, but the
* reception is interrupted for some reason.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
private Exception reason = null;
/**
- *
+ *
* @param source
* @param filename
* @param MIMEType
}
/**
- *
+ *
* @param source
* @param filename
* @param MIMEType
/**
* Gets the exception that caused the failure.
- *
+ *
* @return the exception that caused the failure, null if n/a
*/
public Exception getReason() {
public static class NoOutputStreamEvent extends FailedEvent {
/**
- *
+ *
* @param source
* @param filename
* @param MIMEType
public static class NoInputStreamEvent extends FailedEvent {
/**
- *
+ *
* @param source
* @param filename
* @param MIMEType
/**
* Upload.SucceededEvent event is sent when the upload is received
* successfully.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
public static class SucceededEvent extends FinishedEvent {
/**
- *
+ *
* @param source
* @param filename
* @param MIMEType
/**
* Upload.StartedEvent event is sent when the upload is started to received.
- *
+ *
* @author Vaadin Ltd.
* @since 5.0
*/
private final long length;
/**
- *
+ *
* @param source
* @param filename
* @param MIMEType
/**
* Uploads where the event occurred.
- *
+ *
* @return the Source of the event.
*/
public Upload getUpload() {
/**
* Gets the file name.
- *
+ *
* @return the filename.
*/
public String getFilename() {
/**
* Gets the MIME Type of the file.
- *
+ *
* @return the MIME type.
*/
public String getMIMEType() {
/**
* Upload.ChangeEvent event is sent when the value (filename) of the upload
* changes.
- *
+ *
* @since 7.2
*/
public static class ChangeEvent extends Component.Event {
/**
* Uploads where the event occurred.
- *
+ *
* @return the Source of the event.
*/
@Override
/**
* Gets the file name.
- *
+ *
* @return the filename.
*/
public String getFilename() {
/**
* Receives the events when the upload starts.
- *
+ *
* @author Vaadin Ltd.
* @since 5.0
*/
/**
* Upload has started.
- *
+ *
* @param event
* the Upload started event.
*/
/**
* Receives the events when the uploads are ready.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
/**
* Upload has finished.
- *
+ *
* @param event
* the Upload finished event.
*/
/**
* Receives events when the uploads are finished, but unsuccessful.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
/**
* Upload has finished unsuccessfully.
- *
+ *
* @param event
* the Upload failed event.
*/
/**
* Receives events when the uploads are successfully finished.
- *
+ *
* @author Vaadin Ltd.
* @since 3.0
*/
/**
* Upload successfull..
- *
+ *
* @param event
* the Upload successfull event.
*/
/**
* Listener for {@link ChangeEvent}
- *
+ *
* @since 7.2
*/
public interface ChangeListener extends Serializable {
/**
* A file has been selected but upload has not yet started.
- *
+ *
* @param event
* the change event
*/
/**
* Adds the upload started event listener.
- *
+ *
* @param listener
* the Listener to be added.
*/
/**
* Removes the upload started event listener.
- *
+ *
* @param listener
* the Listener to be removed.
*/
/**
* Adds the upload received event listener.
- *
+ *
* @param listener
* the Listener to be added.
*/
/**
* Removes the upload received event listener.
- *
+ *
* @param listener
* the Listener to be removed.
*/
/**
* Adds the upload interrupted event listener.
- *
+ *
* @param listener
* the Listener to be added.
*/
/**
* Removes the upload interrupted event listener.
- *
+ *
* @param listener
* the Listener to be removed.
*/
/**
* Adds the upload success event listener.
- *
+ *
* @param listener
* the Listener to be added.
*/
/**
* Removes the upload success event listener.
- *
+ *
* @param listener
* the Listener to be removed.
*/
}
/**
- * Adds the upload success event listener.
- *
+ * Adds the upload progress event listener.
+ *
* @param listener
- * the Listener to be added.
+ * the progress listener to be added
*/
public void addProgressListener(ProgressListener listener) {
if (progressListeners == null) {
}
/**
- * Removes the upload success event listener.
- *
+ * Removes the upload progress event listener.
+ *
* @param listener
- * the Listener to be removed.
+ * the progress listener to be removed
*/
public void removeProgressListener(ProgressListener listener) {
if (progressListeners != null) {
/**
* Adds a filename change event listener
- *
+ *
* @param listener
* the Listener to add
*/
/**
* Removes a filename change event listener
- *
+ *
* @param listener
* the listener to be removed
*/
/**
* Emit upload received event.
- *
+ *
* @param filename
* @param MIMEType
* @param length
/**
* Emits the upload failed event.
- *
+ *
* @param filename
* @param MIMEType
* @param length
/**
* Emits the upload success event.
- *
+ *
* @param filename
* @param MIMEType
* @param length
- *
+ *
*/
protected void fireUploadSuccess(String filename, String MIMEType,
long length) {
/**
* Emits the progress event.
- *
+ *
* @param totalBytes
* bytes received so far
* @param contentLength
* actual size of the file being uploaded, if known
- *
+ *
*/
protected void fireUpdateProgress(long totalBytes, long contentLength) {
// this is implemented differently than other listeners to maintain
/**
* Returns the current receiver.
- *
+ *
* @return the StreamVariable.
*/
public Receiver getReceiver() {
/**
* Sets the receiver.
- *
+ *
* @param receiver
* the receiver to set.
*/
/**
* Gets the Tabulator index of this Focusable component.
- *
+ *
* @see com.vaadin.ui.Component.Focusable#getTabIndex()
*/
@Override
/**
* Sets the Tabulator index of this Focusable component.
- *
+ *
* @see com.vaadin.ui.Component.Focusable#setTabIndex(int)
*/
@Override
/**
* 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
/**
* Go into state where new uploading can begin.
- *
+ *
* Warning: this is an internal method used by the framework and should not
* be used by user of the Upload component.
*/
/**
* Gets read bytes of the file currently being uploaded.
- *
+ *
* @return bytes
*/
public long getBytesRead() {
/**
* Returns size of file currently being uploaded. Value sane only during
* upload.
- *
+ *
* @return size in bytes
*/
public long getUploadSize() {
public interface ProgressListener extends Serializable {
/**
* Updates progress to listener
- *
+ *
* @param readBytes
* bytes transferred
* @param contentLength
* {@link #setImmediate(boolean)}, the file choose (html input with type
* "file") is hidden and only the button with this text is shown.
* <p>
- *
+ *
* <p>
* <strong>Note</strong> 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.
- *
+ *
* @param buttonCaption
* text for upload components button.
*/
projects / vaadin-framework.git / commitdiff