JSF engine configuration parameters

In WebSphere® Application Server, you can configure the JavaServer Faces (JSF) engine configuration parameters for optimal performance in a production server environment and in a development environment.

The JSF engine parameters are case-sensitive. If the value specified for a parameter is composed of two or more words that are separated by spaces, you must add quotation marks around the value.

JSF options using SUN RI

Table 1. JSF options using SUN RI . The table shows SUN RI parameter names, descriptions, and default values.
SUN RI parameter name	Description	Default value
com.sun.faces.numberOfViewsInSession	Specifies the number of views that are stored in the session when server-side state saving is used. If set to `true` while client-side state saving is used, the parameter reduces the number of bytes sent to the client by compressing the state before it is encoded and written as a hidden field.	15
com.sun.faces.numberOfLogicalViews	Specifies the number of logical views that are stored in the session when Server-Side State Saving is used.	15
com.sun.faces.enableHighAvailability	If set to `true` while server-side state saving is used, a serialized representation of the view is stored on the server. This provides failover and server clustering support.	false
com.sun.faces.injectionProvider	Defines an injection provider that is used for JSF annotations.
com.sun.faces.serializationProvider	Defines a serialization provider that is used for serializing JSF objects into session.
com.sun.faces.responseBufferSize	Define the size of the response buffer for a JSF response.	1048
com.sun.faces.clientStateWriteBufferSize		8192
com.sun.faces.expressionFactory	Specifies the default EL Expression Factory to use.	org.apache.el.ExpressionFactoryImpl
com.sun.faces.clientStateTimeout	The timeout value used for client-side state saving. When the value set is reached, the state is lost.	infinite
com.sun.faces.displayConfiguration		false
com.sun.faces.validateXml	When set to `true`, tag library XML files and faces configuration XML files using schema are validated during application start.	false
com.sun.faces.verifyObjects		false
com.sun.faces.forceLoadConfiguration		false
com.sun.faces.disableVersionTracking		false
com.sun.faces.enableHtmTagLibValidator		false
com.sun.faces.prerefXHTML		false
com.sun.faces.compressViewState		true
com.sun.faces.compressJavaScript		true
com.sun.faces.sendPoweredByHeader		true
com.sun.faces.enableJSStyleHiding		false
com.sun.faces.writeStateAtFormEnd		true
com.sun.faces.enableLazyBeanValidation		true
com.sun.faces.enableLoadBundle11Compatibility		false
com.sun.faces.enableRestoreView11Compatibilty		false
com.sun.face.serializeServerState		false
com.ibm.ws.jsf.JSP_UPDATE_CHECK	This parameter monitors Faces JavaServer Pages (JSP) files for modifications and synchronizes a running server with the changes without restarting the server. If this parameter is set to `false` or removed from the deployment descriptor, any changes that are made to Faces JSP files might not display for the server until it is restarted. Set this parameter to `true` while you are developing and debugging the Faces JSP files to improve the performance of the development environment.
com.ibm.ws.jsf.JSF_IMPL_CHECK	Set the com.ibm.ws.jsf.JSF_IMPL_CHECK parameter to true to check at application restart if the SUN RI and MyFaces implementations were switched. If the implementation switched, then the runtime removes any generated JSP files from the temp directory and the JSP file is retranslated the next time it is requested.
com.ibm.ws.jsf.associateLabelWithId	The com.ibm.ws.jsf.associateLabelWithId custom property changes the rendering behavior for both the <h:selectOneRadio> and <h:selectManyCheckbox> components. The label no longer wraps the input element. Instead, each input element has a unique ID and the label is associated with that ID used for that attribute. Define and set the com.ibm.ws.jsf.associateLabelWithId context parameter to `true` in the web.xml file. Use the following code as an example. `<context-param> <description> Set to true to explicitly associate labels with their input elements for select one radio buttons and select many check box lists. </description> <param-name>com.ibm.ws.jsf.associateLabelWithId </param-name> <param-value>true</param-value> </context-param>`
com.ibm.ws.jsf.disableEnqueuedMessagesWarning	The com.ibm.ws.jsf.disableEnqueuedMessagesWarning custom property disables the following warning message: FacesMessage(s) have been enqueued, but may not have been displayed. When this property is set to `true` in the web.xml file, this warning message is not included in the SystemOut.log file. Avoid trouble: This context parameter applies only to JSF applications that use the Sun Reference Implementation (RI) for JSF implementation. Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM® i systems. You can also use HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL. Use the following code as an example of how to define and set the com.ibm.ws.jsf.disableEnqueuedMessagesWarning context parameter to `true` in the web.xml file. `<context-param> <description> Set to true to disable the following warning message: FacesMessage(s) have been enqueued, but might not have been displayed </description> <param-name> com.ibm.ws.jsf.disableEnqueuedMessagesWarning </param-name> <param-value>true</param-value> </context-param>`
com.ibm.ws.jsf.disableStylePassthroughForCheckboxList	This custom property prevents passing the style information into the items in the check box list. This property defaults to `false` to maintain the current behavior. Define and set the com.ibm.ws.jsf.disableStylePassthroughForCheckboxList context parameter to `true` in the web.xml file to prevent passing style information into items in the check box list. Use the following code as an example. `<context-param> <description> Set to true if style information should not be passed into items of check box list </description> <param-name> com.ibm.ws.jsf.disableStylePassthroughForCheckboxList </param-name> <param-value>true</param-value> </context-param>`
com.ibm.ws.jsf.DISABLE_UIDATA_NESTED_CHECK	The com.ibm.ws.jsf.DISABLE_UIDATA_NESTED_CHECK custom property determines whether unique IDs are generated for UIData components that are nested inside iterator components that are not UIData components. When this property is set to `true` in the web.xml file, unique IDs are generated for UIData components even if they are nested inside iterator components that are not UIData components. When this property is set to `false`, if a JSF dataTable component is nested within a component that does not extend UIData, such as the Java Widget Library (JWL) dataIterator component, the IDs that are generated for the rows do not increment properly. This situation can result in duplicate IDs being assigned to multiple JSF components. Use the following code as an example of how to define and set the com.ibm.ws.jsf.DISABLE_UIDATA_NESTED_CHECK context parameter to `true` in the web.xmlfile. `<context-param> <description> Set to true to enable unique IDs to be generated for UIData components evenif they are nested inside iterator components that are not UIData components. </description> <param-name> com.ibm.ws.jsf.DISABLE_UIDATA_NESTED_CHECK </param-name> <param-value>true</param-value> </context-param>`
com.ibm.ws.jsf.loadExternalDtd	When parsing the faces-config.xml file from included libraries, the Faces configuration parser attempts to load the DTD even when validation is disabled. The Faces configuration parser uses a SAXParser to read the faces-config.xml. The default behavior of the SAXParser parser is to always load the DTD even if validation is disabled. This behavior can lead to errors initializing the Faces Servlet on systems isolated from the internet. In your web.xml file, set the com.ibm.ws.jsf.loadExternalDtd context parameter to `false` to have the Faces configuration parser set the "http://apache.org/xml/features/nonvalidating/load-external-dtd" feature to false. `<context-param> <description> When set to false, this property sets a feature on the SAX parser to prevent loading the external DTD. </description> <param-name>com.ibm.ws.jsf.loadExternalDtd</param-name> <param-value>false</param-value> </context-param>`
com.ibm.ws.jsf.REMOVE_CHILD_FROM_FACET	For a duplicate id, an IllegalStateException can occur when using the facet component that contains an <h:outputStylesheet/>. When using a facet component such as the following: `<f:facet name="text"> <h: outputStylesheet: library="theme" name="stylesheet.css"/> </f:facet>` the following exception can occur due to a duplicate id being found by JSF: `java.lang.IllegalStateException: component with duplicate id"dup_id" found at org.apache.myfaces.view.facelets.DefaultFaceletsStateManagementStrategy. checkIds(DefaultFaceletsStateManagementStrategy.java:781)` The JSF container is updated to ensure that a duplicate id does not occur, but you must enable com.ibm.ws.jsf.REMOVE_CHILD_FROM_FACET to `true` so that the JSF container processing for duplicate id is activated.	false
enableRestoreView11Compatibility	A JSF 1.2 application might create the ViewExpiredException exception under load when using the Sun Reference Implementation. If your view is not found in session, you can use a compatibility mode in JSF to create a new view. This can have adverse behaviors because it is a new view and items that are usually in the view, such as state, are no longer available. Use the following code as an example to set the com.sun.faces.enableRestoreView11Compatibility context parameter to `true` in the web.xml file. This is only applicable when the Sun Reference Implementation is in use. `<context-param> <param-name> com.sun.faces.enableRestoreView11Compatibility </param-name> <param-value>true</param-value> </context-param>`
enableViewStateIdRendering	The com.sun.faces.enableViewStateIdRendering custom property controls the rendering of the id attribute of the javax.faces.ViewState hidden field. Use the following code as an example to set the com.sun.faces.enableViewStateIdRendering context parameter to `true` in the web.xml file. `<context-param> <param-name>com.sun.faces.enableViewStateIdRendering </param-name> <param-value>true</param-value> </context-param>`
org.apache.el.parser.COERCE_TO_ZERO	Allows for the expression language (EL) that WebSphere Application Server uses to coerce null and empty string integer values to a 0 value or for NOT allowing a coerce to a 0 value and retaining the null or empty string integer. The default is `true` and permits a null or empty string integer value to be coerced to a 0 value. Important: To keep a null value from being coerced to a 0 value in a MyFaces application, the following context parameter in the `web.xml` of the application: should be set to ensure that all possible instances of an empty or null value are inhibited from being coerced to zero. `<context-param> <param-name>javax.faces. INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL </param-name> <param-value>true</param-value> </context-param>` You set the `org.apache.el.parser.COERCE_TO_ZERO` property using the administrative console. Expand Servers, and then select WebSphere Application Servers. Click on the appropriate server from the list. Under Server Infrastructure, expand Java and Process Management > Click on Process definition. Under Additional Properties, click Java virtual machine. Under Additional Properties, click Custom properties. Click New and add the `org.apache.el.parser.COERCE_TO_ZERO` property with the value of `false` if you do NOT want a null value coerced to zero. Click Save to save the change and restart the WebSphere Application Server to ensure that the change takes place.	true

JSF options for MyFaces

Table 2. JSF options for MyFaces . The table shows JSF parameter names, descriptions, and default values.
JSF parameter name	Description	Default value
org.apache.myfaces.RESOURCE_VIRTUAL_PATH		/faces/myFacesExtensionResource
org.apache.myfaces.PRETTY_HTML	If this value is true, rendered HTML code is formatted so that it is human-readable. Additional line separators and blank space are written that do not influence the HTML code.	true
org.apache.myfaces.ALLOW_JAVASCRIPT	This parameter tells MyFaces if javascript code is allowed in the rendered HTML output. If javascript is allowed, command_link anchors have javascript code that submits the corresponding form. If javascript is not allowed, the state saving information and nested parameters are added as URL parameters.	true
org.apache.myfaces.DETECT_JAVASCRIPT		false
org.apache.myfaces.AUTO_SCROLL	If true, a javascript function is rendered that can restore the former vertical scroll on every request. This feature is convenient if you have pages with long lists and you do not want the browser page to jump to the beginning of the page if you trigger a link or button action that stays on the same page.	false
org.apache.myfaces.ADD_RESOURCE_CLASS		org.apache.myfaces.renderkit.html.util.DefaultAddResource
org.apache.myfaces.CHECK_EXTENSIONS_FILTER	This parameter checks for a properly-configured Extensions-Filter if it is needed by the web application.	true
org.apache.myfaces.COMPRESS_STATE_IN_SESSION	Set this option to `true` to compress the serialized state before it is written to the session. If this option is set to `false`, the state is not compressed. This option is only applicable if the state saving method is set to server and if org.apache.myfaces.SERIALIZE_STATE_IN_SESSION is set to `true`.	true
org.apache.myfaces.FLASH_SCOPE_DISABLED	Set this context parameter to `true` to disable the Flash Scope which results in the cookie not being sent.	false
org.apache.myfaces.NUMBER_OF_VIEWS_IN_SESSION	Defines the number of the latest views that are stored in session. This option is only applicable if the state saving method is set to server.	20
org.apache.myfaces.READONLY_AS_DISABLED_FOR_SELECTS		true
org.apache.myfaces.SERIALIZE_STATE_IN_SESSION	Set this option to `true` to serialize the state to a byte stream before it is written to the session. If this option is set to `false`, the state is not serialized to a byte stream. This option is only applicable if the state saving method is set to server.	true
org.apache.myfaces.STRICT_JSF_2_CC_EL_RESOLVER	Ensures that, when a getType() is called over the source EL expression, components working with chained EL expressions can use the metadata information that composite: attribute added. Setting this property to `true` disables this function.	false
org.apache.el.parser.COERCE_TO_ZERO	Allows for the expression language (EL) that WebSphere Application Server uses to coerce null and empty string integer values to a 0 value or for NOT allowing a coerce to a 0 value and retaining the null or empty string integer. The default is `true` and permits a null or empty string integer value to be coerced to a 0 value. Important: To keep a null value from being coerced to a 0 value in a MyFaces application, the following context parameter in the `web.xml` of the application: should be set to ensure that all possible instances of an empty or null value are inhibited from being coerced to zero. `<context-param> <param-name>javax.faces. INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL </param-name> <param-value>true</param-value> </context-param>` You set the `org.apache.el.parser.COERCE_TO_ZERO` property using the administrative console. Expand Servers, and then select WebSphere Application Servers. Click on the appropriate server from the list. Under Server Infrastructure, expand Java and Process Management > Click on Process definition. Under Additional Properties, click Java virtual machine. Under Additional Properties, click Custom properties. Click New and add the `org.apache.el.parser.COERCE_TO_ZERO` property with the value of `false` if you do NOT want a null value coerced to zero. Click Save to save the change and restart the WebSphere Application Server to ensure that the change takes place.	true
org.apache.myfaces.DEBUG_PHASE_LISTENER	Enables the `DebugPhaseListener` in the Development Project Stage.	true
com.ibm.ws.jsf.disablealternatefacesconfigsearch	Disables MyFaces searching for META-INF/*.faces-config.xml for only the web application that this context parameter is set on. If the context parameter and the web container custom property are set, the context parameter takes precedence.	false
com.ibm.ws.jsf.fullyRestoreDynamicComponent	Set this option to `true` to correctly preserve components with dynamically created children.	false
com.ibm.ws.jsf.enableRemoveRestoredViewState	Set this option to `true` to resolve a ViewExpiredException exception in a multi-window scenario.	false
com.ibm.ws.jsf.updateFaceletContextKey	When a `<f:ajax/>` tag occurs in a JSF page under an `<ui:include/>` tag and the name that is referred to in the listener MethodExpression is redefined by a `<ui:param/>` in the `<ui:include/>`, the variable can be resolved incorrectly. Set the web.xml option to `true` to enable the new behavior.	false

JSF options using SUN RI or MyFaces

The following options are valid for both the SUN RI and the MyFaces implementations.

Table 3. JSF options using SUN RI or MyFaces . The table shows JSF parameter names, descriptions, and default values.
JSF parameter name	Description	Default value
javax.faces.STATE_SAVING_METHOD	Specifies the location where state information is saved. Valid values are `server`, which is saved in HttpSession, and `client`, which is saved as a hidden field in the form. Note: If you use javax.faces.STATE_SAVING_METHOD to save on the client side, there are limitations between JavaServer Pages Standard Tag Library (JSTL) and Facelets. For certain processing scenarios, JSF Facelets support has limitations in processing all of the client-side saving requirements for Facelets. For these scenarios, server-side saving is an option. If client-side state saving is a requirement, then use JSF tags.	server
javax.faces.CONFIG_FILES	Use this parameter to specify a comma-delimited list of context-relative resource paths under which the JSF implementation looks for application configuration resources before loading a configuration resource named /WEB-INF/facesconfig.xml, if a resource exists.	n/a
javax.faces.DEFAULT_SUFFIX	Specifies the default suffix for extension-mapped resources that contain JSF components.	.jsp
javax.faces.LIFECYCLE_ID	Use this parameter to configure an alternate life cycle ID.	n/a
com.ibm.ws.jsf.JSF_IMPL_CHECK	Specifies that the JSP files in a web module must be recompiled when the application is restarted because the implementation of JSF that is used has changed. After the application is restarted, the next time a JSP file is accessed for this module the JSP file is recompiled against the selected implementation of JSF specified in the administration console. Subsequent calls to the JSP file do not recompile. The default setting for this option is false. Use this option for development and not in a production environment.	n/a

Sun RI context parameters that have an equivalent behavior in MyFaces

Table 4. Sun RI context parameters and equivalent MyFaces behavior . The table shows SUN RI parameters names and MyFaces equivalent.
SUN RI parameter name	Description	RI default	MyFaces equivalent	MyFaces default
com.sun.faces.numberOfViewsInSession	Defines the maximum number of serialized views stored in the session. Works with server state saving.	15	org.apache.myfaces.NUMBER_OF_VIEWS_IN_SESSION	20
com.sun.faces.compressViewState	When true the view is compressed after it is serialized and before base64 encoded. Works with client state saving. As of 1.2_09, this option also affects server-side state saving when com.sun.faces.serializeServerState is set to true (this has a large impact of the size of the state in the session when using this option, at the expense of more CPU.)	true	org.apache.myfaces.COMPRESS_STATE_IN_CLIENT for client-side state saving or org.apache.myfaces.COMPRESS_STATE_IN_SESSION for server-side state saving	false for client-side state saving, true for server-side state saving
com.sun.faces.validateXml	When true JSF validates the configuration files.	false	org.apache.myfaces.VALIDATE	false
com.sun.faces.injectionProvider	This parameter specifies a class that implements the InjectionProvider.	n/a	injection provider is provided by the WebSphere Application Server run time	n/a
com.sun.faces.serializationProvider	This parameter specifies a class that implements the SerializationProvider SPI. This implementation represents a hook the JSF implementation uses to enable using alternate Serialization implementations.	n/a	org.apache.myfaces.SERIAL_FACTORY - class must implement org.apache.myfaces.shared_impl.util.serial.SerialFactory SPI instead of com.sun.faces.spi.SerializationProvider	n/a
com.sun.faces.enabledJSStyleHiding	If true, inline JavaScript rendered by the HTML ResponseWriter implementation is rendered so that the script is hidden from older browser implementations.	false	org.apache.myfaces.WRAP_SCRIPT_CONTENT_WITH_XML_COMMENT_TAG	true
com.sun.faces.serializeServerState	If enabled the component state (not the tree) is serialized before being stored in the session. This might be desirable for applications that have issues with view state being sensitive to model changes.	false	org.apache.myfaces.SERIALIZE_STATE_IN_SESSION	true

Note: In previous releases of WebSphere Application Server, when using javax.faces.component.UIComponent.findComponent (String expression), an incorrect UIComponent might be returned.

In this release of WebSphere Application Server, the javax.faces.component.UIComponent.findComponent has been updated to return the correct UIComponent. The following JSF context parameter must be set to true: com.ibm.ws.jsf.FIND_COMPONENT_RECURSE_CHILD_ID.