FileEntry

results contains the results of the most recent file upload operation. If the form was submitted, and no files were selected, than the previous results would remain. The results are an instance of FileEntryResults, which encapsulates a list of FileInfo objects, each corresponding to an individual file that was attempted to be uploaded in the one form submit.

fileEntryListener is the mechanism by which application are notified that a file upload attempt has been made. Files may have failed uploading, due to restrictions set on uploads, or they may have succeeded. For both cases, the attempt triggers this listener. This is an example of a prototypical fileEntryListener:

import org.icefaces.ace.component.fileentry.*;

public void listener(FileEntryEvent event) {
    FileEntry fileEntry = (FileEntry) event.getSource();
    FileEntryResults results = fileEntry.getResults();
    for (FileEntryResults.FileInfo fileInfo : results.getFiles()) {
        if (fileInfo.isSaved()) {
            // Process the file. Only save cloned copies of results or fileInfo
        }
    }
}

callback is the means of specifying a FileEntryCallback, which assumes control of receiving the uploaded file data, supplanting the built-in file-system saving mechanism. This is intended for scenarios where files should be processed in memory, written directly to a database, or over a socket. Any instance where writing the files to the file-system are undesirable. There is a tutorial, providing a code example.

With ICEfaces 3.0.0 there is a known issue with updating the FileEntryStatus for an upload, from within the callback.

immediate controls when in the JSF lifecycle the fileEntryListener will get invoked:

• true:  fileEntryListener invoked at end of ApplyRequestValues phase
  • If the upload attempt failed, or a file succeeded uploading, but processing of it deemed the file invalid, then the form submission can be made invalid, and UpdateModel phase skipped, by calling FacesContext.validationFailed() in the fileEntryListener method.
  • If other input components need to be validated using the details or contents of the uploaded files, having immediate="true" would make the fileEntryListener be invoked earlier than the ProcessValidations phase for the input components.
  • If the form submit button's action or actionListener method needs make use of the details of contents of the uploaded files, having immediate="true" would make the fileEntryListener be invoked earlier than the InvokeApplication phase for the command component.
• false:  fileEntryListener invoked before RenderResponse phase
  • If the fileEntryListener depends on the validation of input components, or the action or actionListener methods of command components, having immediate="false" would make the fileEntryListener be invoked later than everything else. But, unlike action and actionListener methods, which are invoked during InvokeApplication, and so will not execute if the form submission is invalid, fileEntryListener will always be invoked, as it is invoked in the before part of RenderResponse phase.

Default is "false".

immediateValidation controls when in the JSF lifecycle the maxTotalSize, maxFileSize, maxFileCount and required validation will occur, marking the form as invalid and calling renderResponse, if necessary.

• true:  Validation done during ApplyRequestValues phase
• false:  Validation done during ProcessValidations phase
  • If immediate="true", then immediateValidation can not be set to false, since that would make the fileEntryListener be called before validation has occurred, so immediateValidation will automatically return a value of true.

Default is "true".

absolutePath, relativePath, useSessionSubdir and useOriginalFilename together determine where the uploaded files will be stored on the server's file-system.

absolutePath, or alternatively relativePath, determine the root directory into which files will be stored. If absolutePath is specified, then it is interpreted as an absolute path into the file-system. As well, it takes precedence if relativePath is also specified, erroneously. If relativePath is specified, it is interpreted as a path within the application deployment directory. The default is for, the root in which files are saved, to be the application deployment directory.

useSessionSubdir and useOriginalFilename are used to keep different files, from different users, from colliding with each other, in the save root.

When useSessionSubdir="false", files uploaded from different sessions will all be jumbled together. The default, of useSessionSubdir="true", separated files of different sessions, each user's file remain separate, and each time a given user logs back in, their files are kept separate from their previous logins' files. This simplified application processing and cleanup of each session's files.

When useOriginalFilename="true", files are saved on the server's file-system using their file name from the user's file-system. This might simplify processing, but could also be a security risk. As well, collisions may occur, where if different versions of the same file are uploaded over time, or different files from different directories, but which share the same file name, are uploaded, then the last one uploaded will overwrite earlier uploaded ones. The default, of useOriginalFilename="false", saves the uploaded files onto the server's file-system using uniquely generated file names.

maxTotalSize, maxFileSize and maxFileCount allow for setting quota constraints on upload operations. They are evaluated and enforced for each individual form submit and upload. Subsequent form submit and uploads do not take into account previous ones.There are no default values, as there are no default constraints. If any of these constraints are not met, then the form will be marked invalid, UpdateModel and InvokeApplication phases will not run, and none of the form fields will be set into the application's beans. When a fileEntry component is configured to allow uploading of multiple files in a single form submit, maxTotalSize and maxFileCount become more relevant.

• Individual files may have their sizes constrained by maxFileSize. If a file's size is greater than maxFilesSize, then it will fail uploading.
• If an application is concerned with the total size of all uploaded files in the aggregate, then maxTotalSize may be used to constrain the total size of all the files together. As each file is processed in sequence, when the maxTotalSize has been exceeded, the current file, and all subsequent files, will fail uploading. The previously processed files, which met the constraint, will have succeeded uploading.
• The maxFileCount constrains the number of files which may be uploaded in a single form submit by the one fileEntry component. As each file is processed in sequence, when the maxFileCount has been exceeded, the current file, and all subsequent files, will fail uploading. The previously processed files, which met the constraint, will have succeeded uploading.

required is used to specify that at least one file must be uploaded as part of the current form submit, for the form to be valid. If no file was uploaded, then the form will be marked invalid, UpdateModel and InvokeApplication phases will not run, and none of the form fields will be set into the application's beans.

The required property does not look into whether the uploaded files succeeded or not, just that any files were attempted to be uploaded. The other constraints, which can fail uploads, will themselves invalidate the form.

The criteria for required to invalidate the form is:

• A full form submit, not using AJAX, occured
• No files were uploaded by this fileEntry component
• The required property is true, for this fileEntry component
• This fileEntry component is executing in the lifecycle. For example:
  • The submitting component did not do a single submit
  • The submitting component did not have an f:ajax tag, which excluded the fileEntry component from executing
• The submitting component did not do a partial submit. That disables required processing

What to expect when some files fail validation in a multiple file upload? When you try to upload multiple files and some of them are rejected because of size, type or any other validation rule, you can expect that the files that passed validation will be saved in the server, and the file entry listener will fire, and you'll be able to see what files were successfully uploaded and which weren't by examining the FileEntryResults.