Today we will look into the Primefaces FileUpload component. HTML provides you file input tag to select the file, but we need a lot more to upload a file to the server. Primefaces has removed that burden by providing you a ready-made FileUpload component that help you in creating beautiful UI with backend support for upload files to the server.

Primefaces FileUpload

We will look into the Primefaces FileUpload component features that you can use in your application.

This tutorial assumes that you have basic knowledge of Primeface, if not please go through Primefaces Example.

Primefaces FileUpload Basic Info

TagfileUpload
Component Classorg.primefaces.component.fileupload.FileUpload
Component Typeorg.primefaces.component.FileUpload
Component Familyorg.primefaces.component
Renderer Typeorg.primefaces.component.FileUploadRenderer
Renderer Classorg.primefaces.component.fileupload.FileUploadRenderer

Primefaces FileUpload Attributes

NameDefaultTypeDescription
idnullStringUnique identifier of the component.
renderedtruebooleanBoolean value to specify the rendering of the component, when set to false component will not be rendered
bindingnullObjectAn el expression that maps to a server side UIComponent instance in a backing bean
valuenullObjectValue of the component than can be either an EL expression of a literal text
converternullConverter/StringAn el expression or a literal text that defines a converter for the component. When it’s an EL expression, it’s resolved to a converter instance. In case it’s a static text, it must refer to a converter id.
immediatefalseBooleanWhen set true, process validations logic is executed at apply request values phase for this component
requiredfalseBooleanMarks component as required.
validatornullMethodExprA method expression that refers to a method validating the input
valueChangeListenernullMethodExprA method expression that refers to a method for handling a valueChangeEvent
requiredMessagenullStringMessage to be displayed when required field validation fails
converterMessagenullStringMessage to be displayed when conversion fails.
validatorMessagenullStringMessage to be displayed when validation fails.
widgetVarnullStringName of the client side widget.
updatenullStringComponent(s) to update after fileupload completes.
processnullStringComponent(s) to process in fileupload request.
fileUploadListenernullMethodExprMethod to invoke when a file is uploaded.
multiplefalseBooleanAllows choosing of multi file uploads from native
autofalseBooleanWhen set to true, selecting a file starts the upload process implicitly
labelChooseStringLabel of the browse button.
allowTypesnullStringRegular expression for accepted file types,
sizeLimitnullIntegerIndividual file size limit in bytes.
fileLimitnullIntegerMaximum number of files allowed to upload.
stylenullStringInline style of the component.
styleClassnullStringStyle class of the component.
modeadvancedStringMode of the fileupload, can be simple or advanced.
uploadLabelUploadStringLabel of the upload button.
cancelLabelCancelStringLabel of the cancel button.
invalidSizeMessagenullStringMessage to display when size limit exceeds.
invalidFileMessagenullStringMessage to display when file is not accepted.
fileLimitMessagenullStringMessage to display when file limit exceeds.
dragDropSupporttrueBooleanSpecifies dragdrop based file selection from filesystem, default is true and works only on supported browsers
onstartnullStringClient side callback to execute when upload begins.
onerrornullStringCallback to execute if fileupload request fails.
oncompletenullStringClient side callback to execute when upload ends.
disabledfalseBooleanDisables component when set true.
messageTemplate{name} {size}StringMessage template to use when displaying file validation errors
previewWidth80IntegerWidth for image previews in pixels.

Primefaces File Upload Example

For making use of FileUpload, you have to provide the FileUpload engine by adding primefaces.UPLOADER web deployment paramater that might take the below values:

web.xml

Copy
<context-param> <param-name>primefaces.UPLOADER</param-name> <param-value>auto|native|commons</param-value> </context-param>
  1. auto: This is the default mode and Primefaces tries to detect the best method by checking the runtime environment, if JSF runtime is at least 2.2 native uploader is selected, otherwise commons.
  2. native: Native mode uses servlet 3.x Part API to upload the files and if JSF runtime is less 2.2 an exception is being thrown.
  3. commons: This option chooses commons fileUpload, it requires the following filter configuration in your deployment descriptor.

web.xml

Copy
<filter> <filter-name>PrimeFaces FileUpload Filter</filter-name> <filter-class> org.primefaces.webapp.filter.FileUploadFilter </filter-class> </filter> <filter-mapping> <filter-name>PrimeFaces FileUpload Filter</filter-name> <servlet-name>Faces Servlet</servlet-name> </filter-mapping>

Note the servlet-name should match the configured name of the JSF servlet which is Faces Servlet in this case. Alternatively, you can do a configuration based on URL-pattern as well.

Primefaces Simple File Upload

Simple file upload mode works in legacy browsers, with a file input whose value should be an UploadedFile instance. Ajax uploads are not supported in the simple upload. Look below for these files required for making a simple file upload sample.

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data"> <p:fileUpload value="#{fileUploadManagedBean.file}" mode="simple"></p:fileUpload> <p:separator/> <h:commandButton value="Dummy Action" action="#{fileUploadManagedBean.dummyAction}"></h:commandButton> </h:form> </h:body> </html>
Copy
package com.journaldev.prime.faces.beans; import javax.faces.bean.ManagedBean; import javax.faces.bean.SessionScoped; import org.primefaces.model.UploadedFile; @ManagedBean @SessionScoped public class FileUploadManagedBean { UploadedFile file; public UploadedFile getFile() { return file; } public void setFile(UploadedFile file) { this.file = file; } public String dummyAction(){ System.out.println("Uploaded File Name Is :: "+file.getFileName()+" :: Uploaded File Size :: "+file.getSize()); return ""; } }

web.xml

Copy
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5" metadata-complete="true"> <servlet> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>/faces/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.xhtml</url-pattern> </servlet-mapping> <context-param> <description>State saving method: 'client' or 'server' (=default). See JSF Specification 2.5.2</description> <param-name>javax.faces.STATE_SAVING_METHOD</param-name> <param-value>client</param-value> </context-param> <context-param> <param-name>primefaces.UPLOADER</param-name> <param-value>auto</param-value> </context-param> <listener> <listener-class>com.sun.faces.config.ConfigureListener</listener-class> </listener> </web-app>

pom.xml

Copy
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.journaldev</groupId> <artifactId>Primefaces-FileUpload-Sample</artifactId> <packaging>war</packaging> <version>0.0.1-SNAPSHOT</version> <name>Primefaces-FileUpload-Sample Maven Webapp</name> <url>http://maven.apache.org</url> <repositories> <repository> <id>prime-repo</id> <name>PrimeFaces Maven Repository</name> <url>http://repository.primefaces.org</url> <layout>default</layout> </repository> </repositories> <dependencies> <!-- Servlet --> <dependency> <groupId>javax.servlet</groupId> <artifactId>servlet-api</artifactId> <version>2.5</version> <scope>provided</scope> </dependency> <!-- Faces Implementation --> <dependency> <groupId>com.sun.faces</groupId> <artifactId>jsf-impl</artifactId> <version>2.2.4</version> </dependency> <!-- Faces Library --> <dependency> <groupId>com.sun.faces</groupId> <artifactId>jsf-api</artifactId> <version>2.2.4</version> </dependency> <!-- Primefaces Version 5 --> <dependency> <groupId>org.primefaces</groupId> <artifactId>primefaces</artifactId> <version>5.0</version> </dependency> <!-- JSP Library --> <dependency> <groupId>javax.servlet.jsp</groupId> <artifactId>javax.servlet.jsp-api</artifactId> <version>2.3.1</version> </dependency> <!-- JSTL Library --> <dependency> <groupId>javax.servlet</groupId> <artifactId>jstl</artifactId> <version>1.1.2</version> </dependency> </dependencies> </project>

As a summary:

  1. Primefaces FileUpload engine that’s used is auto.
  2. fileUpload component’s value attribute associated with the UploadedFile instance.
  3. Using of fileUpload requires including the fileUpload component within a form, its enctype is multipart/form-data.
  4. Dummy action provided has used to print out the name and size of the uploaded file.

Where, the result of demo will be: Simple input button has been rendered into your browser.

Primefaces FileUpload - Simple File Upload Sample - Initial View

Primefaces FileUpload - Simple File Upload Sample - Select File View

Primefaces FileUpload - Simple File Upload Sample - File Selected View

And once you’ve clicked on the Dummy Action a dummy action method is executed and the information of uploaded file gets printed into your console like below.

Primefaces FileUpload - Simple File Upload Sample - File Uploaded

Primefaces Advanced File Upload

FileUpload component provides you a simple view and an advanced view. Choosing of advanced view makes the only available way for accessing uploaded files is through the FileUploadListener. The listener will be processed as soon as the file is uploaded and a FileUploadEvent has been passed into listener as a parameter.

Look below at the required files that help you using advanced mode.

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data" style="width:500px"> <p:fileUpload value="#{fileUploadManagedBean.file}" mode="advanced" fileUploadListener="#{fileUploadManagedBean.fileUploadListener}"></p:fileUpload> </h:form> </h:body> </html>
Copy
package com.journaldev.prime.faces.beans; import javax.faces.bean.ManagedBean; import javax.faces.bean.SessionScoped; import org.primefaces.event.FileUploadEvent; import org.primefaces.model.UploadedFile; @ManagedBean @SessionScoped public class FileUploadManagedBean { UploadedFile file; public UploadedFile getFile() { return file; } public void setFile(UploadedFile file) { this.file = file; } public void fileUploadListener(FileUploadEvent e){ // Get uploaded file from the FileUploadEvent this.file = e.getFile(); // Print out the information of the file System.out.println("Uploaded File Name Is :: "+file.getFileName()+" :: Uploaded File Size :: "+file.getSize()); } }

As a summary:

  1. Neither web.xml nor pom.xml have been mentioned, cause they haven’t changed.
  2. FileUpload component’s value attribute associated with the UploadedFile instance, as the component also listened by the FileUploadListener.
  3. FileUploadListener receives a FileUploadEvent as a parameter.
  4. Once you’ve clicked on the Upload action, the FileUploadListener will be executed and a FileUploadEvent has been created and passed.

Where, the result of demo will be a new view of upload component with two additional buttons; one for upload and the latter for cancel.

Primefaces FileUpload - Advanced File Upload Sample - Initial View

Primefaces FileUpload - Advanced File Upload Sample - Select File View

Primefaces FileUpload - Advanced File Upload Sample - File Ready To Be Uploaded

Primefaces FileUpload - Advanced File Upload Sample - Form Is Uploading File

Primefaces FileUpload - Advanced File Upload Sample - File Uploaded And Info Printed Out

It’s important to notice the following points as a result of execution:

  1. The file uploaded is passed within the FileUploadEvent and it can be accessed by invoking e.getFile() against event object which returns an UploadedFile instance.
  2. The upload process would be cancelling totally, if you’ve clicked on Cancel instead of Upload. Canceling the upload will prevent the listener from getting invoked.

Primefaces Multiple File Uploads

Uploading multiple files using the FileUpload component is applicable so that multiple files can be selected from browser dialog. Multiple uploads are not supported in legacy browsers. Set multiple attribute to true enabling multiple selections of files, however, multiple selections of files doesn’t mean all files will be sent into the server using one request. However, they will be sent one by one.

Look below at the required change that makes multiple selections applicable.

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data" style="width:500px"> <p:fileUpload value="#{fileUploadManagedBean.file}" mode="advanced" multiple="true" fileUploadListener="#{fileUploadManagedBean.fileUploadListener}"></p:fileUpload> </h:form> </h:body> </html>
Copy
package com.journaldev.prime.faces.beans; import javax.faces.bean.ManagedBean; import javax.faces.bean.SessionScoped; import org.primefaces.event.FileUploadEvent; import org.primefaces.model.UploadedFile; @ManagedBean @SessionScoped public class FileUploadManagedBean { UploadedFile file; public UploadedFile getFile() { return file; } public void setFile(UploadedFile file) { this.file = file; } public void fileUploadListener(FileUploadEvent e){ // Get uploaded file from the FileUploadEvent this.file = e.getFile(); // Print out the information of the file System.out.println("Uploaded File Name Is :: "+file.getFileName()+" :: Uploaded File Size :: "+file.getSize()); } }

Where, the result of executing the application looks like below:

Primefaces FileUpload - Advanced File Upload Sample - Multiple Files Selection

Primefaces FileUpload - Advanced File Upload Sample - Multiple Files Selected

Primefaces FileUpload - Advanced File Upload Sample - Multiple Files - Print Out Information of Files

It’s important to notice the following points from the demo:

  1. Cancelling the upload using Cancel button, should lead us into canceling the upload process of all files.
  2. Clicking into icon X that’s beside every single file that will be uploading, cause the corresponding file uploaded to be canceled only.
  3. Once you’ve clicked on Upload action, the listener will be invoked by the number of files that get loaded.

Primefaces Auto File Upload

The default behavior requires users to trigger the upload process, you can change this way by setting auto to true. Auto uploads are triggered as soon as files are selected from the dialog.

Look below at the required change that makes auto upload applicable.

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data" style="width:500px"> <p:fileUpload value="#{fileUploadManagedBean.file}" mode="advanced" multiple="true" auto="true" fileUploadListener="#{fileUploadManagedBean.fileUploadListener}"></p:fileUpload> </h:form> </h:body> </html>

Where, the result of executing the application looks like below:

Primefaces FileUpload - Advanced File Upload Sample - Auto Upload - Initial View

Primefaces FileUpload - Advanced File Upload Sample - Auto Upload - Selection View

Once you’ve clicked Open into your browser window, Uploading process has been started instantly.

Primefaces FileUpload - Advanced File Upload Sample - Auto Upload - Auto Uploaded View Primefaces FileUpload - Advanced File Upload Sample - Auto Upload - Files Uploaded - Print Out Information

Primefaces File Upload Partial Page Update

After the fileUpload process completes you can use the Primefaces PPR (Partial Page Render) to update any component on the page. FileUpload is equipped with the update attribute for this purpose. Following example displays a “File Uploaded Successfully” message using the growl component after file upload. Growl component will be discussed later when coming into messages.

The following fragment of codes helps you display a message once the file has been uploaded.

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data" style="width:500px"> <p:growl id="msg"></p:growl> <p:fileUpload value="#{fileUploadManagedBean.file}" mode="advanced" fileUploadListener="#{fileUploadManagedBean.fileUploadListener}" update="msg"></p:fileUpload> </h:form> </h:body> </html>
Copy
package com.journaldev.prime.faces.beans; import javax.faces.application.FacesMessage; import javax.faces.bean.ManagedBean; import javax.faces.bean.SessionScoped; import javax.faces.context.FacesContext; import org.primefaces.event.FileUploadEvent; import org.primefaces.model.UploadedFile; @ManagedBean @SessionScoped public class FileUploadManagedBean { UploadedFile file; public UploadedFile getFile() { return file; } public void setFile(UploadedFile file) { this.file = file; } public void fileUploadListener(FileUploadEvent e){ // Get uploaded file from the FileUploadEvent this.file = e.getFile(); // Print out the information of the file System.out.println("Uploaded File Name Is :: "+file.getFileName()+" :: Uploaded File Size :: "+file.getSize()); // Add message FacesContext.getCurrentInstance().addMessage(null,new FacesMessage("File Uploaded Successfully")); } }

Where, the result of execution looks like below:
Primefaces FileUpload - Advanced File Upload Sample - Partial Page Update

A message has been added into FacesContext and the FileUpload component defines the update attribute which will cause the message to be rendered through Ajax mechanism. Ajax behavior will be discussed later in a separate tutorial.

File Upload Filters

Users can be restricted to only select the file types you’ve configured, the example below demonstrates how to accept images only.

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data" style="width:500px"> <p:growl id="msg"></p:growl> <p:fileUpload value="#{fileUploadManagedBean.file}" mode="advanced" allowTypes="/(\.|\/)(gif|jpe?g|png)$/" fileUploadListener="#{fileUploadManagedBean.fileUploadListener}" update="msg"></p:fileUpload> </h:form> </h:body> </html>

And the result of execution looks like below
Primefaces FileUpload - Advanced File Upload Sample - Enforce Images To Be Uploaded

Primefaces FileUpload - Advanced File Upload Sample - Enforce Images - Error Message Shown

Primefaces File Upload Size Limit & File Limit

Sometimes, you need to restrict the size of the uploaded file or the number of files to be uploaded. Doing such these restrictions aren’t big issue with Primefaces FileUpload component. You can achieve these restrictions by providing sizeLimit & fileLimit attributes respectively against FileUpload itself.

Following the code fragments that keep your users restricted:

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data" style="width:500px"> <p:growl id="msg"></p:growl> <p:fileUpload value="#{fileUploadManagedBean.file}" mode="advanced" multiple="true" fileLimit="3" sizeLimit="2048" fileUploadListener="#{fileUploadManagedBean.fileUploadListener}" update="msg"></p:fileUpload> </h:form> </h:body> </html>

When you try to upload more than three files or file its size exceeds the limit an error messages will be displayed like below:

Primefaces FileUpload - Advanced File Upload Sample - Size Limit Failed

Primefaces FileUpload - Advanced File Upload Sample - Four Files - File Limit Failed

Primefaces File Upload Validation Message

invalidFileMessage, invalidSizeMessage and fileLimitMessage options are provided to display validation messages to the users. You can provide whatever you want of messages for those validations. Look below at the provided example.

index.xhtml

Copy
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:h="http://java.sun.com/jsf/html" xmlns:f="http://java.sun.com/jsf/core" xmlns:p="http://primefaces.org/ui"> <h:head> <title>Journaldev Tutorial</title> </h:head> <h:body> <h:form enctype="multipart/form-data" style="width:500px"> <p:growl id="msg"></p:growl> <p:fileUpload value="#{fileUploadManagedBean.file}" invalidSizeMessage="JournalDev: Invalid Size" invalidFileMessage="JournalDev: Invalid File Type" fileLimitMessage="JournalDev: Invalid File Limit" mode="advanced" multiple="true" fileLimit="3" sizeLimit="2048" allowTypes="/(\.|\/)(gif|jpe?g|png)$/" fileUploadListener="#{fileUploadManagedBean.fileUploadListener}" update="msg"></p:fileUpload> </h:form> </h:body> </html>

And the messages should look like below:
Primefaces FileUpload - Advanced File Upload Sample - Invalid File Size - Custom Message

Primefaces FileUpload - Advanced File Upload Sample - Invalid File Type - Custom Message

Primefaces FileUpload - Advanced File Upload Sample - Four Files - File Limit Failed - Custom Message

If you’ve noticed the messages have been changed and they’re provided different text values. If you notice the managed bean code, we are not doing anything with the file. However in real life situations, we can use UploadedFile getInputstream() method to get the file data and save it as file on server or database.

Primefaces FileUpload Summary

This tutorial intended to provide you a full detailed explanation about using of FileUpload Primefaces component. FileUpload component equipped with a lot of features that keep your focus on the business instead of trying to implement something similar. You can download the sample project from below link and use other fileUpload attributes to learn more.