Recipe2.5.Factoring Your Application into Modules

Recipe 2.5. Factoring Your Application into Modules

Problem

You want to segregate portions of a web application into distinct subapplications, or modules, each with its own separate configuration.

Solution

Create a Struts configuration file for each module in addition to a Struts configuration file for the default module. Then declare each module using initialization parameters for the ActionServlet in the web.xml, as shown in Example 2-11.

Example 2-11. ActionServlet configuration for modules

<!-- 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>   <init-param>     <param-name>config/module1</param-name>     <param-value>/WEB-INF/struts-config-module1.xml</param-value>   </init-param>   <init-param>     <param-name>config/module2</param-name>     <param-value>/WEB-INF/struts-config-module2.xml</param-value>   </init-param>   <load-on-startup>1</load-on-startup> </servlet>

Discussion

Struts 1.1 introduced the ability to define separately configurable sub-applications known as modules. Modules were incorporated into Struts to address the need for subdividing a web application into distinct, manageable portions. Each module is defined with its own configuration file(s). Every Struts application implicitly has a default module. The default module has no module name.

To provide backward compatibility with Struts 1.0 applications, the actual name of the default module is the empty string.

Additional modules are defined by specifying a module prefix. The prefix is the value following config/ in the initialization parameter for the Struts' ActionServlet. In Example 2-11, three modules are defined. The first init-param element defines the default module. The second and third init-param elements establish module1 and module2, respectively.

Struts pre-pends the module prefix to every URL accessed through declarations in the struts-config.xml file for each module. This rule applies to path attributes used in global forwards, global exceptions, action mappings, local forwards, and local exceptions. However, the module's Struts configuration file doesn't need to know and should not use the module prefix.

URLs that are generated using Struts tags, such as html:link and html:rewrite, will include the module name. This implicit inclusion of the module prefix can be a headache when you want to refer to globally shared web resources like images and cascading stylesheets. Web applications commonly place all images referenced throughout the site in a top-level /images folder. If you are using modules and you use the html:img tag to display these images, you must create a separate /images folder for each module or set the module attribute of the html:img tag to the empty string ("") to indicate the default module.

Suppose you wanted to create an administrative user interface for the struts-example MailReader application. The changes required to add the administrative module to the web.xml file are shown below, and the second init-param element defines the admin module:

  <!-- 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,         /WEB-INF/struts-config-registration.xml       </param-value>     </init-param>     <init-param>       <param-name>config/admin</param-name>       <param-value>/WEB-INF/struts-config-admin.xml</param-value>     </init-param>     <load-on-startup>1</load-on-startup>   </servlet>

A common mistake when working with modules is to assume that if you navigate to a URL containing the module prefix, Struts will know you are in that module. For example, you might provide a standard HTML link (i.e., <a href . . . >) to the administrative module's index page from the application's main page. If users select that link, they may see the correct page rendered. However, as far as Struts is concerned, the user is still within the default module. To switch between modules in a Struts 1.1 application, you must forward the user through a special action, called the SwitchAction. In Struts 1.2, the Struts html tags that generate links and URLs support the module attribute, allowing you to explicitly indicate the target module.

Using modules with Struts 1.1 can have its drawbacks. Not all of the tags in Struts 1.1 support modules; so, you may find that the JSP pages within a module can't be written completely irrespective of the module to which they belong. Many of these gaps in usability for modules have been filled in Struts 1.2. Therefore, I recommend you use modules only if you are using Struts 1.2. If you must use Struts 1.1 and your application is anything more than even slightly complex, you may want to avoid the inconsistencies with using modules and instead organize your application by into subfolders, using the technique shown in Recipe 2.4 to split apart your struts-config.xml file.

See Also

Recipe 2.4 describes a technique for splitting the struts-config.xml file into multiple files without using modules. Recipe 6.7 shows techniques to use when you need to switch between modules in a running Struts application.