Using ICEfaces with JBoss Seam

As of the ICEfaces 1.6.0 Final release, ICEfaces has been tested to work with Seam v1.2.1.GA with both jsf 1.1 implementation (myfaces jars) and jsf1.2 implementation (jsf1.2 jars). For Seam v2.0.0.GA, ICEfaces 1.6.1 as a minimum is recommended. Downloads available to assist developers include:-

seam component showcase which contains 3 build targets
1. jboss-seam-1.2.1.GA with jsf 1.1 implementation (myfaces jars)
2. jboss-seam-1.2.1.GA with jsf 1.2 implementation (jsf1.2 jars)
3. jboss-seam-2.0.0.GA with jsf 1.2 implemenation (jsf1.2 jars)
icefaces-seam-gen which will create a jboss-seam-1.2.1.GA (jsf1.1 implementation) application and allow the reverse generation of templates and java classes from an existing database

Both bundles contain README for information on use.

The distribution package for jboss-seam-2.0.0.GA includes an icefaces example (using ICEfaces1.6.1 on the Maven2 repository that jboss-seam has created). This package also now includes ICEfaces as an option in it's standard seam-gen utiltiy.

Soon to be released is a WAR deployment of seam-comp-showcase which doesn't use the ejb3 container (currently available on the SVN repository). It is based on jboss-seam-2.0.0.GA with jsf 1.2 implementation and has been tested using Tomcat 6, jboss-4.2.*, Weblogic 10 and Glassfish v2. There are also targets for non-jee5 application servers, but the asynchronous push is not currently working for these (yet).

Please see the ICEfaces JBoss Seam Integration forums if you have further questions or comments.

Overview

This document contains the following sections:

Configuring a Seam + ICEfaces Application

Many classloading issues can arise when working with Seam and ICEfaces (as opposed to a strictly JSF web app environment). Currently, the following approach must be used:

For jboss-seam-1.2.1.GA

Use an EAR type of deployment. Examples of how to create an EAR are available in the Seam documentation, or you can simply use icefaces-seam-gen and specify 'ear' at the appropriate prompt. A NetBeans plug-in is also available and, if you have your database configured through NetBeans, this makes it easier to reverse-engineer pages based on database tables. These utilities are based on the original seam-gen utility but require the location of your icefaces*.jars to provide ICEfaces-enabled pages
Package the ICEfaces jars in the EAR directory and specify them as modules in the application.xml. For actual configuration files, see the seam component showcase bundle. Note that the properties in the build.properties file must be modified for each build so that the proper directories are targeted for each configuration. Each version of seam has dependencies on entirely different sets of libraries (jar files) and the various versions of jsf implementations further complicates the configuration and packaging, making the seam component showcase bundle of added benefit (as well as showing how to use the ICEfaces components).
Ensure that the ICEfaces jars are *not* included in the WAR's WEB-INF/lib directory, as this will override the jars being loaded from the EAR's application.xml. Also ensure that the ONLY facelets jar deployed within the project is the icefaces-facelets.jar.
Be sure to have the following context params defined in the web.xml file for all ICEfaces Seam applications:
- This parameter indicates to ICEfaces to use the standard JSF implementation of EVENT scope. ICEfaces applications that do not use Seam may set this false, and store application information within the RequestMap in the ExternalContext for longer than a single Request or Server initiated render cycle.
  
  <context-param>
  <param-name>com.icesoft.faces.standardRequestScope</param-name>
  <param-value>true</param-value>
  </context-param>
- For jsf 1.1 specification web.xml use the following listeners
  
  < listener> <listener-class>org.jboss.seam.servlet.SeamListener</listener-class> </listener> < listener> <listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class> </listener> < listener> <listener-class>com.icesoft.faces.util.event.servlet.ContextEventRepeater</listener-class> </listener>


         


  

Using
Server Initiated Rendering (RenderManager)

	Beginning with ICEfaces v1.6DR#3, the RenderManager is
	supported when using Seam. 
	


	For server initiated rendering, be
	SURE to have synchronous mode set to false in your web.xml file.
	Otherwise, the application will generate server initiated renders
	that are silently swallowed: 
	
	<context-param> 
  
	<param-name>com.icesoft.faces.synchronousUpdate</param-name>
	
   <param-value>false</param-value>
	
</context-param> 
	
	
You should use Synchronous update mode
	(synchronousUpdate=true) if your application does NOT use the
	ICEfaces server-initiated rendering feature (via either the
	RenderManager or by calling  render() on the
	PersistentFacesState object). 
	

Prior to the ICEfaces v1.6 DR#1, ICEfaces application developers 
could use JSF to instantiate the Application scope RenderManager, and 
cause this instance to be initialized via a property setter on their 
state bean for the purposes of initiating an IntervalRenderer, or 
some similar mechanism for triggering a render portion of the JSF 
lifecycle. This still works, but it is preferrable to configure Seam to load the RenderManager as a named component, 
and can use injection to pass the RenderManager instance to their 
beans. 

Example

To get the RenderManager to be
loaded as a named Seam component, add the following line to the
components.xml file: 

<component scope="APPLICATION"
auto-create="true" name="renderManager"
       
class="com.icesoft.faces.async.render.RenderManager" />


This is effectively the same as using JSF to create a
managed bean instance. There are a couple of ways to gain access to
the RenderManager via injection: 


	Declare the RenderManager with the @In Seam annotation
	

  @In 
  private RenderManager
	renderManager; 
	
	
 Or you can declare the setter property with the @In annotation 

  
	@In 
   public void setRenderManager(RenderManager x) {
	
     renderManager = x; 
  
	} 
	


To use the RenderManager is a bit more involved than before. 
See the TimerBeanImpl Class that is created through icefaces-seam-gen for an implementation of the IntervalRenderer.  Also, the progress monitor in the new War deployment for jboss-seam-2.0.0.GA uses an Interval Renderer.

Using the File Upload (ice:inputFile)
Component
As of 1.6 DR#4 release, due to refactoring and streamlining the 
Servlet environment used in ICEfaces, it's no longer necessary to 
turn off Seam interception for the FileUpload backing bean. Please 
see the InputFileBackerBean in the seam-component-showcase example 
for an example if you want to do a SSB for this component.

We still use an inner class in the
InputBeanImpl class in the FileUpload example to get around a
concurrent access problem when you make the  BackingBean itself
generate a render from inside the Bean itself. Concurrent method
calls to the same object are not allowed in n EJB container. 
See the example in the FileUploadServlet.
Note also the direct use of the PersistentFacesState object to 
execute and render within the progress method of this example. This 
approach (rather than using the RenderManager) is a cosmetic one 
designed to make the progress bar updates oppear as they occur. If 
the RenderManager is used, all server initiated rendering is done 
asynchronously in a separate thread. The file upload occurs quite 
quickly, for small files, and the progress bar usually only renders 0 
or 100%, as the 10% updates occur far faster than the render cycle 
can complete. 

This constraint does not occur in the 
ProgressBar example.  
The War-deployment version of seam-comp-showcase is uses techniques similar to non-seam versions but turns off Seam transaction management (for now).

Common Errors and Known issues
Please see the JBoss Seam Integration portion of the forum for the current issues users are facing.  Seam is rapidly evolving with users becoming more conversant and innovative, helping to push the development pace such that documents like this are hard pressed to keep up.

Not all seam components are currently working with our facelets view handler.  The following Jira's are already registered for fixes to ensure 100% Seam component use with ICEfaces.   Please see the Jira for details:-


	
		 Jira Number
		 description
	
	
	    ICE-2114
	     allow Seam pdf functionality with ICEfaces
	    
	
	 
	    ICE-2321
	     integrate seam mail component
	
	 
	    ICE-2527
	     Seam jBPM redriects causing redirect loop
	
	
	    ICE-2147
	    Seam LocaleSelector currently not working with ICEfaces viewHandler

Jira Number	description
ICE-2114	`allow Seam pdf functionality with ICEfaces`
ICE-2321	`integrate seam mail component`
ICE-2527	`Seam jBPM redriects causing redirect loop`
ICE-2147	`Seam LocaleSelector currently not working with ICEfaces viewHandler`