Java Server Faces (JSF)

Integrating OpenCms with JavaServer Faces 1.1 is possible. JSF 1.2 seems not to work with up to OpenCms 7.0.4. This articles lists all the work that has to be done to use JSF within OpenCms.

There seem to be people out there that have OpenCms and JSF 2 running. However, this requires at least code modification on the OpenCms side! Any further information is welcome.

Prerequisites

Before you start you have to decide on the software versions you want to use. On the Apache website there is a compatibility list for Apache's software stack (Tomcat, MyFaces).

The following combinations are known to work

please extend!

Java Runtime	OpenCms	Servlet Container/Application Server	JSF Implementation
1.5	7.0.1 (WebApp 2.4)	Tomcat 6.0.14	Sun RI 1.1_02
1.5	7.0.1 (WebApp 2.4)	Tomcat 5.5.23	Sun RI 1.1_02
1.5	7.0.1 (WebApp 2.4)	Tomcat 5.5.23	MyFaces 1.1.5
1.5	6.2.3 (WebApp 2.3)	Tomcat 6.0.14	Sun RI 1.1_02
1.5	7.0.2 (WebApp 2.4)	Tomcat 6.0.14	Sun RI 1.1_02
1.6	7.0.4 (WebApp 2.4)	Tomcat 5.5.26	MyFaces 1.1.5
1.5	6.2.3 (WebApp 2.3)	Tomcat 6.0.14	Sun RI 1.1_02
1.5	7.0.2 (WebApp 2.4)	Tomcat 6.0.14	Sun RI 1.1_02
1.6	7.0.4 (WebApp 2.4)	Tomcat 5.5.26	MyFaces 1.1.5
1.5	6.2.3 (WebApp 2.3)	Tomcat 6.0.14	Sun RI 1.1_02
1.5	7.0.2 (WebApp 2.4)	Tomcat 6.0.14	Sun RI 1.1_02
1.6	7.0.4 (WebApp 2.4)	Tomcat 5.5.26	MyFaces 1.1.5
1.5	6.2.3 (WebApp 2.3)	Tomcat 6.0.14	Sun RI 1.1_02
1.5	7.0.2 (WebApp 2.4)	Tomcat 6.0.14	Sun RI 1.1_02
1.6	7.0.4 (WebApp 2.4)	Tomcat 5.5.26	MyFaces 1.1.5

The following seem NOT to work:

• JSF 1.2 in general. Tested with Sun's RI (Mojara) and Apache Myfaces.
• With Mojara the JSF page is rendered, but output of JSF tags is out of order and partially overwriting JSP output. In addition to this the output is truncated, depending on the <f:view>-tag's content size.
• With Apache MyFaces the output of the JSF page is incomplete. Non-JSF output seems to be missing completely.

The following seem to NOT work:

• JSF 1.2 in general. Tested with Sun's RI (Mojara) and Apache Myfaces.
• With Mojara the JSF page is rendered, but output of JSF tags is out of order and partially overwriting JSP output. In addition to this the output is truncated, depending on the <f:view>-tag's content size.
• With Apache MyFaces the output of the JSF page is incomplete. Non-JSF output seems to be missing completely.

The following seem to NOT work:

• JSF 1.2 in general. Tested with Sun's RI (Mojara) and Apache Myfaces.
• With Mojara the JSF page is rendered, but output of JSF tags is out of order and partially overwriting JSP output. In addition to this the output is truncated, depending on the <f:view>-tag's content size.
• With Apache MyFaces the output of the JSF page is incomplete. Non-JSF output seems to be missing completely.

Integrating OpenCms and Java Server Faces

Copy JSF Libraries

First, get the JSF implementation of your choice. Unzip the distribution and search for the JAR files named jsf-api.jar and jsf-impl.jar (usually in the lib directory). Copy these two archives to WEB-INF/lib in your OpenCms installation directory.

Adapt Webapplication Descriptor

Next you have to configure the servlet mapping in WEB-INF/web.xml. Add the following sections:

   <servlet>
      <servlet-name>Faces Servlet</servlet-name>
      <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
   </servlet>
 
   <servlet-mapping>
      <servlet-name>Faces Servlet</servlet-name>
      <url-pattern>/faces/*</url-pattern>
   </servlet-mapping>

Note that it has been reported, that suffix-mapping (e.g, *.jsf) should work as well but I couldn't get it to work, so I used prefix mapping, i.e. "/faces/*", instead.

Create Faces Configuration

Next you can create a JSF configuration file in WEB-INF/faces-config.xml like this:

<?xml version="1.0"?>
<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"
        version="1.2">
   <navigation-rule>
      <from-view-id>/opencms/jsf-example.jsp</from-view-id>
      <navigation-case>
         <from-outcome>login</from-outcome>
         <to-view-id>/opencms/jsf-example2.jsp</to-view-id>
      </navigation-case>
   </navigation-rule>
 
   <managed-bean>
      <managed-bean-name>user</managed-bean-name>
      <managed-bean-class>com.corejsf.UserBean</managed-bean-class>
      <managed-bean-scope>session</managed-bean-scope>
   </managed-bean>
</faces-config>

Add Bean Classes

Add bean classes as you need them to WEB-INF/classes or in a JAR file, as you like.

Restart Servlet Container

Restart your servlet container.

Use your JSF pages with the correct URLs

Create your JSF pages and access them with the correct URLs. There is nothing special in creating JSF pages. Just go to OpenCms' workplace, click on "New", select "JSP" as the type for you new JSF page and insert your code.

When you want to access a JSF page use the base URL http://myhost:8080/opencms/faces/opencms/ with the path of the file in workplace appended. For example if you have a file jsf-example.jsp in your root-folder of the /sites/default site, access it via the URL http://myhost:8080/opencms/faces/opencms/jsf-example.jsp.

Here's a simple servlet filter that rewrites any pages ending with ".jsf" to /opencms/faces/opencms . This way, you can click on the JSF pages within the editor and get the preview to work correctly. You'll need to name all your JSF pages ".jsf" for this to work. The filter requires the Apache Commons Lang libraries:

package opencms-support.servlet;
 
import java.io.IOException;
import javax.servlet.*;
import javax.servlet.http.*;
 
import org.apache.commons.lang.StringUtils;
 
 
public class RewriteFilter implements Filter {
	/**
	 * Logger for this class
	 */
	private FilterConfig filterConfig;
	public void destroy() {
	}
 
	public void doFilter(ServletRequest request, ServletResponse response,
			FilterChain chain) throws IOException, ServletException {
		HttpServletRequest req = (HttpServletRequest) request;
		HttpServletResponse res = (HttpServletResponse) response;
		String uri = req.getRequestURI();
		String queryString = req.getQueryString();
		if ((uri.startsWith("/opencms/opencms/")) && (uri.endsWith(".jsf") )) {
			uri = StringUtils.replace(uri, "/opencms/opencms/", "/opencms/faces/opencms/");		
			if (StringUtils.isNotBlank(queryString)) {
				uri = uri + "?" + queryString;
			}
			res.sendRedirect(uri);
			return;			
		}
		chain.doFilter(request, response);
	}
	public void init(FilterConfig filterConfig) throws ServletException {
		this.filterConfig = filterConfig;
	}
 
}

You'll also need to map it in web.xml:

<filter>
  <filter-name>RewriteFilter</filter-name>
  <filter-class>opencms-support.servlet.RewriteFilter</filter-class>
</filter>
 
<filter-mapping>
 <filter-name>RewriteFilter</filter-name>
 <url-pattern>/*</url-pattern>
</filter-mapping>

Useful Links

• http://www.nabble.com/forum/ViewPost.jtp?post=13485806&framed=y
• http://www.nabble.com/forum/ViewPost.jtp?post=15958214&framed=y
• http://forum.java.sun.com/thread.jspa?threadID=5236855&tstart=555
• http://lists.opencms.org/pipermail/opencms-dev/2011q1/035258.html