Configuration Reference

Configuration Reference

This section explains some of the main configurations that should be considered when using ICEfaces, but is not comprehensive. For a complete overview of all the available ICEfaces configuration parameters, see Appendix B ICEfaces Configuration Parameter Overview.

Configuring faces-config.xml

The icefaces.jar file contains a faces-config.xml file that configures the ICEfaces extensions. Specifically, the configuration file registers the Direct-to-DOM renderers. There is no need for the developer to modify the ICEfaces faces-config.xml.

Configuring web.xml

Servlet Registration and Mappings

The application's web.xml file must include necessary Servlet registration and mappings.

The ICEfaces Servlets are registered as follows:
<servlet>
 
	<servlet-name>Persistent Faces Servlet</servlet-name>
 
	<servlet-class>

		com.icesoft.faces.webapp.xmlhttp.PersistentFacesServlet
 
	</servlet-class>
 
	<load-on-startup> 1 </load-on-startup>
 
</servlet>
 

 
<servlet>
 
	<servlet-name>Blocking Servlet</servlet-name>
 
	<servlet-class>com.icesoft.faces.webapp.xmlhttp.BlockingServlet</servlet-class>
 
	<load-on-startup> 1 </load-on-startup>
 
</servlet>
 
The Servlet mappings are established as follows:
<servlet-mapping>
 
	<servlet-name>Faces Servlet</servlet-name>
 
	<url-pattern>*.jspx</url-pattern>
 
</servlet-mapping>
 

 
<servlet-mapping>
 
	<servlet-name>Persistent Faces Servlet</servlet-name>
 
	<url-pattern>*.iface</url-pattern>
 
</servlet-mapping>
 

 
<servlet-mapping>
 
	<servlet-name>Persistent Faces Servlet</servlet-name>
 
	<url-pattern>/xmlhttp/*</url-pattern>
 
</servlet-mapping>
 

 
<servlet-mapping>
 
	<servlet-name>Blocking Servlet</servlet-name>
 
	<url-pattern>/block/*</url-pattern>
 
</servlet-mapping>
 
Defining the Context Listener

This is a not a parameter, per se, but a listener that is typically configured by default because it sits in icefaces.jar/META-INF/include.tld as:
<listener> 
 
    <listener-class>
 
          com.icesoft.faces.util.event.servlet.ContextEventRepeater
 
    </listener-class> 
 
</listener> 
 
The ContextEventRepeater implements both the HttpSessionListener and ServletContextListener interfaces and was designed to forward servlet events to different parts of the ICEfaces framework. These events are typically of interest for gracefully and/or proactively keeping track of valid sessions and allowing for orderly shut down.

Application servers that don't support configuring listeners this way may need to include this listener in their web.xml document:
<listener> 
 
    <listener-class> 
 
          com.icesoft.faces.util.event.servlet.ContextEventRepeater 
 
    </listener-class> 
 
</listener> 
 
Asynchronous vs. Synchronous Updates

By default, ICEfaces runs in asynchronous update mode, which provides support for ICEfaces unique server-initiated rendering (Ajax Push) capabilities. However, many applications do not require the full capabilities provided by asynchronous update mode. In these cases, it is recommended that synchronous update mode be configured.

Synchronous update mode can be enabled application-wide using the ICEfaces context parameter, com.icesoft.faces.synchronousUpdate. Typically this is set in the web.xml file of your web application as follows.
<context-param>
 
		<param-name>com.icesoft.faces.synchronousUpdate</param-name>
 
		<param-value>true</param-value>
 
</context-param>
 

 
There is no advantage to using asynchronous update mode for applications that do not use server-initiated rendering, and there are additional resource requirements associated with its use. See Optimizing Asynchronous Communications for Scalability. Synchronous update mode should be used if your application does NOT use the ICEfaces server-initiated rendering features. When synchronous update mode is configured, monitoring and maintaining continuous connections to the server is not required. Instead, a connection is created for each user-initiated request, just as with any non-ICEfaces web-application.

Note: When deploying multiple asynchronous ICEfaces applications to the same application server/host-name, it is necessary to also deploy the ICEfaces Push Server. Refer to Push Server. for more information.

Concurrent Views

To allow multiple windows for a single application, concurrent DOM views must be enabled. This is set through the ICEfaces context parameter, com.icesoft.faces.concurrentDOMViews. Typically, this is set in the web.xml file of your web application:
	<context-param>
 
		<param-name>com.icesoft.faces.concurrentDOMViews</param-name> 
 
		<param-value>true</param-value> 
 
	</context-param> 
 
Standard Request Scope

To cause request scope to last only for the duration of a single user event, "standard request scope" must be enabled. This is set through the ICEfaces context parameter, com.icesoft.faces.standardRequestScope.

Typically this is set in the web.xml file of your web application:
	<context-param>
 
		<param-name>com.icesoft.faces.standardRequestScope</param-name>
 
		<param-value>true</param-value>
 
	</context-param>
 
Redirect on JavaScript Blocked

Some browsers are configured to block JavaScript interpretation or some browsers cannot interpret JavaScript content. For these instances, ICEFaces can be configured to redirect the browser to a custom error page.

This feature can be turned on application-wide using the ICEfaces context parameter, com.icesoft.faces.javascriptBlockedRedirectURI.
<context-param>
 
		<param-name>com.icesoft.faces.javascriptBlockedRedirectURI</param-name>
 
		<param-value>...custom error page URL....</param-value>
 
</context-param>
 
If not specified, by default the server will send an HTTP error code `403 - Javascript not enabled'. This is to avoid any ambiguity, since the accessed page would be rendered but any interaction with it would be impossible.

Compressing Resources

Resources such as JavaScript and CSS files can be compressed when sent to the browser, improving application load time in certain deployments. The configuration works independently from the web-server configuration.

By default, ICEfaces will compress key resources. This may cause problems in configurations whereby another component is also configured to compress resources, such as certain portal containers. If necessary, you can disable it using the ICEfaces context parameter, com.icesoft.faces.compressResources.
<context-param>
 
		<param-name>com.icesoft.faces.compressResources</param-name>
 
		<param-value>false</param-value>
 
</context-param>
 
Further customization of ICEfaces resource compression behavior is possible, such as specifying specific file types to be compressed. For more information, see the compressResources and compressResourcesExclusions configuration parameters in Appendix B ICEfaces Configuration Parameter Overview.

Busy Indicator

By default, ICEfaces presents a busy indictor (hourglass cursor) and blocks user-interface events via the mouse while a submit or partial-submit is being processed.This feature provides the user with a visual indication that the application is busy and also prevents them from triggering additional submits while the previous submit is being processed. This prevents users from "chaining" multiple user interface events/submits while results from previous events are pending, which could result in confusing application behavior as the user-interface lags and then "catches" up with the user interactions.

This feature can be disabled by specifying the following configuration parameter in the web.xml file of your web application:
<context-param> 
 
		<param-name>com.icesoft.faces.blockUIOnSubmit</param-name> 
 
		<param-value>false</context-param> 
 
</context-param> 
 
Further customization of ICEfaces Ajax bridge behaviors is possible, such as implementing a custom busy indicator in JavaScript for your application. For more information, see Bridge Connection Status Events.

File Upload

Applications that use the ice:fileUpload component must configure the upload servlet:
 
 
<servlet> 
 
    <servlet-name>uploadServlet</servlet-name> 
 
    <servlet-class>
 
            com.icesoft.faces.component.inputfile.FileUploadServlet
 
    </servlet-class> 
 
    <load-on-startup> 1 </load-on-startup> 
 
</servlet> 
 

 
The maximum file upload size can be specified in the web.xml file of your web application as follows:
<context-param>
 
    <param-name>com.icesoft.faces.uploadMaxFileSize</param-name>
 
    <param-value>1048576</param-value>
 
</context-param>
 
If not specified the default value for file upload is 10485760 bytes (10 megabytes).

To specify the directory location where uploaded files are stored, the following parameter is used:
<context-param>
 
    <param-name>com.icesoft.faces.uploadDirectory</param-name>
 
    <param-value>images/upload</param-value>
 
</context-param>
 
This parameter works in conjunction with the ice:inputFile component attribute "uniqueFolder" with four possible combinations as illustrated in the table below:

uniqueFolder

com.icesoft.faces.uploadDirectory

Set

Not Set

True

/application-context/uploadDirectory/sessionid/

/application-context/sessionid/

False

/application-context/uploadDirectory/

/application-context/

Note: The default upload directory specified via the configuration parameters above can be overridden on a per-instance basis via the uploadDirectory and uploadDirectoryAbsolute attributes on the ice:inputFile component.

uniqueFolder	com.icesoft.faces.uploadDirectory
uniqueFolder	Set	Not Set
True	/application-context/uploadDirectory/sessionid/	/application-context/sessionid/
False	/application-context/uploadDirectory/	/application-context/