| Use the ui:upload tag to create a component that can be used to
browse the local file system for a file, and upload a copy of the
file's contents to the web application.
HTML Elements and Layout
The Upload component produces an XHTML <input type="file">
element, which displays a text input field with an adjacent Browse button.
The user can type a file name or click the Browse button to select
a file. When the form is submitted, the file is uploaded. Note
that this tag requires the use of a filter.
Configuring the UploadFilter
In order for the ui:upload tag to work, you must
configure the web application to use the
com.sun.rave.web.ui.util.UploadFilter.
Configure the filter by declaring a filter element in the web application's
deployment descriptor, web.xml.
<filter>
<filter-name>UploadFilter</filter-name>
<filter-class>com.sun.rave.web.ui.util.UploadFilter</filter-class>
</filter>
Map the filter to the FacesServlet by adding the following filter
mapping in the same file, for example
<filter-mapping>
<filter-name>UploadFilter</filter-name>
<servlet-name>FacesServlet</servlet-name>
</filter-mapping>
The UploadFilter uses the Apache commons fileupload package. You
can optionally configure the parameters of the DiskFileUpload
class by specifying init parameters on the UploadFilter. The
following parameters are available:
maxSize The maximum allowed upload size in bytes.
If negative, there is no maximum. The default value is 1,000,000.sizeThresholdThe implementation of the uploading
functionality uses temporary storage of the file contents before the
Upload component stores them per its configuration. In the temporary
storage, smaller files are stored in memory while larger files are
written directly to disk . Use this parameter
to specify an integer value of the cut-off where files should be
written to disk. The default value is 4096 bytes.tmpDir Use this directory to specify the directory to
be used for temporary storage of files. The default behaviour is to use
the directory specified in the system property "java.io.tmpdir".
The UploadedFile model object
The contents of the uploaded file, together with some information
about it are stored in an instance of
com.sun.rave.web.ui.model.UploadedFile. Using this object you
can get the content of the file as a String or write the contents to
disk, as well as get properties such as the name and the size of the
file. In the interest of conserving memory, the contents and file data
are only available during the HTTP request in which the file was
uploaded.
|
UploadedFile Method Summary |
void |
dispose()
Dispose of the resources associated with the file upload (this will
happen automatically when the resource is garbage collected). |
java.lang.String |
getAsString()
Use this method to retrieve the contents of the file as a String |
byte[] |
getBytes()
Use this method to retrieve the contents of the file as an array of bytes. |
java.lang.String |
getContentType()
Get the content-type that the browser communicated with the request
that included the uploaded file. |
java.io.InputStream |
getInputStream()
Returns a InputStream for reading the file. |
java.lang.String |
getOriginalName()
Use this method to retrieve the name that the file has on the web
application user's local system. |
long |
getSize()
The size of the file in bytes |
void |
write(java.io.File file)
Write the contents of the uploaded file to a file on the server host. |
Configuring the ui:upload tag
To access the contents of the uploaded file from the
ui:upload tag you have two
options:
- Bind the
uploadedFile attribute to managed bean
property of type com.sun.rave.web.ui.model.UploadedFile.
Have the setter or an action method process the file.
- Specify a valueChangeListener on the Upload component.
The method invoked by the value change listener has access to the
new value of the component.
method.
To optionally specify a label for the component, use the
label attribute, or specify a label facet.
Client Side Javascript Functions
In all the functions below, <id> should be
the generated id of the Upload component.
field_setDisabled(<id>, <disabled>)
|
Enable/disable the field. Set <disabled>
to true to disable the component, or false to enable it.
|
field_setValue(<id>, <newValue>)
|
Set the value of the field to <newValue>.
|
field_getValue(<id>)
|
Get the value of the field. |
field_getInputElement(<id>) |
Get hold of a reference to the input element rendered by this
component.
|
component_setVisible(<id>)
|
Hide or show this component.
|
Examples
Get the contents of the file as a String (using a managed bean)
On the form that controls the upload:
<ui:upload id="upload2"
uploadedFile = "#{FileUploadBean.uploadedFile}"
label="Choose a file: "
required="true"/>
On the page that displays the results of the upload:
<ui:staticText id="text"
text ="File contents are bound to string: " >
<ui:staticText id="text"
text ="#{FileUploadBean.stringContent}"/>
The managed bean looks like this:
import java.io.Serializable;
import com.sun.rave.web.ui.model.UploadedFile;
public class FileUploadBean implements Serializable {
//
// Holds value of property uploadedFile.
//
transient private UploadedFile uploadedFile;
//
// Getter for property stringContent.
// @return Value of property stringContent.
//
public String getStringContent() {
return uploadedFile.getAsString();
}
//
// Getter for property uploadedFile.
// @return Value of property uploadedFile.
//
public UploadedFile getUploadedFile() {
return this.uploadedFile;
}
//
// Setter for property uploadedFile.
// @param uploadedFile New value of property uploadedFile.
//
public void setUploadedFile(UploadedFile uploadedFile) {
this.uploadedFile = uploadedFile;
}
}
Write the contents of the file to disk (using a ValueChangeListener)
On the form that controls the upload:
<ui:upload id="upload1"
label="Choose a file: "
valueChangeListener="#{FileUploadedListener.processValueChange}"/>
Code for the ValueChangeListener
import java.io.File;
import java.io.Serializable;
import javax.faces.event.AbortProcessingException;
import javax.faces.event.ValueChangeEvent;
import com.sun.rave.web.ui.model.UploadedFile;
public class FileUploadedListener implements ValueChangeListener, Serializable {
public void processValueChange(ValueChangeEvent event)
throws AbortProcessingException { Object value = event.getNewValue();
if(value != null && value instanceof UploadedFile) {
UploadedFile uploadedFile = (UploadedFile)value;
String name = uploadedFile.getOriginalName();
if(name == null || name.length() == 0) {
name = "tmp.tmp";
}
String suffix = name.substring(name.indexOf("."));
if(suffix.length() == 0) {
suffix = ".tmp";
}
String prefix = name.substring(0, name.indexOf("."));
try {
File tmpFile = File.createTempFile(prefix, suffix);
uploadedFile.write(tmpFile);
} catch(Exception ex) {
// report the problem
}
}
}
}
Auto-generated component class.
Do NOT modify; all changes
will be lost!
| 