Monday, September 28, 2015

What Mojarra context parameters are available and what do they do?

Preface

Previously, on the GlassFish wiki page you could find an overview of all Mojarra specific web.xml context parameters (those starting with com.sun.faces), specifically here: wikis.oracle.com/display/GlassFish/JavaServerFacesRI. However, since Oracle changed one and other on the Internet again (wikis and blogs were shut down without proper redirecting and/or replacement), all links to that page suddenly became dead.

Fortunately, there's the web archive where I could recover the most recent snapshot and copy into this blog, so Mojarra users can find it by the usual search engines. Moreover, I've added a bunch of missing ones based on com.sun.faces.config.WebConfiguration class. The below listed available context parameters are clearly categorized and default values are valid as per Mojarra 2.2.11, whereby the deprecated and unused ones are already removed.

For standard JSF context parameters (those starting with javax.faces), head over to JSF specification chapter 11.1.3 or this Stack Overflow answer.

State saving related context parameters

Name Description Default Since
com.sun.faces.clientStateTimeout Maximum time, in seconds, that client state will be considered valid by the default StateManager/ResponseStateManager implementations. If the time between requests exceeds the configured time, a javax.faces.application.ViewExpiredException. will be thrown. It is important to note that if this feature is enabled, and client requests are recieved with view state produced from a previous version, the ViewExpiredException will be thrown immediately. NONE 1.2_05
com.sun.faces.clientStateWriteBufferSize The size, in bytes, of the buffer that is used to write client state. It should be noted, that the buffer used is split - half is for raw bytes, the other half is for the Base64 encoded characters of said bytes. So, for example, if the default, 8192, is used, then 4096 of that is used for the bytes, and the other 4096 is used for the Base64 encoded characters. 8192 1.2_01
com.sun.faces.compressViewState When true, the view is compressed after it is serialized and before base64 encoded. Works with client state saving only. As of 1.2_09, this option also impacts 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 of course) true 1.2
com.sun.faces.disableClientStateEncryption Since Mojarra 2.2, the client state is by default always encrypted. When true, the client state encryption is disabled. See also com.sun.faces.ClientStateSavingPassword - recommendations for actual password? false 2.2
com.sun.faces.enableClientStateDebugging When true, the client state will as test be unserialized before writing and any serialization exceptions will be logged along with a debug path to the cause of the serialization error false ???
com.sun.faces.generateUniqueServerStateIds If true, generate random server view state ids. If false, create server view state ids sequentially. This resembles closely the JSF 1.x behavior, but this is more sensitive to CSRF. true 2.0
com.sun.faces.numberOfLogicalViews Defines the maximum number of serialized views stored in the session. Works with server state saving only (note the implementation unintentionally has swapped the meaning, as we cannot change this without breaking what people have become used to we have updated this here). See com.sun.faces.numberOfViewsInSession vs com.sun.faces.numberOfLogicalViews for detail. 15 1.2
com.sun.faces.numberOfViewsInSession Definies the maximum number of serialized logical views per view. Works with server state saving only (note the implementation unintentionally has swapped the meaning, as we cannot change this without breaking what people have become used to we have updated this here) See com.sun.faces.numberOfViewsInSession vs com.sun.faces.numberOfLogicalViews for detail. 15 1.2
com.sun.faces.serializeServerState If enabled the component state (not the tree) will be serialized before being stored in the session. This may be desirable for applications that may have issues with view state being sensitive to model changes after state saving which are reflected back in view state. This has since JSF 2.2 been replaced by javax.faces.SERIALIZE_SERVER_STATE. false 1.2_05
com.sun.faces.writeStateAtFormEnd Per the renderkit doc specification, the state information for the view will be written out prior to closing the form tag. However, it may be desirable to have the state information written out after the opening form tag. If this is the case, specifiy this parameter in the web.xml with a value of false. true 1.2_04

View building/rendering related context parameters

Name Description Default Since
com.sun.faces.allowTextChildren If true, allow children of h:inputText and h:outputText to be rendered. In 1.2, they would always be rendered before the value of tag. As of 2.0, children of UIInput and UIOutput components will not be rendered by the default renderer implementations. Set this option to true if this behavior is required, but note that doing so may cause issues when using Ajax. See issue 1154 for details. false 2.0.0
com.sun.faces.autoCompleteOffOnViewState If false, don't use autocomplete="off" on view state hidden input field. This attribute is by default always rendered in order to fix a Firefox related bug, but it is invalid on a hidden input field as per w3 HTML validator. So, when false, then beware of the Firefox bug which may trigger "unexpected" ViewExpiredException. See issue 1129 for details. true 2.0.0
com.sun.faces.compressJavaScript If true, then the JavaScript rendered by h:commandLink will be compressed to reduce the amount of whitespace transmitted in the response. If false then the JavaScript will be rendered to the client in a well formatted manner. true 1.2_02
com.sun.faces.disableUnicodeEscaping By default any characters above a certain range will be escaped as either an HTML entity or a decimal reference. This behavior is not always desirable. To allow more flexibility how content is rendered to a client, this option was introduced. Valid configuration values are: false, true, and auto with false being the default. When the option value is false, Mojarra will continue to escaped no matter the response encoding type. If the configuration value is true, Then no escaping will occur assuming that the response encoding can properly handle all characters. If the configuration option is auto then the response encoding will be checked. If the encoding is of the UTF family of encodings no unicode or html entity encoding will occur, however, if the response stream encoding is ISO-8859-1 then the ISO characters above a certain range will be encoded as HTML entities and any characters above that range will be written as decimal references. false 1.2_09
com.sun.faces.disableIdUniquenessCheck If true, then component ID uniqueness won't be checked if ProjectStage is Production to enhance performance. See issue 2414 for details. false 2.1.9
com.sun.faces.enabledJSStyleHiding If true, inlined JavaScript rendered by the HTML ResponseWriter implementation will be rendered so that the script is hidden from older browser implementations which does not recognize <script> elements. false 1.2_03
com.sun.faces.enableScriptsInAttributeValues If false, attribute values with javascript: or script: will not be rendered within attribute values to prevent potential XSS attacks. true 1.2_08
com.sun.faces.enableViewStateIdRendering If true, the view state hidden field will be rendered with both the id and name attributes having the value of "javax.faces.ViewState". This is what the spec requires, however, if there are multiple forms within a view and the response content-type is XHTML, the result will be XHTML that will fail validation due to multiple ID attributes with the same value: javax.faces.ViewState. Setting this parameter to false will result in the ID attribute not being rendered. Keep in mind however, that doing this may break integration with AJAX frameworks that get the state field via ID. See issue 433 for details. true 1.2_08
com.sun.faces.preferXHTML For the case where a browser supports XHTML and HTML without a quality. When enabled and this case occurs, then XHTML will be set as the content type. This setting is not recommended and should be only used to fix broken applications designed with XHTML output in mind instead of HTML(5) output. false 1.2
com.sun.faces.responseBufferSize This parameter specifies the size, in bytes, of the buffer that is used to write all generated JSP content excluding state. Note that this is ignored when Facelets is used. For Facelets, use javax.faces.FACELETS_BUFFER_SIZE instead. 1024 1.2_01

Resource handling related context parameters

Name Description Default Since
com.sun.faces.cacheResourceModificationTimestamp If true, cache the modification time of the resource and use the cached time to tell if the resource needs to be refreshed false 2.0.0
com.sun.faces.compressableMimeTypes Specify mime types that should be gzip compressed. Mime types can be specified by their exact name (i.e. text/css) or a wildcard can be used after the slash (i.e. text/*). The resource will not be compressed on each request, instead when building the cache, the resource will be compressed to a temporary directory and those bytes will be served instead. NONE 2.0.0
com.sun.faces.defaultResourceMaxAge This affects the value of the Expires response header that will be sent for a resource. The logic is basically Date.getTime() + valueOf(defaultResourceManxAge). Increase this value to increase the amount of time that a Resource is valid. The value is in milliseconds (so the default value of 604800000 is 7 days). 604800000 2.0.0
com.sun.faces.enableFaceletsResourceResolverCompositeComponents See issue 3684 for details. false 2.2.10
com.sun.faces.enableMissingResourceLibraryDetection If enabled, the runtime will check for the existence of a resource library before checking for the resource itself. If not found, an appropriate error message will be included in the log and in the view if ProjectStage is Development. false 2.1
com.sun.faces.resourceUpdateCheckPeriod When javax.faces.PROJECT_STAGE is Production, UnitTest, or SystemTest resource paths will be cached to reduce the overhead of resource path compuation. By default, updates (i.e. new files, new directories, new versions, etc.) will be checked for every 5 minutes. If a change is detected, the cache will be cleared and rebuilt. If the value of this option is -1, the cache will never be cleared and new resources will not be picked up. The value is in minutes. 5 2.0.0

Clustering related context parameters

Name Description Default Since
com.sun.faces.enableAgressiveSessionDirtying If true, makes it so every session attribute is touched in for every request through the lifecycle. This makes it much harder to make mistakes that cause session replication to fail. false 2.0.0
com.sun.faces.enableDistributable If true, signal JSF that the application is deployed to a clustered environment, so that session dirtying will be explicitly performed, hereby forcing session replication. This is automatically true when <distributable /> entry is present in web.xml. false 2.???

Configuration related context parameters

Name Description Default Since
com.sun.faces.annotationScanPackages The value of this context init parameter is a whitespace separated list of values that control which class packages are scanned for javax.faces annotations. To restrict which jars/packages are scanned, use the following entry format: jar:<jar name>:<comma separated list of packages> So an example would be: jar:a.jar:com.acme.package1,com.acme.package2. NONE 2.0.0
com.sun.faces.displayConfiguration If true then all web configuration information (context initialization parameters and environment entries) will be written to the log. This is useful during development to confirm your application is configured as expected. false 1.2_01
com.sun.faces.enableCoreTagLibValidator When true, enable validation of standard Core TagLibs, at the expense of a slightly slower start time. false 2.0
com.sun.faces.enableHtmlTagLibValidator When true, enable validation of standard Html TagLibs, at the expense of a slightly slower start time. false 2.0
com.sun.faces.enableLazyBeanValidation When true, managed beans will be validated when first created. If false, managed beans will be validated when the application is started, at the expense of a slightly slower start time. true 1.2_05
com.sun.faces.enableThreading When enabled, the runtime initialization and default ResourceHandler implementation will use threads to perform their functions. Set this value to false if threads aren't desired (as in the case of running within the Google Application Engine). Note that when this option is disabled, the ResourceHandler will not pick up new versions of resources when ProjectStage is development. See issue 2385 for details. true 1.2_13
com.sun.faces.forceLoadConfiguration There is a chance for an NPE in com.sun.faces.application.WebappLifecycleListener with some configurations. Take for example, installing JSF in a container such that JSF will be available to all web applications. The NPE will occur for an application that doesn't have the FacesServlet defined within its web.xml. The workaround for this issue is, within the global web.xml for the container (JBoss and Tomcat both have one) add either a FacesServlet definition (no mapping) or add the context init parameter, com.sun.faces.forceLoadConfiguration, with a value of true. See issue 670 for details. false 1.2_08
com.sun.faces.validateXml When true, enable validation of faces-config.xml files, at the expense of a slightly slower start time. false 1.2
com.sun.faces.verifyObjects When true, JSF makes during startup sure all that registered managed beans components, validators, etc can be instantiated by the runtime, at the expense of a slightly slower start time. false 1.2

Miscellaneous context parameters

Name Description Default Since
com.sun.faces.enableTransitionTimeNoOpFlash If true, the act of calling getExternalContext().getFlash() on the FacesContext at startup or shutdown time will cause a no-op implementation of the Flash to be returned. This should prevent startup/shutdown exceptions caused by invalid/stale flash cookies. See "bugdb 17024459" for details. false 2.2.8
com.sun.faces.expressionFactory This parameter specifies a class that implements the ExpressionFactory. NONE ???
com.sun.faces.forceAlwaysWriteFlashCookie If true, then the flash cookie will always be written, regardless of whether or not the flash has data. This should prevent problems on multiple successive redirects. See issue 3735 for details. false 2.1.20
com.sun.faces.injectionProvider This parameter specifies a class that implements the InjectionProvider. NONE 1.2_01
com.sun.faces.namespaceParameters If true, then view state hidden field is namespaced according to NamingContainer rules. See issue 3031 for details. false 2.1.29
com.sun.faces.registerConverterPropertyEditors If true, allow EL Coercion to use JSF Custom converters. false 2.0
com.sun.faces.sendPoweredByHeader The servlet specification defines an optional header that can be sent by a container to communicate the version of the JSP/Servlet the response was generated by. If this is enabled, then X-Powered-By=JSF/2.2 header is included in all responses. false 1.2
com.sun.faces.serializationProvider This parameter specifies a class that implements the SerializationProvider SPI. This implementation represents a hook the JSF implementation will use in order to allow the use of alternate Serialization implementations. NONE 1.2_01

JSF 1.x backwards compatibility related context parameters

Never use them in JSF 2.x.

Name Description Default Since
com.sun.faces.enabledLoadBundle11Compatibility When this flag is true, The f:loadBundle will behave as it did in JSF 1.1. If you've migrated from 1.1 to 1.2, and haven't had any issues with f:loadBundle it is safe to ignore this option. See issue 577 for details. false 1.2_05
com.sun.faces.enableRestoreView11Compatibility When this flag is true, The restore view phase will behave as it did in JSF 1.1. If you've migrated from 1.1 to 1.2, and haven't had any issues with handling ViewExpiredException it is safe to ignore this option. false 1.2_???