Columns in FOP Page # Block 0: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. XML has associated with it a great number of other standards, most of them under W3C (World-Wide Web Consortium) auspices. Among these are XML Namespaces, XML Pointer, XPath, XSLT, XHTML, SVG, RELAX, SOAP, and any number of others. This file has been prepared using formatting objects, an XML vocabulary described in the XSL specification of October 18, 2000. Formatting objects are used to specify pagination and composition, and are intended for high-quality, precision layout-driven formatting. Block 1: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. XML has associated with it a great number of other standards, most of them under W3C (World-Wide Web Consortium) auspices. Among these are XML Namespaces, XML Pointer, XPath, XSLT, XHTML, SVG, RELAX, SOAP, and any number of others. This file has been prepared using formatting objects, an XML vocabulary described in the XSL specification of October 18, 2000. Formatting objects are used to specify pagination and composition, and are intended for high-quality, precision layout-driven formatting. Block 2: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. Block 3: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. Block 4: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. Block 5: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. Block 6: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. XML has associated with it a great number of other standards, most of them under W3C (World-Wide Web Consortium) auspices. Among these are XML Namespaces, XML Pointer, XPath, XSLT, XHTML, SVG, RELAX, SOAP, and any number of others. This file has been prepared using formatting objects, an XML vocabulary described in the XSL specification of October 18, 2000. Formatting objects are used to specify pagination and composition, and are intended for high-quality, precision layout-driven formatting. Block 7: The Extensible Markup Language (XML) is a subset of SGML that is completely described in this document. Its goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. For further information read normal.pdf. XML has associated with it a great number of other standards, most of them under W3C (World-Wide Web Consortium) auspices. Among these are XML Namespaces, XML Pointer, XPath, XSLT, XHTML, SVG, RELAX, SOAP, and any number of others. This file has been prepared using formatting objects, an XML vocabulary described in the XSL specification of October 18, 2000. Formatting objects are used to specify pagination and composition, and are intended for high-quality, precision layout-driven formatting. 16' href='#n16'>16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
---
title: Upload
order: 27
layout: page
---

[[components.upload]]
= Upload

ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/other/upload"]
endif::web[]

The [classname]#Upload# component allows a user to upload files to the server.
It has two different modes controlled with [methodname]#setImmediateMode(boolean)#, that affect the user workflow.

[parameter]#Immediate# (default):: In the immediate mode, the upload displays a file name entry box and a button for selecting the file. The uploading is started immediately after the file has been selected.

[parameter]#Non-immediate#:: In the non-immediate mode, the upload displays a file name
entry box, a button for selecting the file and a button for starting the upload.
After the file is selected, the user starts the upload by clicking the submit button.

Uploading requires a receiver that implements [interfacename]#Upload.Receiver#
to provide an output stream to which the upload is written by the server.

[source, java]
----
Upload upload = new Upload("Upload it here", receiver);
upload.setImmediateMode(false);
----

[[figure.ui.upload]]
.The [classname]#Upload# component in non-immediate mode
image::img/upload.png[width=60%, scaledwidth=80%]

In the image above, the upload is in non-immediate mode. By default in the immediate mode,
only the [guilabel]#Start Upload# button is visible.

You can set the text of the upload button with [methodname]#setButtonCaption()#.
Note that it is difficult to change the caption or look of the
[guibutton]#Browse# button. This is a security feature of web browsers. The
language of the [guibutton]#Browse# button is determined by the browser, so if
you wish to have the language of the [classname]#Upload# component consistent,
you will have to use the same language in your application.

[source, java]
----
upload.setButtonCaption("Upload Now");
----

You can also hide the upload button with [literal]#++.v-upload .v-button
{display: none}++# in theme, have custom logic for starting the upload, and call
[methodname]#startUpload()# to start it.

[[components.upload.receiving]]
== Receiving Upload Data

The uploaded files are typically stored as files in a file system, in a
database, or as temporary objects in memory. The upload component writes the
received data to an [classname]#java.io.OutputStream# so you have plenty of
freedom in how you can process the upload content.

To use the [classname]#Upload# component, you need to implement the
[classname]#Upload.Receiver# interface. The [methodname]#receiveUpload()# method
of the receiver is called when the user clicks the submit button. The method
must return an [classname]#OutputStream#. To do this, it typically creates a
file or a memory buffer to which the stream is written. The method gets the file
name and MIME type of the file, as reported by the browser.

While uploading, the upload progress can be monitored with an
[interfacename]#Upload.ProgressListener#. The [methodname]#updateProgress()#
method gets the number of read bytes and the content length as parameters. The
content length is reported by the browser, but the reported value is not
reliable, and can also be unknown, in which case the value is -1. It is
therefore recommended to follow the upload progress and check the allowed size
in a progress listener. Upload can be terminated by calling
[methodname]#interruptUpload()# on the upload component. You may want to use a
[classname]#ProgressBar# to visualize the progress, and in indeterminate mode if
the content length is not known.

When an upload is finished, successfully or unsuccessfully, the
[classname]#Upload# component will emit the [classname]#Upload.FinishedEvent#
event, which you can handle with an [classname]#Upload.FinishedListener# added
to the upload component. The event object will include the file name, MIME type,
and final length of the file. More specific [classname]#Upload.FailedEvent# and
[classname]#Upload.SucceededEvent# events will be called in the cases where the
upload failed or succeeded, respectively.

The following example uploads images to [filename]#/tmp/uploads# directory in
(UNIX) filesystem (the directory must exist or the upload fails). The component
displays the uploaded image in an [classname]#Image# component.

[source, java]
----
// Show uploaded file in this placeholder
final Image image = new Image("Uploaded Image");

// Implement both receiver that saves upload in a file and
// listener for successful upload
class ImageUploader implements Receiver, SucceededListener {
    public File file;

    public OutputStream receiveUpload(String filename,
                                      String mimeType) {
        // Create and return a file output stream
        ...
    }

    public void uploadSucceeded(SucceededEvent event) {
        // Show the uploaded file in the image viewer
        image.setSource(new FileResource(file));
    }
};
ImageUploader receiver = new ImageUploader();

// Create the upload with a caption and set receiver later
Upload upload = new Upload("Upload Image Here", receiver);
upload.addSucceededListener(receiver);
----


[[components.upload.css]]
== CSS Style Rules


[source, css]
----
.v-upload { }
  .gwt-FileUpload { }
  .v-button { }
    .v-button-wrap { }
      .v-button-caption { }
----

The [classname]#Upload# component has an overall [literal]#++v-upload++# style.
The upload button has the same structure and style as a regular
[classname]#Button# component.