com.sun.rave.web.ui.component
Class UploadBase

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
          extended by javax.faces.component.UIOutput
              extended by javax.faces.component.UIInput
                  extended by com.sun.rave.web.ui.component.HiddenFieldBase
                      extended by com.sun.rave.web.ui.component.HiddenField
                          extended by com.sun.rave.web.ui.component.FieldBase
                              extended by com.sun.rave.web.ui.component.Field
                                  extended by com.sun.rave.web.ui.component.UploadBase
All Implemented Interfaces:
ComplexComponent, javax.faces.component.EditableValueHolder, javax.faces.component.StateHolder, javax.faces.component.ValueHolder
Direct Known Subclasses:
Upload

public abstract class UploadBase
extends Field

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:

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:

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!


Field Summary
 
Fields inherited from class com.sun.rave.web.ui.component.Field
INPUT_ID, LABEL_FACET, LABEL_ID, READONLY_FACET, READONLY_ID
 
Fields inherited from class javax.faces.component.UIInput
COMPONENT_FAMILY, COMPONENT_TYPE, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID
 
Fields inherited from class javax.faces.component.UIComponent
bindings
 
Constructor Summary
UploadBase()
          Construct a new UploadBase.
 
Method Summary
 int getColumns()
          Number of character columns used to render this field.
 java.lang.String getFamily()
          Return the identifier of the component family to which this component belongs.
 UploadedFile getUploadedFile()
          The value of this attribute must be a JSF EL expression, and it must resolve to an object of type com.sun.rave.web.ui.model.UploadedFile.
 javax.faces.el.ValueBinding getValueBinding(java.lang.String name)
          Return the ValueBinding stored for the specified name (if any), respecting any property aliases.
 void restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state)
          Restore the state of this component.
 java.lang.Object saveState(javax.faces.context.FacesContext _context)
          Save the state of this component.
 void setColumns(int columns)
          Number of character columns used to render this field.
 void setUploadedFile(UploadedFile uploadedFile)
          The value of this attribute must be a JSF EL expression, and it must resolve to an object of type com.sun.rave.web.ui.model.UploadedFile.
 void setValueBinding(java.lang.String name, javax.faces.el.ValueBinding binding)
          Set the ValueBinding stored for the specified name (if any), respecting any property aliases.
 
Methods inherited from class com.sun.rave.web.ui.component.Field
getLabelComponent, getPrimaryElementID, getReadOnlyComponent, log, setText
 
Methods inherited from class com.sun.rave.web.ui.component.FieldBase
getLabel, getLabelLevel, getMaxLength, getOnBlur, getOnChange, getOnClick, getOnDblClick, getOnFocus, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getOnSelect, getStyle, getStyleClass, getTabIndex, getText, getToolTip, isDisabled, isReadOnly, isTrim, isVisible, setDisabled, setLabel, setLabelLevel, setMaxLength, setOnBlur, setOnChange, setOnClick, setOnDblClick, setOnFocus, setOnKeyDown, setOnKeyPress, setOnKeyUp, setOnMouseDown, setOnMouseMove, setOnMouseOut, setOnMouseOver, setOnMouseUp, setOnSelect, setReadOnly, setStyle, setStyleClass, setTabIndex, setToolTip, setTrim, setVisible
 
Methods inherited from class com.sun.rave.web.ui.component.HiddenField
getConvertedValue, getReadOnlyValueString, getValueAsString
 
Methods inherited from class javax.faces.component.UIInput
addValidator, addValueChangeListener, compareValues, decode, getConverterMessage, getRequiredMessage, getSubmittedValue, getValidator, getValidatorMessage, getValidators, getValueChangeListener, getValueChangeListeners, isImmediate, isLocalValueSet, isRequired, isValid, processDecodes, processUpdates, processValidators, removeValidator, removeValueChangeListener, resetValue, setConverterMessage, setImmediate, setLocalValueSet, setRequired, setRequiredMessage, setSubmittedValue, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, updateModel, validate, validateValue
 
Methods inherited from class javax.faces.component.UIOutput
getConverter, getLocalValue, getValue, setConverter
 
Methods inherited from class javax.faces.component.UIComponentBase
addFacesListener, broadcast, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient
 
Methods inherited from class javax.faces.component.UIComponent
encodeAll, getContainerClientId, getValueExpression, setValueExpression
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.faces.component.ValueHolder
getConverter, getLocalValue, getValue, setConverter
 

Constructor Detail

UploadBase

public UploadBase()

Construct a new UploadBase.

Method Detail

getFamily

public java.lang.String getFamily()

Return the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the rendererType property, may be used to select the appropriate Renderer for this component instance.

Overrides:
getFamily in class FieldBase

getValueBinding

public javax.faces.el.ValueBinding getValueBinding(java.lang.String name)

Return the ValueBinding stored for the specified name (if any), respecting any property aliases.

Overrides:
getValueBinding in class FieldBase
Parameters:
name - Name of value binding to retrieve

setValueBinding

public void setValueBinding(java.lang.String name,
                            javax.faces.el.ValueBinding binding)

Set the ValueBinding stored for the specified name (if any), respecting any property aliases.

Overrides:
setValueBinding in class FieldBase
Parameters:
name - Name of value binding to set
binding - ValueBinding to set, or null to remove

getColumns

public int getColumns()

Number of character columns used to render this field.

Overrides:
getColumns in class Field

setColumns

public void setColumns(int columns)

Number of character columns used to render this field.

Overrides:
setColumns in class FieldBase
See Also:
getColumns()

getUploadedFile

public UploadedFile getUploadedFile()

The value of this attribute must be a JSF EL expression, and it must resolve to an object of type com.sun.rave.web.ui.model.UploadedFile. See the JavaDoc for this class for details.


setUploadedFile

public void setUploadedFile(UploadedFile uploadedFile)

The value of this attribute must be a JSF EL expression, and it must resolve to an object of type com.sun.rave.web.ui.model.UploadedFile. See the JavaDoc for this class for details.

See Also:
getUploadedFile()

restoreState

public void restoreState(javax.faces.context.FacesContext _context,
                         java.lang.Object _state)

Restore the state of this component.

Specified by:
restoreState in interface javax.faces.component.StateHolder
Overrides:
restoreState in class FieldBase

saveState

public java.lang.Object saveState(javax.faces.context.FacesContext _context)

Save the state of this component.

Specified by:
saveState in interface javax.faces.component.StateHolder
Overrides:
saveState in class FieldBase