org.icefaces.ace.component.fileentry
Class FileEntryBase

java.lang.Object
  javax.faces.component.UIComponent
      javax.faces.component.UIComponentBase
          org.icefaces.ace.component.fileentry.FileEntryBase

All Implemented Interfaces:

java.util.EventListener, javax.faces.component.PartialStateHolder, javax.faces.component.StateHolder, javax.faces.component.TransientStateHolder, javax.faces.event.ComponentSystemEventListener, javax.faces.event.FacesListener, javax.faces.event.SystemEventListenerHolder, IFileEntry

Direct Known Subclasses:

FileEntry

public class FileEntryBase
extends javax.faces.component.UIComponentBase
implements IFileEntry

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.

Nested Class Summary

protected static class

FileEntryBase.PropertyKeys

Field Summary

static java.lang.String	COMPONENT_TYPE
static java.lang.String	RENDERER_TYPE

Fields inherited from class javax.faces.component.UIComponent

ATTRS_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 Summary

FileEntryBase()

Method Summary

java.lang.String	getAbsolutePath() Return the value of the absolutePath property.
java.lang.String	getFamily()
javax.el.MethodExpression	getFileEntryListener() Return the value of the fileEntryListener property.
java.lang.String	getLabel() Return the value of the label property.
int	getMaxFileCount() Return the value of the maxFileCount property.
java.lang.String	getMaxFileCountMessage() Return the value of the maxFileCountMessage property.
long	getMaxFileSize() Return the value of the maxFileSize property.
java.lang.String	getMaxFileSizeMessage() Return the value of the maxFileSizeMessage property.
long	getMaxTotalSize() Return the value of the maxTotalSize property.
java.lang.String	getMaxTotalSizeMessage() Return the value of the maxTotalSizeMessage property.
java.lang.String	getRelativePath() Return the value of the relativePath property.
java.lang.String	getRequiredMessage() Return the value of the requiredMessage property.
FileEntryResults	getResults() Return the value of the results property.
int	getSize() Return the value of the size property.
java.lang.String	getStyle() Return the value of the style property.
java.lang.String	getStyleClass() Return the value of the styleClass property.
java.lang.Integer	getTabindex() Return the value of the tabindex property.
boolean	isDisabled() Return the value of the disabled property.
boolean	isImmediate() Return the value of the immediate property.
boolean	isImmediateValidation() Return the value of the immediateValidation property.
boolean	isRequired() Return the value of the required property.
boolean	isUseOriginalFilename() Return the value of the useOriginalFilename property.
boolean	isUseSessionSubdir() Return the value of the useSessionSubdir property.
void	setAbsolutePath(java.lang.String absolutePath) Set the value of the absolutePath property.
void	setDisabled(boolean disabled) Set the value of the disabled property.
void	setFileEntryListener(javax.el.MethodExpression fileEntryListener) Set the value of the fileEntryListener property.
void	setImmediate(boolean immediate) Set the value of the immediate property.
void	setImmediateValidation(boolean immediateValidation) Set the value of the immediateValidation property.
void	setLabel(java.lang.String label) Set the value of the label property.
void	setMaxFileCount(int maxFileCount) Set the value of the maxFileCount property.
void	setMaxFileCountMessage(java.lang.String maxFileCountMessage) Set the value of the maxFileCountMessage property.
void	setMaxFileSize(long maxFileSize) Set the value of the maxFileSize property.
void	setMaxFileSizeMessage(java.lang.String maxFileSizeMessage) Set the value of the maxFileSizeMessage property.
void	setMaxTotalSize(long maxTotalSize) Set the value of the maxTotalSize property.
void	setMaxTotalSizeMessage(java.lang.String maxTotalSizeMessage) Set the value of the maxTotalSizeMessage property.
void	setRelativePath(java.lang.String relativePath) Set the value of the relativePath property.
void	setRequired(boolean required) Set the value of the required property.
void	setRequiredMessage(java.lang.String requiredMessage) Set the value of the requiredMessage property.
void	setResults(FileEntryResults results) Set the value of the results property.
void	setSize(int size) Set the value of the size property.
void	setStyle(java.lang.String style) Set the value of the style property.
void	setStyleClass(java.lang.String styleClass) Set the value of the styleClass property.
void	setTabindex(java.lang.Integer tabindex) Set the value of the tabindex property.
void	setUseOriginalFilename(boolean useOriginalFilename) Set the value of the useOriginalFilename property.
void	setUseSessionSubdir(boolean useSessionSubdir) Set the value of the useSessionSubdir property.

Methods inherited from class javax.faces.component.UIComponentBase

addClientBehavior, addFacesListener, broadcast, clearInitialState, decode, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processDecodes, processRestoreState, processSaveState, processUpdates, processValidators, queueEvent, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class javax.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, visitTree

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPONENT_TYPE

public static final java.lang.String COMPONENT_TYPE

See Also:

Constant Field Values

RENDERER_TYPE

public static final java.lang.String RENDERER_TYPE

See Also:

Constant Field Values

Constructor Detail

FileEntryBase

public FileEntryBase()

Method Detail

getFamily

public java.lang.String getFamily()

Specified by:

getFamily in class javax.faces.component.UIComponent

setAbsolutePath

public void setAbsolutePath(java.lang.String absolutePath)

Set the value of the absolutePath property.

Contents: The absolute path, into the file-system, where the files should be stored. If specified, this takes precedence over the alternative property relativePath.

Specified by:

setAbsolutePath in interface IFileEntry

getAbsolutePath

public java.lang.String getAbsolutePath()

Return the value of the absolutePath property.

Contents: The absolute path, into the file-system, where the files should be stored. If specified, this takes precedence over the alternative property relativePath.

Specified by:

getAbsolutePath in interface IFileEntry

setDisabled

public void setDisabled(boolean disabled)

Set the value of the disabled property.

Contents: Defines 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.

Specified by:

setDisabled in interface IFileEntry

isDisabled

public boolean isDisabled()

Return the value of the disabled property.

Contents: Defines 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'.

Specified by:

isDisabled in interface IFileEntry

setFileEntryListener

public void setFileEntryListener(javax.el.MethodExpression fileEntryListener)

Set the value of the fileEntryListener property.

Contents: MethodExpression, 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.

Specified by:

setFileEntryListener in interface IFileEntry

getFileEntryListener

public javax.el.MethodExpression getFileEntryListener()

Return the value of the fileEntryListener property.

Contents: MethodExpression, 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.

Specified by:

getFileEntryListener in interface IFileEntry

setImmediate

public void setImmediate(boolean immediate)

Set the value of the immediate property.

Contents: When 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.

Specified by:

setImmediate in interface IFileEntry

isImmediate

public boolean isImmediate()

Return the value of the immediate property.

Contents: When 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'.

Specified by:

isImmediate in interface IFileEntry

setImmediateValidation

public void setImmediateValidation(boolean immediateValidation)

Set the value of the immediateValidation property.

Contents: Initially, 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.

Specified by:

setImmediateValidation in interface IFileEntry

isImmediateValidation

public boolean isImmediateValidation()

Return the value of the immediateValidation property.

Contents: Initially, 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'.

Specified by:

isImmediateValidation in interface IFileEntry

setLabel

public void setLabel(java.lang.String label)

Set the value of the label property.

Contents: When faces messages are shown for this component, the label is how this component is represented to the user

Specified by:

setLabel in interface IFileEntry

getLabel

public java.lang.String getLabel()

Return the value of the label property.

Contents: When faces messages are shown for this component, the label is how this component is represented to the user

Specified by:

getLabel in interface IFileEntry

setMaxFileCount

public void setMaxFileCount(int maxFileCount)

Set the value of the maxFileCount property.

Contents: The 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.

Specified by:

setMaxFileCount in interface IFileEntry

getMaxFileCount

public int getMaxFileCount()

Return the value of the maxFileCount property.

Contents: The 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'.

Specified by:

getMaxFileCount in interface IFileEntry

setMaxFileCountMessage

public void setMaxFileCountMessage(java.lang.String maxFileCountMessage)

Set the value of the maxFileCountMessage property.

Contents: The localised message format string to use when showing a faces message, when the maxFileCount has been exceeded

Specified by:

setMaxFileCountMessage in interface IFileEntry

getMaxFileCountMessage

public java.lang.String getMaxFileCountMessage()

Return the value of the maxFileCountMessage property.

Contents: The localised message format string to use when showing a faces message, when the maxFileCount has been exceeded

Specified by:

getMaxFileCountMessage in interface IFileEntry

setMaxFileSize

public void setMaxFileSize(long maxFileSize)

Set the value of the maxFileSize property.

Contents: The 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.

Specified by:

setMaxFileSize in interface IFileEntry

getMaxFileSize

public long getMaxFileSize()

Return the value of the maxFileSize property.

Contents: The 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'.

Specified by:

getMaxFileSize in interface IFileEntry

setMaxFileSizeMessage

public void setMaxFileSizeMessage(java.lang.String maxFileSizeMessage)

Set the value of the maxFileSizeMessage property.

Contents: The localised message format string to use when showing a faces message, when the maxSizePerFile has been exceeded

Specified by:

setMaxFileSizeMessage in interface IFileEntry

getMaxFileSizeMessage

public java.lang.String getMaxFileSizeMessage()

Return the value of the maxFileSizeMessage property.

Contents: The localised message format string to use when showing a faces message, when the maxSizePerFile has been exceeded

Specified by:

getMaxFileSizeMessage in interface IFileEntry

setMaxTotalSize

public void setMaxTotalSize(long maxTotalSize)

Set the value of the maxTotalSize property.

Contents: The 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.

Specified by:

setMaxTotalSize in interface IFileEntry

getMaxTotalSize

public long getMaxTotalSize()

Return the value of the maxTotalSize property.

Contents: The 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'.

Specified by:

getMaxTotalSize in interface IFileEntry

setMaxTotalSizeMessage

public void setMaxTotalSizeMessage(java.lang.String maxTotalSizeMessage)

Set the value of the maxTotalSizeMessage property.

Contents: The localised message format string to use when showing a faces message, when the maxSizeTotal has been exceeded

Specified by:

setMaxTotalSizeMessage in interface IFileEntry

getMaxTotalSizeMessage

public java.lang.String getMaxTotalSizeMessage()

Return the value of the maxTotalSizeMessage property.

Contents: The localised message format string to use when showing a faces message, when the maxSizeTotal has been exceeded

Specified by:

getMaxTotalSizeMessage in interface IFileEntry

setRelativePath

public void setRelativePath(java.lang.String relativePath)

Set the value of the relativePath property.

Contents: The 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.

Specified by:

setRelativePath in interface IFileEntry

getRelativePath

public java.lang.String getRelativePath()

Return the value of the relativePath property.

Contents: The 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.

Specified by:

getRelativePath in interface IFileEntry

setRequired

public void setRequired(boolean required)

Set the value of the required property.

Contents: Similar 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.

Specified by:

setRequired in interface IFileEntry

isRequired

public boolean isRequired()

Return the value of the required property.

Contents: Similar 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'.

Specified by:

isRequired in interface IFileEntry

setRequiredMessage

public void setRequiredMessage(java.lang.String requiredMessage)

Set the value of the requiredMessage property.

Contents: The localised message format string to use when showing a faces message, when the component has become invalid, due to no files being uploaded

Specified by:

setRequiredMessage in interface IFileEntry

getRequiredMessage

public java.lang.String getRequiredMessage()

Return the value of the requiredMessage property.

Contents: The localised message format string to use when showing a faces message, when the component has become invalid, due to no files being uploaded

Specified by:

getRequiredMessage in interface IFileEntry

setResults

public void setResults(FileEntryResults results)

Set the value of the results property.

Contents: Maintains 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.

Specified by:

setResults in interface IFileEntry

getResults

public FileEntryResults getResults()

Return the value of the results property.

Contents: Maintains 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.

Specified by:

getResults in interface IFileEntry

setSize

public void setSize(int size)

Set the value of the size property.

Contents: The 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.

Specified by:

setSize in interface IFileEntry

getSize

public int getSize()

Return the value of the size property.

Contents: The 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.

Specified by:

getSize in interface IFileEntry

setStyle

public void setStyle(java.lang.String style)

Set the value of the style property.

Contents: Custom 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.

Specified by:

setStyle in interface IFileEntry

getStyle

public java.lang.String getStyle()

Return the value of the style property.

Contents: Custom 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.

Specified by:

getStyle in interface IFileEntry

setStyleClass

public void setStyleClass(java.lang.String styleClass)

Set the value of the styleClass property.

Contents: Custom CSS style class(es) to use for this component. These style classes can be defined in your page or in a theme CSS file.

Specified by:

setStyleClass in interface IFileEntry

getStyleClass

public java.lang.String getStyleClass()

Return the value of the styleClass property.

Contents: Custom CSS style class(es) to use for this component. These style classes can be defined in your page or in a theme CSS file.

Specified by:

getStyleClass in interface IFileEntry

setTabindex

public void setTabindex(java.lang.Integer tabindex)

Set the value of the tabindex property.

Contents: tabindex of the component

Specified by:

setTabindex in interface IFileEntry

getTabindex

public java.lang.Integer getTabindex()

Return the value of the tabindex property.

Contents: tabindex of the component

Specified by:

getTabindex in interface IFileEntry

setUseOriginalFilename

public void setUseOriginalFilename(boolean useOriginalFilename)

Set the value of the useOriginalFilename property.

Contents: Uploaded 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.

Specified by:

setUseOriginalFilename in interface IFileEntry

isUseOriginalFilename

public boolean isUseOriginalFilename()

Return the value of the useOriginalFilename property.

Contents: Uploaded 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'.

Specified by:

isUseOriginalFilename in interface IFileEntry

setUseSessionSubdir

public void setUseSessionSubdir(boolean useSessionSubdir)

Set the value of the useSessionSubdir property.

Contents: When 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.

Specified by:

setUseSessionSubdir in interface IFileEntry

isUseSessionSubdir

public boolean isUseSessionSubdir()

Return the value of the useSessionSubdir property.

Contents: When 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'.

Specified by:

isUseSessionSubdir in interface IFileEntry