| |||||||
FRAMES NO FRAMES |
Use the webuijsf: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.
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.
In order for the webuijsf:upload
tag to work, you must
configure the web application to use the
com.sun.webui.jsf.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.webui.jsf.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 and woodstock implemented subclasses. The UploadFilterDiskFileUpload class can be configured, as needed, by specifying UploadFilter init parameters. The following parameters are available:
maxSize
The maximum allowed upload size in bytes.
If negative, there is no maximum. The default value is 1MBsizeThreshold
The 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". UploadedFile
model objectThe contents of the uploaded file, together with some information
about it are stored in an instance of
com.sun.webui.jsf.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 of the resources associated with the file upload (this will happen automatically when the resource is garbage collected). |
java.lang.String |
Use this method to retrieve the contents of the file as a String |
byte[] |
Use this method to retrieve the contents of the file as an array of bytes. |
java.lang.String |
Get the content-type that the browser communicated with the request that included the uploaded file. |
java.io.InputStream |
Returns a InputStream for reading the file. |
java.lang.String |
Use this method to retrieve the name that the file has on the web application user's local system. |
long |
The size of the file in bytes |
void |
Write the contents of the uploaded file to a file on the server host. |
webuijsf:upload
tagTo access the contents of the uploaded file from the
webuijsf:upload
tag you have two
options:
uploadedFile
attribute to managed bean
property of type com.sun.webui.jsf.model.UploadedFile
.
Have the setter or an action method process the file.To optionally specify a label for the component, use the
label
attribute, or specify a label facet.
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. |
On the form that controls the upload:
<webuijsf:upload id="upload2" uploadedFile = "#{FileUploadBean.uploadedFile}" label="Choose a file: " required="true"/>
On the page that displays the results of the upload:
<webuijsf:staticText id="text" text ="File contents are bound to string: " > <webuijsf:staticText id="text" text ="#{FileUploadBean.stringContent}"/>
The managed bean looks like this:
import java.io.Serializable; import com.sun.webui.jsf.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; } }
On the form that controls the upload:
<webuijsf: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.webui.jsf.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 } } } }
Tag Information | |
Tag Class | com.sun.webui.jsf.component.UploadTag |
TagExtraInfo Class | None |
Body Content | JSP |
Display Name | None |
Attributes | ||||
Name | Required | Request-time | Type | Description |
binding | false | false | java.lang.String | A ValueExpression that resolves to the UIComponent that corresponds to this tag. This binding allows the Java bean that contains the UIComponent to manipulate the UIComponent, its properties, and its children. |
maxLength | false | false | java.lang.String | The maximum number of characters that can be entered for this field. |
uploadedFile | false | false | java.lang.String | The value of this attribute must be a JSF EL expression, and
it must resolve to an object of type
|
converter | false | false | java.lang.String | The converter attribute is used to specify a method to translate native
property values to String and back for this component. The converter
attribute value must be one of the following:
|
required | false | false | java.lang.String | Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error. |
columns | false | false | java.lang.String | Number of character character columns used to render this field. The default is 40. |
preservePath | false | false | java.lang.String | If preservePath is true the upload
component will preserve the literal value of the file input element
as set by the user on the client.
Different browsers handle the value of an HTML input element
of type "file" differently. Some browsers submit the literal value
of the input element in the multipart/form-data file portion
of the request, others only submit the file name portion and not
the directory portion. If this property is set to true, the
literal value (typically the full path name either entered explicitly
by the user, or from a file selection dialogue) will be stored and
submitted in a hidden field. The UploadRenderer will
preserve the full file path in the corresponding
|
onDblClick | false | false | java.lang.String | Scripting code executed when a mouse double click occurs over this component. |
onKeyPress | false | false | java.lang.String | Scripting code executed when the user presses and releases a key while the component has focus. |
onSelect | false | false | java.lang.String | Scripting code executed when some text in this component value is selected. |
onFocus | false | false | java.lang.String | Scripting code executed when this component receives focus. An element receives focus when the user selects the element by pressing the tab key or clicking the mouse. |
rendered | false | false | java.lang.String | Indicates whether the HTML code for the component should be included in the rendered HTML page. If set to false, the rendered HTML page does not include the HTML for the component. If the component is not rendered, it is also not processed on any subsequent form submission. |
id | false | true | java.lang.String | No Description |
onKeyUp | false | false | java.lang.String | Scripting code executed when the user releases a key while the component has focus. |
onMouseUp | false | false | java.lang.String | Scripting code executed when the user releases a mouse button while the mouse pointer is on the component. |
styleClass | false | false | java.lang.String | CSS style class(es) to be applied to the outermost HTML element when this component is rendered. |
style | false | false | java.lang.String | CSS style(s) to be applied to the outermost HTML element when this component is rendered. |
onClick | false | false | java.lang.String | Scripting code executed when a mouse click occurs over this component. |
onBlur | false | false | java.lang.String | Scripting code executed when this element loses focus. |
toolTip | false | false | java.lang.String | Sets the value of the title attribute for the HTML element. The specified text will display as a tooltip if the mouse cursor hovers over the HTML element. |
onMouseDown | false | false | java.lang.String | Scripting code executed when the user presses a mouse button while the mouse pointer is on the component. |
disabled | false | false | java.lang.String | Flag indicating that the user is not permitted to activate this component, and that the component's value will not be submitted with the form. |
validatorExpression | false | false | java.lang.String | Used to specify a method in a backing bean to validate input
to the component. The value must be a JavaServer Faces
EL expression that resolves to a public method with
return type void. The method must take three parameters:
The backing bean where the method is defined must implement
The method is invoked during the Process Validations Phase. |
onMouseOut | false | false | java.lang.String | Scripting code executed when a mouse out movement occurs over this component. |
onMouseOver | false | false | java.lang.String | Scripting code executed when the user moves the mouse pointer into the boundary of this component. |
onMouseMove | false | false | java.lang.String | Scripting code executed when the user moves the mouse pointer while over the component. |
htmlTemplate | false | false | java.lang.String | Alternative HTML template to be used by this component. |
immediate | false | false | java.lang.String | Flag indicating that event handling for this component should be handled immediately (in Apply Request Values phase) rather than waiting until Invoke Application phase. |
label | false | false | java.lang.String | If set, a label is rendered adjacent to the component with the value of this attribute as the label text. |
onChange | false | false | java.lang.String | Scripting code executed when the element value of this component is changed. |
visible | false | false | java.lang.String | Use the visible attribute to indicate whether the component should be viewable by the user in the rendered HTML page. |
onKeyDown | false | false | java.lang.String | Scripting code executed when the user presses down on a key while the component has focus. |
labelLevel | false | false | java.lang.String | Sets the style level for the generated label, provided the label attribute has been set. Valid values are 1 (largest), 2 and 3 (smallest). The default value is 2. |
readOnly | false | false | java.lang.String | Flag indicating that modification of this component by the user is not currently permitted, but that it will be included when the form is submitted. |
valueChangeListenerExpression | false | false | java.lang.String | Specifies a method to handle a value-change event that is triggered
when the user enters data in the input component. The
attribute value must be a JavaServer Faces EL expression that
resolves to a backing bean method. The method must take a single
parameter of type javax.faces.event.ValueChangeEvent ,
and its return type must be void. The backing bean where the
method is defined must implement java.io.Serializable
or javax.faces.component.StateHolder .
|
tabIndex | false | false | java.lang.String | Position of this element in the tabbing order of the current document. Tabbing order determines the sequence in which elements receive focus when the tab key is pressed. The value must be an integer between 0 and 32767. |
Variables | No Variables Defined. |
| |||||||
FRAMES NO FRAMES |