ICEfaces ACE Components
Tag fileEntry


The FileEntry component allows for uploading files to the server within a form submit POST. The actual POST is non-AJAX, but leverages ICEfaces to return incremental page updates. The upload occurs within as single JSF lifecycle, along with the form's other component processing, allowing applications to handle input field validation together with file content validation, for model coherency. As well, server push is not necessary for receiving the rendered view from the lifecycle in which the files were uploaded. The progress indicator is built-in, and will default to indeterminate mode. If server push is enabled, then the component will automatically push progress information to the indicator, and once that has been received, the indicator will automatically switch to display the incrementalprogress bar. The progress pushes are rate limited to be no more frequent than once every 2 seconds, and are only sent at 1% progress increments.

For more information, see the FileEntry Wiki Documentation.


Tag Information
Tag Classorg.icefaces.ace.component.fileentry.FileEntryTag
TagExtraInfo ClassNone
Body ContentJSP
Display NameNone

Attributes
NameRequiredRequest-timeTypeDescription
absolutePathnotruejava.lang.StringThe absolute path, into the file-system, where the files should be stored. If specified, this takes precedence over the alternative property relativePath.
acceptTypenotruejava.lang.StringThe MIME type of the files that are accepted by this component. The second term in the MIME type can be an asterisk to indicate that all files of a general category are accepted (e.g. acceptType="image/*" would accept all image files).
accesskeynotruejava.lang.StringAccess key that, when pressed, transfers focus to this component.
autoUploadnotruebooleanWhen this property is true, once the user selects the file(s) to upload, the upload will immediately commence, without need to click an upload button. Default = 'false'.
bindingnotruejavax.el.ValueExpressionUsing an EL expression, bind the component reference to a bean property, so that the component may be accessed in the bean.
callbacknotrueorg.icefaces.ace.component.fileentry.FileEntryCallbackSpecify a reference to a FileEntryCallback instance using a ValueExpression. Using this will result in the uploaded files not being written to the file system, and so precludes the absolutePath, relativePath, useSessionSubdir, and useOriginalFilename properties. This property supports scenarios where the uploaded files will be stored in a database, or streamed through to elsewhere, or virus scanned, or otherwise processed before being saved.
disablednotruebooleanDefines whether or not the component is disabled. When disabled='true', this component is unable to receive focus and cannot be interacted with by the user. Default = 'false'.
fileEntryListenernotruejavax.el.MethodExpressionMethodExpression, which must evaluate to a public method that takes an FileEntryEvent as a parameter, with a return type of void or an Object whose toString method will be used to produce a navigation outcome, much like how an action method works with a UICommand. Invoked after file(s) have been uploaded, during a lifecycle phase that is determined by the immediate property. It can be used to retrieve the FileEntryResults object from the results property of the FileEntry component, giving access to the status information of the successfully, and unsuccessfully, uploaded files.
idnotruejava.lang.StringThe component identifier for this component. This value must be unique within the closest parent component that is a naming container.
immediatenotruebooleanWhen true, the fileEntryListener will be invoked at the end of the APPLY_REQUEST_VALUES phase. Otherwise, it will be invoked just before rendering, so that the application will receive the event, regardless of whether the form has passed validation or not. Default = 'false'.
immediateValidationnotruebooleanInitially, validation of maxTotalSize, maxFileSize, maxFileCount, and required was fixed at APPLY_REQUEST_VALUES phase for technical reasons. Now that it can happen in PROCESS_VALIDATIONS, there are backwards compatibility constraints, so it's tied off of this new property instead of the typical immediate property. And this property's default value must give the pre-existing behaviour, not the newly available one. Validation must happen before the FileEntryEvent is broadcast and the fileEntryListener is invoked, so if immediate is true, then immediateValidation must be true as well. Baring that constraint, when immediateValidation is false, validation will occur in PROCESS_VALIDATIONS phase, otherwise when immediateValidation is true or unspecified, it will occur during APPLY_REQUEST_VALUES phase. Default = 'true'.
labelnotruejava.lang.StringWhen faces messages are shown for this component, the label is how this component is represented to the user
maxFileCountnotrueintThe maximum number of files that may be uploaded, per form submit upload operation, by this one component. Any files uploaded, beyond this count, will be discarded. Any subsequent form submit which uploads files will restart the counting at zero. Default = '10'.
maxFileCountMessagenotruejava.lang.StringThe localised message format string to use when showing a faces message, when the maxFileCount has been exceeded
maxFileSizenotruelongThe maximum amount of bytes allowed, that each individual file may have. If a file exceeds both maxFileSize and maxTotalSize, then maxFileSize will be the reported error. If a file size exceeds maxFileSize, it is completely discarded. Default = 'Long.MAX_VALUE'.
maxFileSizeMessagenotruejava.lang.StringThe localised message format string to use when showing a faces message, when the maxSizePerFile has been exceeded
maxTotalSizenotruelongThe maximum amount of bytes allowed, in total, for all of the files uploaded, together. If, for example, three files are uploaded, and the second one exceeds maxTotalSize, then the second and third files will be discarded. Default = 'Long.MAX_VALUE'.
maxTotalSizeMessagenotruejava.lang.StringThe localised message format string to use when showing a faces message, when the maxSizeTotal has been exceeded
messagePersistencenotruebooleanInput components add conversion and validation faces messages on every execute. When this is true, this component will add its upload success and failure on every execute, otherwise, when false, it will only add the faces messages when an upload occurs. Note: false precludes faces messages from ever being added. Default = 'true'.
multiplenotruebooleanAllows for multiple files to be selected, and uploaded all together. In modern browsers this can be done by selecting several files at once in the file selection dialog, and in all browsers the file selection dialog can be used multiple times in succession to add more files to be uploaded. Default = 'false'.
relativePathnotruejava.lang.StringThe relative path, inside of the web application deployment root directory, in the file-system, where the files should be stored. If specified, the alternative property, absolutePath, takes precedence over this property. If neither are specified, then the file is stored directly inside the deployment root directory.
renderednotruebooleanReturn true if this component (and its children) should be rendered during the Render Response phase of the request processing lifecycle. Default = 'true'.
requirednotruebooleanSimilar to required property on input components, when true, this states that at least one file must be selected, and uploaded, by this component, when the form is submitted. Default = 'false'.
requiredMessagenotruejava.lang.StringThe localised message format string to use when showing a faces message, when the component has become invalid, due to no files being uploaded
resultsnotrueorg.icefaces.ace.component.fileentry.FileEntryResultsMaintains the results of the most recent file upload operation. From this, applications can retrieve the uploaded files' information, such as the file name, MIME content type, size, location where the file has been stored, and status of the success of the upload. If saving a FileEntryResults object or FileEntryResults.FileInfo objects, in your application, then save a clone of the objects, instead.
sizenotrueintThe size attribute is used to specify how many characters wide the file selection will display. Default: no size attribute will be rendered; determined by browser.
stylenotruejava.lang.StringCustom inline CSS styles to use for this component. These styles are generally applied to the root DOM element of the component. This is intended for per-component basic style customizations. Note that due to browser CSS precedence rules, CSS rendered on a DOM element will take precedence over the external stylesheets used to provide the ThemeRoller theme on this component. If the CSS properties applied with this attribute do not affect the DOM element you want to style, you may need to create a custom theme styleClass for the theme CSS class that targets the particular DOM elements you wish to customize.
styleClassnotruejava.lang.StringCustom CSS style class(es) to use for this component. These style classes can be defined in your page or in a theme CSS file.
tabindexnotruejava.lang.Integertabindex of the component
useOriginalFilenamenotruebooleanUploaded files' names, as they were on the user's file-system, are always provided to the application, via the FileEntryResults.FileInfo.fileName property. By default, the fileEntry component will store the uploaded files on the server's file-system using a unique naming convention, to ensure that new files do not over-write older files, and that the names do not create security issues. The application may then implement its own policy of maintaining old files or over-writing them, as well as vetting file names based on any particular rules specific to their deployment operating system. Alternatively, they application may simply set this property to true, so that uploaded files will be saved using the user's file name, which will cause any pre-existing file using that name to be over-written. Default = 'false'.
useSessionSubdirnotruebooleanWhen constructing the path in which to save the files, whether it be in the directory specified by the absolutePath property, or inside of the web application deployment root directory, or inside a sub-directory of that, as specified by the relativePath property, when useSessionSubdir is true, then an additional sub-directory, will be used, that is the session id, to separate file uploads from different sessions, from each other. Default = 'true'.

Variables
No Variables Defined.


Output Generated by Tag Library Documentation Generator. Java, JSP, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-4 Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054, U.S.A. All Rights Reserved.