|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.faces.component.UIComponent
javax.faces.component.UIComponentBase
javax.faces.component.UIOutput
javax.faces.component.UIInput
com.sun.webui.jsf.component.WebuiInput
com.sun.webui.jsf.component.HiddenField
com.sun.webui.jsf.component.Field
com.sun.webui.jsf.component.Upload
public class Upload
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.
TheUploadFilter
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.
Upload.UPLOAD_ERROR_KEY
. When there is a request
attribute with this name, the value is an Exception
that
was thrown while parsing the multipart request. It typically results in the
form-data as well as the file data being lost. This means that the
JSF view state field is also lost and the request will be interpreted as
a first time visit to the page, i.e. only the RENDER phase will execute.
Upload.UPLOAD_NO_DATA_KEY
. When there is a request
attribute with this name, the value is the same as the name. It indicates
that no form or file data was parsed from the multipart document. Typically
this attribute will exist only when Upload.UPLOAD_ERROR_KEY
also exists, but may, in extremely unusual circumstances
like a malformed request, exist by itself.
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.
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 |
---|
public static final java.lang.String INPUT_ID
public static final java.lang.String PRESERVE_PATH_ID
public static final java.lang.String INPUT_PARAM_ID
public static final java.lang.String SCRIPT_ID
public static final java.lang.String SCRIPT_FACET
public static final java.lang.String TEXT_ID
public static final java.lang.String LENGTH_EXCEEDED
public static final java.lang.String FILE_SIZE_KEY
public static final java.lang.String UPLOAD_NO_DATA_KEY
org.apache.commons.fileupload
package cannot parse
the multipart/form-data request and an empty FileItem
list is returned.
public static final java.lang.String UPLOAD_ERROR_KEY
Exception
instance that was thrown by the
org.apache.commons.fileupload
package when
the multipart/form-data request cannot be parsed.
Constructor Detail |
---|
public Upload()
Method Detail |
---|
public java.lang.String getFamily()
Return the family for this component.
getFamily
in class Field
public java.lang.Object getConvertedValue(javax.faces.context.FacesContext context, java.lang.Object value)
Converts the submitted value. Returns an object of type UploadedFile.
context
- The FacesContextvalue
- An object representing the submitted value
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.
getValueAsString
in class HiddenField
context
- FacesContext for the current request
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.
getReadOnlyValueString
in class HiddenField
context
- FacesContext for the current request
public java.lang.String getType()
public void setText(java.lang.Object text)
setText
in class Field
Field.getText()
public int getColumns()
getColumns
in class Field
public java.lang.String getPrimaryElementID(javax.faces.context.FacesContext context)
getPrimaryElementID
in interface com.sun.webui.jsf.component.ComplexComponent
getPrimaryElementID
in class Field
context
- The FacesContext for the request
getLabeledElementId(javax.faces.context.FacesContext)
public java.lang.String getLabeledElementId(javax.faces.context.FacesContext context)
for
attribute.
getLabeledElementId
in interface com.sun.webui.jsf.component.ComplexComponent
getLabeledElementId
in class Field
context
- The FacesContext used for the request
public java.lang.String getFocusElementId(javax.faces.context.FacesContext context)
getFocusElementId
in interface com.sun.webui.jsf.component.ComplexComponent
getFocusElementId
in class Field
context
- The FacesContext used for the requestpublic void setRequired(boolean required)
setRequired
in interface javax.faces.component.EditableValueHolder
setRequired
in class WebuiInput
public javax.el.ValueExpression getValueExpression(java.lang.String name)
Return the ValueExpression
stored for the
specified name (if any), respecting any property aliases.
getValueExpression
in class Field
name
- Name of value binding expression to retrievepublic void setValueExpression(java.lang.String name, javax.el.ValueExpression binding)
Set the ValueExpression
stored for the
specified name (if any), respecting any property
aliases.
setValueExpression
in class Field
name
- Name of value binding to setbinding
- ValueExpression to set, or null to removepublic javax.faces.convert.Converter getConverter()
javax.faces.converter.Converter
interface; or
getConverter
in interface javax.faces.component.ValueHolder
getConverter
in class javax.faces.component.UIOutput
public int getMaxLength()
getMaxLength
in class Field
public boolean isTrim()
Field
Flag indicating that any leading and trailing blanks will be trimmed prior to conversion to the destination data type. Default value is true.
isTrim
in class Field
public java.lang.Object getText()
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.
getText
in class Field
public void setColumns(int columns)
Number of character character columns used to render this field. The default is 40.
setColumns
in class Field
getColumns()
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.
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.
getUploadedFile()
public boolean isPreservePath()
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.
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
.
public void setPreservePath(boolean preservePath)
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.
It is not clear if it is a security risk to transmit the
full file path in clear text to the server.
public void restoreState(javax.faces.context.FacesContext _context, java.lang.Object _state)
Restore the state of this component.
restoreState
in interface javax.faces.component.StateHolder
restoreState
in class Field
public java.lang.Object saveState(javax.faces.context.FacesContext _context)
Save the state of this component.
saveState
in interface javax.faces.component.StateHolder
saveState
in class Field
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |