com.sun.webui.jsf.component
Class Upload

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.webui.jsf.component.WebuiInput
                      extended by com.sun.webui.jsf.component.HiddenField
                          extended by com.sun.webui.jsf.component.Field
                              extended by com.sun.webui.jsf.component.Upload
All Implemented Interfaces:
com.sun.webui.jsf.component.ComplexComponent, java.io.Serializable, javax.faces.component.EditableValueHolder, javax.faces.component.NamingContainer, javax.faces.component.StateHolder, javax.faces.component.ValueHolder

public class Upload
extends Field
implements java.io.Serializable

The Upload component relies on the UploadFilter and other upload filter classes to upload the file from the client to the server.

The file is uploaded in the request by the presence of an HTML input element, rendered by the UploadRenderer.

There is a problem processing errors. If there are serious errors where the form-data cannot be parsed from the multipart request, the JSF view state is also lost and only the RENDER phase executes. This leaves only the encode methods to catch and report any unexpected errors.

The UploadFilter places attributes in the requst map to indicate multipart/form-data request parsing failures. The following request attributes will exist if there are fatal parsing errors.

If any of these errors are seen FacesMessages are queued and any information available is logged.

If an exception occurred while processing the file uploaded in the request, like the maximum file size was exceeded or space for the temporary file could not be obtained, the UploadFilterFileItem instance mapped to the component id in the request map, will have the exceptions in its errorLog. Any exceptions found will be logged and a FacesMessage queued.

If a file is uploaded, there will always be a value change event for a successful upload. No attempt is made to determine if the previously uploaded file is the same as the current uploaded file.

See Also:
Serialized Form

Field Summary
static java.lang.String FILE_SIZE_KEY
          Deprecated.  
static java.lang.String INPUT_ID
          A suffix applied to the component id to form the id of the HTML input element.
static java.lang.String INPUT_PARAM_ID
          Deprecated.  
static java.lang.String LENGTH_EXCEEDED
          Deprecated.  
static java.lang.String PRESERVE_PATH_ID
          A suffix applied to the component id and used to identigy a hidden HTML input to preserve the full path entered by the user.
static java.lang.String SCRIPT_FACET
          Deprecated.  
static java.lang.String SCRIPT_ID
          Deprecated.  
static java.lang.String TEXT_ID
          Deprecated.  
static java.lang.String UPLOAD_ERROR_KEY
          An attribute with this name is placed in the request map with a value of an Exception instance that was thrown by the org.apache.commons.fileupload package when the multipart/form-data request cannot be parsed.
static java.lang.String UPLOAD_NO_DATA_KEY
          An attribute with this name is placed in the request map, with a value that is the same as the attribute name, when the org.apache.commons.fileupload package cannot parse the multipart/form-data request and an empty FileItem list is returned.
 
Fields inherited from class com.sun.webui.jsf.component.Field
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 interface javax.faces.component.NamingContainer
SEPARATOR_CHAR
 
Constructor Summary
Upload()
          Default constructor.
 
Method Summary
 int getColumns()
          Return the character width of the field.
 java.lang.Object getConvertedValue(javax.faces.context.FacesContext context, java.lang.Object value)
          Converts the submitted value.
 javax.faces.convert.Converter getConverter()
          The converter attribute is used to specify a method to translate native property values to String and back for this component.
 java.lang.String getFamily()
          Return the family for this component.
 java.lang.String getFocusElementId(javax.faces.context.FacesContext context)
          Returns the id of an HTML element suitable to receive the focus.
 java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
          Returns the ID of an HTML element suitable to use as the value of an HTML LABEL element's for attribute.
 int getMaxLength()
          The maximum number of characters that can be entered for this field.
 java.lang.String getPrimaryElementID(javax.faces.context.FacesContext context)
          Deprecated.  
 java.lang.String getReadOnlyValueString(javax.faces.context.FacesContext context)
          Return the value to be rendered as a string when the component is readOnly.
 java.lang.Object getText()
          Literal value to be rendered in this input field.
 java.lang.String getType()
          Overrides getType in the FileInput class, to always return "file"
 UploadedFile getUploadedFile()
          The value of this attribute must be a JSF EL expression, and it must resolve to an object of type com.sun.webui.jsf.model.UploadedFile.
 java.lang.String getValueAsString(javax.faces.context.FacesContext context)
          Return the value to be rendered when the component is rendered as a String.
 javax.el.ValueExpression getValueExpression(java.lang.String name)
          Return the ValueExpression stored for the specified name (if any), respecting any property aliases.
 boolean isPreservePath()
          Return true if the upload component has been configured to preserve the literal file path as entered on the client, else false, meaning that the upload component will not preserve the the full path as entered by the user on the client.
 boolean isTrim()
          Flag indicating that any leading and trailing blanks will be trimmed prior to conversion to the destination data type.
 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 character columns used to render this field.
 void setPreservePath(boolean preservePath)
          If preservePath is true the upload component will save the file input element value in a hidden field and submit it in the request, else if false the value will not be preserved.
 void setRequired(boolean required)
          Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.
 void setText(java.lang.Object text)
          This method overrides setText() in 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.webui.jsf.model.UploadedFile.
 void setValueExpression(java.lang.String name, javax.el.ValueExpression binding)
          Set the ValueExpression stored for the specified name (if any), respecting any property aliases.
 
Methods inherited from class com.sun.webui.jsf.component.Field
getIndicatorComponent, getLabel, getLabelComponent, getLabelLevel, getOnBlur, getOnChange, getOnClick, getOnDblClick, getOnFocus, getOnKeyDown, getOnKeyPress, getOnKeyUp, getOnMouseDown, getOnMouseMove, getOnMouseOut, getOnMouseOver, getOnMouseUp, getOnSelect, getReadOnlyComponent, getStyle, getStyleClass, getTabIndex, getToolTip, getValue, isDisabled, isReadOnly, isRequired, 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.webui.jsf.component.HiddenField
getHtmlTemplate, getRendererType, setHtmlTemplate
 
Methods inherited from class com.sun.webui.jsf.component.WebuiInput
broadcast, getValidator, getValidatorExpression, getValueChangeListener, getValueChangeListenerExpression, processDecodes, processUpdates, processValidators, setConverter, setId, setImmediate, setRendered, setValidatorExpression, setValueChangeListenerExpression
 
Methods inherited from class javax.faces.component.UIInput
addValidator, addValueChangeListener, decode, getConverterMessage, getRequiredMessage, getSubmittedValue, getValidatorMessage, getValidators, getValueChangeListeners, isImmediate, isLocalValueSet, isValid, removeValidator, removeValueChangeListener, resetValue, setConverterMessage, setLocalValueSet, setRequiredMessage, setSubmittedValue, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, updateModel, validate
 
Methods inherited from class javax.faces.component.UIOutput
getLocalValue
 
Methods inherited from class javax.faces.component.UIComponentBase
encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, restoreAttachedState, saveAttachedState, setParent, setRendererType, setTransient, setValueBinding
 
Methods inherited from class javax.faces.component.UIComponent
encodeAll, getContainerClientId
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.faces.component.ValueHolder
getLocalValue
 

Field Detail

INPUT_ID

public static final java.lang.String INPUT_ID
A suffix applied to the component id to form the id of the HTML input element.

See Also:
Constant Field Values

PRESERVE_PATH_ID

public static final java.lang.String PRESERVE_PATH_ID
A suffix applied to the component id and used to identigy a hidden HTML input to preserve the full path entered by the user.

See Also:
Constant Field Values

INPUT_PARAM_ID

public static final java.lang.String INPUT_PARAM_ID
Deprecated. 
A suffix applied to the component id to form the id of a hidden HTML input element used to store the component's client id. This is needed when the label attribute has no value.

See Also:
Constant Field Values

SCRIPT_ID

public static final java.lang.String SCRIPT_ID
Deprecated. 
See Also:
Constant Field Values

SCRIPT_FACET

public static final java.lang.String SCRIPT_FACET
Deprecated. 
See Also:
Constant Field Values

TEXT_ID

public static final java.lang.String TEXT_ID
Deprecated. 
See Also:
Constant Field Values

LENGTH_EXCEEDED

public static final java.lang.String LENGTH_EXCEEDED
Deprecated. 
See Also:
Constant Field Values

FILE_SIZE_KEY

public static final java.lang.String FILE_SIZE_KEY
Deprecated. 
See Also:
Constant Field Values

UPLOAD_NO_DATA_KEY

public static final java.lang.String UPLOAD_NO_DATA_KEY
An attribute with this name is placed in the request map, with a value that is the same as the attribute name, when the org.apache.commons.fileupload package cannot parse the multipart/form-data request and an empty FileItem list is returned.

See Also:
Constant Field Values

UPLOAD_ERROR_KEY

public static final java.lang.String UPLOAD_ERROR_KEY
An attribute with this name is placed in the request map with a value of an Exception instance that was thrown by the org.apache.commons.fileupload package when the multipart/form-data request cannot be parsed.

See Also:
Constant Field Values
Constructor Detail

Upload

public Upload()
Default constructor.

Method Detail

getFamily

public java.lang.String getFamily()

Return the family for this component.

Overrides:
getFamily in class Field

getConvertedValue

public java.lang.Object getConvertedValue(javax.faces.context.FacesContext context,
                                          java.lang.Object value)

Converts the submitted value. Returns an object of type UploadedFile.

Parameters:
context - The FacesContext
value - An object representing the submitted value
Returns:
An Object representation of the value (a java.lang.String or a java.io.File, depending on how the component is configured

getValueAsString

public java.lang.String getValueAsString(javax.faces.context.FacesContext context)

Return the value to be rendered when the component is rendered as a String. For the FileUpload, we never render the file name in the textfield, so we return null.

Overrides:
getValueAsString in class HiddenField
Parameters:
context - FacesContext for the current request
Returns:
A String value of the component

getReadOnlyValueString

public java.lang.String getReadOnlyValueString(javax.faces.context.FacesContext context)

Return the value to be rendered as a string when the component is readOnly. This method overrides the default behaviour by returning a String "No file uploaded" if getValueAsString() returns null.

Overrides:
getReadOnlyValueString in class HiddenField
Parameters:
context - FacesContext for the current request
Returns:
A String value of the component

getType

public java.lang.String getType()
Overrides getType in the FileInput class, to always return "file"

Returns:
"file"

setText

public void setText(java.lang.Object text)
This method overrides setText() in Field. It is a noop.

Overrides:
setText in class Field
See Also:
Field.getText()

getColumns

public int getColumns()
Return the character width of the field. The default width is 40. If the assigned value is less than 1, 40 is returned.

Overrides:
getColumns in class Field

getPrimaryElementID

public java.lang.String getPrimaryElementID(javax.faces.context.FacesContext context)
Deprecated. 

Retrieves the DOM ID for the HTML input element. To be used by Label component as a value for the "for" attribute.

Specified by:
getPrimaryElementID in interface com.sun.webui.jsf.component.ComplexComponent
Overrides:
getPrimaryElementID in class Field
Parameters:
context - The FacesContext for the request
Returns:
The client id, also the JavaScript element id
See Also:
getLabeledElementId(javax.faces.context.FacesContext)

getLabeledElementId

public java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
Returns the ID of an HTML element suitable to use as the value of an HTML LABEL element's for attribute.

Specified by:
getLabeledElementId in interface com.sun.webui.jsf.component.ComplexComponent
Overrides:
getLabeledElementId in class Field
Parameters:
context - The FacesContext used for the request
Returns:
The id of the HTML element

getFocusElementId

public java.lang.String getFocusElementId(javax.faces.context.FacesContext context)
Returns the id of an HTML element suitable to receive the focus.

Specified by:
getFocusElementId in interface com.sun.webui.jsf.component.ComplexComponent
Overrides:
getFocusElementId in class Field
Parameters:
context - The FacesContext used for the request

setRequired

public void setRequired(boolean required)
Flag indicating that an input value for this field is mandatory, and failure to provide one will trigger a validation error.

Specified by:
setRequired in interface javax.faces.component.EditableValueHolder
Overrides:
setRequired in class WebuiInput

getValueExpression

public javax.el.ValueExpression getValueExpression(java.lang.String name)

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

Overrides:
getValueExpression in class Field
Parameters:
name - Name of value binding expression to retrieve

setValueExpression

public void setValueExpression(java.lang.String name,
                               javax.el.ValueExpression binding)

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

Overrides:
setValueExpression in class Field
Parameters:
name - Name of value binding to set
binding - ValueExpression to set, or null to remove

getConverter

public javax.faces.convert.Converter getConverter()
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:

getMaxLength

public int getMaxLength()
The maximum number of characters that can be entered for this field.

Overrides:
getMaxLength in class Field

isTrim

public boolean isTrim()
Description copied from class: Field

Flag indicating that any leading and trailing blanks will be trimmed prior to conversion to the destination data type. Default value is true.

Overrides:
isTrim in class Field

getText

public java.lang.Object getText()
Description copied from class: Field

Literal value to be rendered in this input field. If this property is specified by a value binding expression, the corresponding value will be updated if validation succeeds.

Overrides:
getText in class Field

setColumns

public void setColumns(int columns)

Number of character character columns used to render this field. The default is 40.

Overrides:
setColumns in class Field
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.webui.jsf.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.webui.jsf.model.UploadedFile. See the JavaDoc for this class for details.

See Also:
getUploadedFile()

isPreservePath

public boolean isPreservePath()
Return true if the upload component has been configured to preserve the literal file path as entered on the client, else false, meaning that the upload component will not preserve the the full path as entered 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 UploadFilterFileItem instance, encapsulated by the UploadedFile instance.

See Also:

It is not clear if it is a security risk to transmit the full file path in clear text to the server.
The default value is false.


setPreservePath

public void setPreservePath(boolean preservePath)
If preservePath is true the upload component will save the file input element value in a hidden field and submit it in the request, else if false the value will not be preserved.

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 UploadFilterFileItem instance, encapsulated by the UploadedFile instance.

See Also:

It is not clear if it is a security risk to transmit the full file path in clear text to the server.


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 Field

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 Field


Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.