Recipe6.7.Changing the Current Module

Recipe 6.7. Changing the Current Module

Problem

You want to allow the user to switch to a different module at runtime.

Solution

In the struts-config.xml file of the module that you will be switching (referred to as the "source" module), create an action that uses a type of org.apache.struts.actions.SwitchAction:

<action path="/ChangeModuleTest"         type="org.apache.struts.actions.SwitchAction"/>

To use the action, pass request parameters that indicate the module and page within the module to switch to. The module is specified as the value of the prefix request parameter. The page is specified as the value for the page request parameter and defines the module-relative location of the resource to access.

<html:link page="/ChangeModuleTest.do?prefix=moduleName&page=/ SomeAction.do">     Change Module </html:link>

Since the page value is a location, if you are linking to an action, you must include the action extension (e.g., .do) as part of the parameter value.

Discussion

SwitchAction changes the application's current module to another module and forwards control to a specified module-relative URL. Like ForwardAction and IncludeAction, the SwitchAction doesn't require subclassing.

A module is an in-memory, application-relative context maintained by Struts. Modules partition a web application context into subcontexts. A module is defined by creating a separate Struts configuration XML file for the module. This file is referenced using an initialization parameter for the Struts ActionServlet in the web application's web.xml file. The name of the initialization parameter specifies the module's prefix. The following servlet definition creates three modules: the default module, /mod1, and /mod2:

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

You might assume that you can switch from one module to another by using the module prefix on a URL of a link or action. For example, say that you have created a module for administration features called admin. You want to create a link from your application's main page, in the default module, to the main page of the admin module. You might be inclined to create the link using something like this:

<html:link action="/admin/Main.do">Admin Module</html:link>

If you were to code this, you would find that the link would not work!

To switch to an action in another module, the request must go through the Struts controller layer. If you issue a request directly to a JSP page in another module, it won't have access to module-specific Struts objects, such as message resources, plug-ins, and global forwards. The SwitchAction ensures that the request goes through the controller.

Since you can't link directly to JSP in another module, create an action in the Struts configuration file for the module you are linking from that uses the SwitchAction type. Then reference the path of that action in the link, passing the module prefix and page as request parameters:

<html:link page="/SwitchModule.do?prefix=admin&page=/Main.do">     Admin Module </html:link>

The SwitchAction determines the module and the URL of the page or action to forward to based on the prefix and page request parameters. Table 6-1 describes these parameters and provides some examples.

Table 6-1. Switch action parameters
Parameter	Description	Examples
`prefix`	The name of the module to switch to. This value should start with a leading `/`.. Use an empty string to denote the default module.	`prefix=""prefix="/admin`"
`page`	The module-relative URL of the JSP or Action to execute.	`page="/main.jsp"page="/AddEmployee.do?id=5`"

Use global forwards to predefine module links in the Struts configuration file. If the module prefix or page to execute should change, you only need to change the global forward:

<global-forwards>     <forward name="goToDefaultModule"  contextRelative="true"              path="/default_module.jsp"/>     <forward name="goToDefaultModuleViaAction"               path="/SwitchModule.do?prefix=&amp;page=/default_module.jsp"/>     <forward name="goToModule2"               path="/SwitchModule.do?prefix=/mod2&amp;page=/module2.jsp"/> </global-forwards>

Setting contextRelative="true" indicates that you will be switching to the default module. If you are switching to a module other than the default module, the action referenced by the path must be a SwitchAction. To create a link that switches to the module, specify the value of the html:link tag's forward attribute as the name of the global forward:

<html:link forward="goToModule2">     Module2 </html:link>

When specifying request parameters on a path attribute in a Struts configuration XML file, the ampersand character (&) can't be used literally. Instead, use the & character entity. The resulting attribute value will be parsed correctly when it's processed and read by Struts.

Struts 1.2 has added additional support for modules that makes it easier to create links between modules. You can use the html:link tag to create a link to an action in a different module without having to use the SwitchAction or a global forward. When used with the action attribute of the html:link tag, the module attribute specifies the prefix name of the module containing the action mapping specified by the action attribute. Use the empty string ("") to denote the default module. The module attribute is only valid when used with the action attribute:

<html:link module="/mod2" action="module2Action.do">     Module2 </html:link>

If you need to link to a JSP page in another module, you must pass the request through the controller using the SwitchAction.