The Struts-Faces Tag Library Tags | Struts: The Complete Reference, 2nd Edition

Using the Struts-Faces Library

Using the Struts-Faces library involves these five steps:

Add the required .jar files to the application.
Add a servlet definition for the JSF controller servlet to the web.xml file.
Configure Struts to use a custom Struts-Faces request processor.
Use the Struts-Faces and JSF tag library tags to create JSF-based user interfaces.
Configure forward and action definitions in the application's Struts configuration file.

The following sections explain how to set up and use the Struts-Faces library in detail.

Adding the Required .jar Files to the Application

Several .jar files must be added to the application in order to use JSF and Struts-Faces functionality. Each required .jar file should be copied to the application's WEB-INF\lib directory (or added to the classpath of the server[s] the application runs on). First, add the Struts-Faces .jar file (e.g., c:\java\struts-1.3.5\lib\struts-faces-1.3.5.jar) from the Struts distribution to the application if it is not already present. Next, add the JSTL .jar files (e.g., c:\java\struts-1.3.5\lib\jstl-1.0.2.jar and c:\java\struts-1.3.5\lib\standard-1.0.2.jar) from the Struts distribution to the application if they are not already present. Finally, a JSF implementation's .jar files must be added to the application. Any JSF implementation that has been certified to be compatible with the JSF specification will work, such as the reference implementation from Sun or the Apache MyFaces implementation. Assuming, you're using the reference implementation from Sun, you must copy the jsf-api.jar and jsf-impl.jar files from the reference implementation's lib directory (e.g., c:\java\jsf-1_1_01\lib) to the application.

Adding a Servlet Definition for the JSF Controller Servlet to the web.xml File

Similar to the setup for the Struts controller servlet, a servlet definition and related configuration details must be added to the web.xml file for the JSF controller servlet. The following snippet shows an example:

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

Generally, the JSF controller servlet is mapped to URI's using extension mapping (e.g., *.faces) as shown in the preceding configuration snippet. However, path mapping (e.g., /faces/*) can be used as well, as shown next.

<!-- JSF Servlet Mapping --> <servlet-mapping>   <servlet-name>faces</servlet-name>   <url-pattern>/faces/*</url-pattern> </servlet-mapping>

In addition to adding the JSF controller servlet configuration details to the web.xml file, the Struts servlet configuration details must be modified so that the JSF controller servlet is initialized before the Struts controller servlet. Recall that the order in which servlets are initialized is controlled by the <load-on-startup> tag. The <load-on-startup> tag specifies a priority value for the order in which servlets are loaded; servlets with a higher priority (lower value) are loaded first. The JSF controller servlet priority is set to 1, so the Struts controller servlet must be updated to a priority of 2 so that it loads after the JSF controller servlet, as shown here:

<!-- Action Servlet Configuration --> <servlet>   <servlet-name>action</servlet-name>   <servlet-class>org.apache.struts.action.ActionServlet</servlet-class>   <init-param>     <param-name>config</param-name>     <param-value>/WEB-INF/struts-config.xml</param-value>   </init-param>   <load-on-startup>2</load-on-startup> </servlet>

Configuring Struts to Use a Custom Struts-Faces Request Processor

Struts must be configured to use a custom Struts-Faces request processor in order to recognize requests for pages utilizing JSF and to handle them appropriately. There are two custom request processors provided by Struts-Faces that can be used:

org.apache.struts.faces.application.FacesRequestProcessor
org.apache.struts.faces.application.FacesTilesRequestProcessor

FacesRequestProcessor is for standard Struts applications not using Tiles and FacesTile sRequestProcessor is for Struts applications making use of Tiles. To configure Struts to use a custom request processor, you must update your application's Struts configuration file (e.g., struts-config.xml). The following snippet configures Struts to use the basic non-Tiles Struts-Faces request processor:

<!-- Controller Configuration --> <controller>   <set-property property="processorClass"     value="org.apache.struts.faces.application.FacesRequestProcessor"/> </controller>

Note

Although Struts versions 1.3 and later use Commons Chain for request processing, at the time of this writing Struts-Faces still relies on the outdated method of extending the RequestProcessor class to modify the behavior of the request processing engine.

Using the Struts-Faces and JSF Tag Library Tags to Create JSF-Based User Interfaces

The main task in using the Struts-Faces library is to create JSPs that use (or update JSPs to use) the Struts-Faces and JSF tag library tags to build a user interface. As in any Struts or JSF application, first you must declare the tag libraries that will be used by the JSP. The following JSF tag library declarations must be added to the JSP:

<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>

Additionally, the declaration shown next must be added to the JSP for the Struts-Faces tag library.

<%@ taglib uri="http://struts.apache.org/tags-faces" prefix="s" %>

After declaring the tag libraries, user interfaces can be created using the JSF and Struts-Faces tag libraries. The interface is created just as it would be in a JSF application with a few exceptions where Struts-Faces tags are used instead of JSF tags.

Whereas in a JSF application the JSF Html Tag Library form tag (i.e., <h:form>) is used to encapsulate a form, with Struts-Faces the Struts-Faces form tag (i.e., <s:form>) must be used. The Struts-Faces form tag behaves the same as the JSF form tag except that it interfaces with the Struts controller servlet for processing the request. Similarly, Struts-Faces requires that its commandLink tag be used instead of the JSF commandLink tag so that form submissions are processed properly. The Struts-Faces library also provides other tags such as the message and write tags that make integrating with Struts easy. The message and write tags essentially mirror those from the Struts Bean Tag Library. The Struts-Faces tag library also has several other tags that ease the integration of Struts and JSF (or transition from Struts to JSF as the case may be).

Configuring Forward and Action Definitions in the Application's Struts Configuration File

Once application JSPs have been created or updated to use Struts-Faces and JSF Tag Library tags, you must create or update each of the forward and action definitions in the Struts configuration file that point to those JSPs. Without Struts-Faces, forward and action definitions usually point directly to JSPs. With Struts-Faces, however, the definitions must point to URIs that map to the JSF controller servlet, either by extension (e.g., *.faces) or by path (e.g., / faces/*). For example, the following forward definition points directly to search.jsp.

<!-- Global Forwards Configuration --> <global-forwards>   <forward name="search" path="/search.jsp"/> </global-forwards>

With Struts-Faces, the forward must point to the search page's JSF URI, as shown here:

<!-- Global Forwards Configuration --> <global-forwards>   <forward name="search" path="/search.faces"/> </global-forwards>

At run time, the Struts-Faces library will determine whether a forward or action definition points to the path of a JSF URI or directly to a JSP. If a JSF URI is specified, then Struts-Faces will process the page accordingly; otherwise, normal Struts processing will take place.

Known Limitations

At the time of this writing the Struts-Faces library has a few documented limitations. Each limitation is listed next with details about its impact.

The Struts modules feature is not yet supported by Struts-Faces. Additionally, as a result of that, the forwardPattern and pagePattern attributes of the <controller> tag in the Struts configuration file are not supported by Struts-Faces. A servlet filter can be used to get around this limitation; however, such a filter is not provided by Struts-Faces.
The Struts Nested and Struts-EL tag libraries are not supported by Struts-Faces. Because many of the tags in the Struts tag libraries have JSTL equivalent replacements, JSTL should be used instead.
The forward attribute of the <action> tag in the Struts configuration file cannot be used to forward to a JSF page.
Custom request processors cannot be used unless they extend one of the Struts-Faces custom request processors. Because Struts-Faces does not yet support the more modern Commons Chain-based request processing approach, each layer of customization to the request processing engine requires an extension of another request processing class. This makes it difficult to use multiple features that each extend the engine.