public class InputFile extends HtmlInputFile
The <o:inputFile> is a component that extends the standard <h:inputFile> and
adds support for multiple, directory, accept and maxsize
attributes, along with built-in server side validation on accept and maxsize attributes.
Additionally, it makes sure that the value of HTML file input element is never rendered. The standard
<h:inputFile> renders Part#toString() to it which is unnecessary.
You can use it the same way as <h:inputFile>, you only need to change h: into
o: to get the extra support for multiple, directory and accept
attributes. Here's are some usage examples.
It is basically not different from <h:inputFile>. You might as good use it instead.
<h:form enctype="multipart/form-data">
<o:inputFile value="#{bean.file}" />
<h:commandButton value="Upload" action="#{bean.upload}" />
</h:form>
private Part file; // +getter+setter
public void upload() {
if (file != null) {
String name = Servlets.getSubmittedFileName(file);
String type = file.getContentType();
long size = file.getSize();
InputStream content = file.getInputStream();
// ...
}
}
Note that it's strongly recommended to use Servlets.getSubmittedFileName(Part) to obtain the submitted file
name to make sure that any path is stripped off. Some browsers are known to incorrectly include the client side path
or even a fake path along with the file name.
The multiple attribute can be set to true to enable multiple file selection.
With this setting the enduser can use control/command/shift keys to select multiple files.
<h:form enctype="multipart/form-data">
<o:inputFile value="#{bean.files}" multiple="true" />
<h:commandButton value="Upload" action="#{bean.upload}" />
</h:form>
private List<Part> files; // +getter+setter
public void upload() {
if (files != null) {
for (Part file : files) {
String name = Servlets.getSubmittedFileName(file);
String type = file.getContentType();
long size = file.getSize();
InputStream content = file.getInputStream();
// ...
}
}
}
The directory attribute can be set to true to enable folder selection. This implicitly also
sets multiple attribute to true and renders an additional webkitdirectory
attribute to HTML for better browser compatibility.
<h:form enctype="multipart/form-data">
<o:inputFile value="#{bean.files}" directory="true" />
<h:commandButton value="Upload" action="#{bean.upload}" />
</h:form>
private List<Part> files; // +getter+setter
public void upload() {
if (files != null) {
for (Part file : files) {
String name = Servlets.getSubmittedFileName(file);
String type = file.getContentType();
long size = file.getSize();
InputStream content = file.getInputStream();
// ...
}
}
}
Do note that this does not send physical folders, but only files contained in those folders.
The accept attribute can be set with a comma separated string of media types of files to filter in
browse dialog. An overview of all registered media types can be found at
IANA.
<h:form enctype="multipart/form-data">
<o:inputFile id="file" value="#{bean.losslessImageFile}" accept="image/png,image/gif" />
<h:commandButton value="Upload" action="#{bean.upload}" />
<h:message for="file" />
</h:form>
<h:form enctype="multipart/form-data">
<o:inputFile id="file" value="#{bean.anyImageFile}" accept="image/*" />
<h:commandButton value="Upload" action="#{bean.upload}" />
<h:message for="file" />
</h:form>
<h:form enctype="multipart/form-data">
<o:inputFile id="file" value="#{bean.anyMediaFile}" accept="audio/*,image/*,video/*" />
<h:commandButton value="Upload" action="#{bean.upload}" />
<h:message for="file" />
</h:form>
This will also be validated in the server side using a built-in validator. Do note that the accept
attribute only filters in client side and validates in server side based on the file extension, and this does thus
not strictly validate the file's actual content. To cover that as well, you should in the bean's action method parse
the file's actual content using the tool suited for the specific media type, such as ImageIO#read() for
image files, and then checking if it returns the expected result.
The default message for server side validation of accept attribute is:
{0}: Media type of file ''{1}'' does not match ''{2}''
Where {0} is the component's label and {1} is the submitted file name and {2}
is the value of accept attribute.
You can override the default message by the acceptMessage attribute:
<h:form enctype="multipart/form-data">
<o:inputFile id="file" value="#{bean.anyImageFile}" accept="image/*" acceptMessage="File {1} is unacceptable!" />
<h:commandButton value="Upload" action="#{bean.upload}" />
<h:message for="file" />
</h:form>
Or by the custom message bundle file as identified by <application><message-bundle> in
faces-config.xml. The message key is org.omnifaces.component.input.InputFile.accept.
org.omnifaces.component.input.InputFile.accept = File {1} is unacceptable!
The maxsize attribute can be set with the maximum file size in bytes which will be validated on each
selected file in the client side if the client supports HTML5 File API. This only requires that there is a
<h:message> or <h:messages> component and that it has its id set.
Namely, the client side validation will on fail trigger JSF via an ajax request to render the faces message. Noted
should be that the file(s) will not be sent, hereby saving network bandwidth.
<h:form enctype="multipart/form-data">
<o:inputFile id="file" value="#{bean.file}" maxsize="#{10 * 1024 * 1024}" /> <!-- 10MiB -->
<h:commandButton value="Upload" action="#{bean.upload}" />
<h:message id="messageForFile" for="file" />
</h:form>
This will also be validated in the server side using a built-in validator.
The default message for both client side and server side validation of maxsize attribute is:
{0}: Size of file ''{1}'' is larger than maximum of {2}
Where {0} is the component's label and {1} is the submitted file name and {2}
is the value of maxsize attribute.
You can override the default message by the maxsizeMessage attribute:
<h:form enctype="multipart/form-data">
<o:inputFile id="file" value="#{bean.file}" maxsize="#{10 * 1024 * 1024}" maxsizeMessage="File {1} is too big!" />
<h:commandButton value="Upload" action="#{bean.upload}" />
<h:message id="messageForFile" for="file" />
</h:form>
Or by the custom message bundle file as identified by <application><message-bundle> in
faces-config.xml. The message key is org.omnifaces.component.input.InputFile.maxsize.
org.omnifaces.component.input.InputFile.maxsize = File {1} is too big!
| Modifier and Type | Field and Description |
|---|---|
static String |
COMPONENT_TYPE |
COMPONENT_FAMILY, CONVERSION_MESSAGE_ID, REQUIRED_MESSAGE_ID, UPDATE_MESSAGE_ID, VALIDATE_EMPTY_FIELDS_PARAM_NAMEATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY| Constructor and Description |
|---|
InputFile() |
| Modifier and Type | Method and Description |
|---|---|
void |
decode(FacesContext context)
This override checks if client side validation on maxsize has failed and if multi file upload is enabled.
|
void |
encodeEnd(FacesContext context)
This override will render
multiple, directory and accept attributes
accordingly. |
String |
getAccept()
Returns comma separated string of mime types of files to filter in client side file browse dialog.
|
String |
getAcceptMessage()
Returns validation message to be displayed when the condition in
accept attribute is violated. |
protected Object |
getConvertedValue(FacesContext context,
Object submittedValue)
This override will convert the individual parts if multi file upload is enabled and collect only non-null parts
having a non-empty file name and a file size above zero.
|
Long |
getMaxsize()
Returns maximum size in bytes for each selected file.
|
String |
getMaxsizeMessage()
Returns validation message to be displayed when the condition in
maxsize attribute is violated. |
Object |
getValue()
This override returns null during render response as it doesn't make sense to render
Part#toString()
as value of file input, moreover it's for HTML security reasons discouraged to prefill the value of a file input
even though browsers will ignore it. |
boolean |
isDirectory()
Returns whether or not to enable directory selection.
|
boolean |
isMultiple()
Returns whether or not to allow multiple file selection.
|
void |
setAccept(String accept)
Sets comma separated string of media types of files to filter in client side file browse dialog.
|
void |
setAcceptMessage(String acceptMessage)
Sets validation message to be displayed when the condition in
accept attribute is violated. |
void |
setDirectory(boolean directory)
Sets whether or not to enable directory selection.
|
void |
setMaxsize(Long maxsize)
Sets maximum size in bytes for each selected file.
|
void |
setMaxsizeMessage(String maxsizeMessage)
Sets validation message to be displayed when the condition in
maxsize attribute is violated. |
void |
setMultiple(boolean multiple)
Sets whether or not to allow multiple file selection.
|
protected void |
validateHierarchy()
Validate the component hierarchy.
|
protected void |
validateValue(FacesContext context,
Object convertedValue)
This override will server-side validate any
accept and maxsize for each part. |
getAccesskey, getAlt, getAutocomplete, getDefaultEventName, getDir, getEventNames, getLabel, getLang, getMaxlength, getOnblur, getOnchange, getOnclick, getOndblclick, getOnfocus, getOnkeydown, getOnkeypress, getOnkeyup, getOnmousedown, getOnmousemove, getOnmouseout, getOnmouseover, getOnmouseup, getOnselect, getRole, getSize, getStyle, getStyleClass, getTabindex, getTitle, isDisabled, isReadonly, setAccesskey, setAlt, setAutocomplete, setDir, setDisabled, setLabel, setLang, setMaxlength, setOnblur, setOnchange, setOnclick, setOndblclick, setOnfocus, setOnkeydown, setOnkeypress, setOnkeyup, setOnmousedown, setOnmousemove, setOnmouseout, setOnmouseover, setOnmouseup, setOnselect, setReadonly, setRole, setSize, setStyle, setStyleClass, setTabindex, setTitleaddValidator, addValueChangeListener, clearInitialState, compareValues, getConverterMessage, getFamily, getRequiredMessage, getSubmittedValue, getValidator, getValidatorMessage, getValidators, getValueChangeListener, getValueChangeListeners, isEmpty, isImmediate, isLocalValueSet, isRequired, isValid, markInitialState, processDecodes, processUpdates, processValidators, removeValidator, removeValueChangeListener, resetValue, restoreState, saveState, setConverterMessage, setImmediate, setLocalValueSet, setRequired, setRequiredMessage, setSubmittedValue, setValid, setValidator, setValidatorMessage, setValue, setValueChangeListener, updateModel, validategetConverter, getLocalValue, setConverteraddClientBehavior, addFacesListener, broadcast, encodeBegin, encodeChildren, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEventencodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, visitTreeclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitaddClientBehavior, getClientBehaviorsgetConverter, getLocalValue, setConverterpublic static final String COMPONENT_TYPE
public void decode(FacesContext context)
protected Object getConvertedValue(FacesContext context, Object submittedValue)
getConvertedValue in class UIInputprotected void validateValue(FacesContext context, Object convertedValue)
accept and maxsize for each part.validateValue in class UIInputpublic Object getValue()
Part#toString()
as value of file input, moreover it's for HTML security reasons discouraged to prefill the value of a file input
even though browsers will ignore it.getValue in interface ValueHoldergetValue in class UIInputpublic void encodeEnd(FacesContext context) throws IOException
multiple, directory and accept attributes
accordingly. As the directory attribute is relatively new, for better browser compatibility the
webkitdirectory attribute will also be written along it.
They're written as passthrough attributes because in Mojarra the startElement() takes place in
encodeEnd(FacesContext) instead of UIComponentBase.encodeBegin(FacesContext).
encodeEnd in class UIComponentBaseIOExceptionprotected void validateHierarchy()
Development.IllegalStateException - When component hierarchy is wrong.public boolean isMultiple()
true when directory attribute is true.public void setMultiple(boolean multiple)
multiple - Whether or not to allow multiple file selection.public boolean isDirectory()
public void setDirectory(boolean directory)
true, this implicitly defaults the multiple attribute to true.directory - Whether or not to enable directory selection.public String getAccept()
public void setAccept(String accept)
accept - Comma separated string of mime types of files to filter in client side file browse dialog.public String getAcceptMessage()
accept attribute is violated.accept attribute is violated.public void setAcceptMessage(String acceptMessage)
accept attribute is violated.acceptMessage - Validation message to be displayed when the condition in accept attribute is
violated.public Long getMaxsize()
public void setMaxsize(Long maxsize)
maxsize - Maximum size in bytes for each selected file.public String getMaxsizeMessage()
maxsize attribute is violated.maxsize attribute is violated.public void setMaxsizeMessage(String maxsizeMessage)
maxsize attribute is violated.maxsizeMessage - Validation message to be displayed when the condition in maxsize attribute is
violated.Copyright © 2012–2017 OmniFaces. All rights reserved.