Defining a file upload listener is a way to access the uploaded files. The definition of the handleFileUpload method is given next. The method receives an instance of org.primefaces.event.FileUploadEvent as a parameter.

public void handleFileUpload(FileUploadEvent event) {
  UploadedFile file = event.getFile();
  MessageUtil.addInfoMessage("upload.successful",
    file.getFileName() + " is uploaded.");
}

Texts for the upload and cancel buttons can be customized with the uploadLabel and cancelLabel attributes. The showButtons attribute enables/disables the visibility of the upload and cancel buttons in the button bar of the component. The auto attribute enables automatic file upload. A file will be uploaded automatically when it is selected or dragged-and-dropped to the component.

The fileUpload component allows us to restrict the file selection only to the types configured with the allowTypes attribute. The allowTypes attribute accepts a JavaScript regular expression that will be used to match against the name of the file to be uploaded. The following definition only accepts image files with an extension of gif, jpg, jpeg, or png:

<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}"
  allowTypes="/(.|/)(gif|jpe?g|png)$/" />

When an incorrect type of file is selected or dragged-and-dropped onto the fileUpload component, the component renders an error message to alert the user to the wrong file type. The following image shows the error message that occurred when a file with type flv was selected for upload:

The error message Invalid file type can also be customized with the invalidFileMessage attribute.

With the sizeLimit attribute, it's possible to restrict the maximum file upload size. The following definition limits the file size to a maximum of 10 KB:

<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}"
  sizeLimit="10240" />

The following image shows the error message that occurred when a file with size 2.6 MB was selected for upload:

The error message Invalid file size can be customized with the invalidSizeMessage attribute.

By default, selecting multiple files for uploading, via browsing after clicking on the Choose button, is not supported by the component. Setting the multiple attribute to true enables multiple upload for the advanced version of the component. In the multiple mode, files get uploaded in the selected order and the method bound with the fileUploadListener attribute gets called for each uploaded file.

<p:fileUpload id="multipleUpload" multiple="true" update="growl"
  fileUploadListener="#{fileBean.handleFileUpload}" />

The fileUpload component supports hooking custom JavaScript methods when the upload process starts and ends. The following code snippet shows the upload component with the onstart and oncomplete attributes showing a progress dialog box while doing the upload:

<p:fileUpload fileUploadListener="#{fileBean.handleFileUpload}"
  onstart="showStatus()" oncomplete="hideStatus()" />

The showStatus and hideStatus methods are two simple methods for showing and hiding a dialog box component, which is also a PrimeFaces component.

<script type="text/javascript">
  function showStatus() {
    PF('statusDialog').show();
  }
  function hideStatus() {
    PF('statusDialog').hide();
  }
</script>

<p:dialog modal="true" widgetVar="statusDialog" header="Status"
  draggable="false" closable="false">
  <p:graphicImage value="/resources/images/ajax-loader.gif" />
</p:dialog>

In supported browsers, a file can also be dragged-and-dropped for uploading with fileUpload, and the component itself will be the drop zone. The dragDropSupport attribute defines whether or not to enable drag-and-drop from the file system. By default, the value of this attribute is true. In order to provide drag-and-drop support, the fileUpload component should be in advanced mode, which is also the default mode. The definition of the fileUpload component for uploading files with drag-and-drop would be as follows:

<p:fileUpload id="upload" value="#{fileBean.file}"
  dragDropSupport="true"
  update="growl"
  fileUploadListener="#{fileBean.handleFileUpload}" />

This recipe is available in the demo web application on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition). Clone the project if you have not done it yet, explore the project structure, and build and deploy the WAR file on every Servlet 3.x compatible application server, such as JBoss WildFly or Apache TomEE.

The showcase for the recipe is available at the URLs listed in the following table: