Recipe7.4.Forwarding Users to Alternate Destinations

Recipe 7.4. Forwarding Users to Alternate Destinations

Problem

You want to define locations, such as other servlets, JSPs, or Struts components that you can forward users to from your application code.

Solution

Define the global forwards in the struts-config.xml file. If the forward is for a specific module, define it in that module's struts-config.xml file:

<form-beans>    <!-- snipped ... --> </form-beans> <global-forwards>     <forward name="main" path="/index.jsp"           redirect="true"/>     <forward name="logon" path="/Logon.do"           contextRelative="true" redirect="true"/>     <forward name="logoff" path="/Logoff.do"           contextRelative="true" redirect="true"/> </global-forwards> <global-exceptions>    <!-- snipped ... --> </global-exceptions>

Discussion

The URL paths you use in your application commonly evolve and change as your application develops. You can create logical references to application paths using a Struts forward. Global forwardsdefined using forward elements nested in the global-forwards elementcreate logical destinations that can be accessed from anywhere in your application. The Struts html:link, html:rewrite, and html:frame tags all support the forward attribute that accepts the name of a global forward. The tag uses the logical path for that forward to generate the actual URL.

Local forwards are specific to a given action. Local forwards are specified as nested elements of an action element:

<action    path="/LoadData"            type="com.oreilly.strutsckbk.ch07.LoadDataAction"           scope="request"            name="TestForm">     <forward name="success" path="/show_data_form.jsp"/> </action>

Local forwards are used by action classes to specify a logical destination. The ActionMapping.findForward( ) method retrieves a forward by name. This method finds a matching local forward for the given name. If none can be found, it searches the global forwards. Here's how a typical custom Action uses the findForward( ) method to retrieve and return an ActionForward:

public ActionForward execute(ActionMapping mapping, ActionForm form,             HttpServletRequest request, HttpServletResponse response)         throws Exception {     // perform action here         // forward to the logical "success" location     return mapping.findForward("success"); }

The forward element, whether global or local, accepts the attributes shown in Table 7-1.

Table 7-1. Forward attributes

Attribute	Description
className	Fully qualified Java class name of the ActionForward subclass to use for this object. If unspecified, the class org.apache.struts.action.ActionForward is used. You only need to use this if you extend the Struts ActionForward to provide unique behavior.
contextRelative	Set this to true if the path is relative to the entire application and not this module. This attribute, added in Struts 1.1, is deprecated in Struts 1.2. The default value is false; that is, the path is considered module-relative.
module	The module prefix to use with this path. This value begins with a slash (for example, /adminModule) . If unspecified, the module prefix defaults for the current module will be used. A single slash (/) indicates the root module.
name	A module-unique logical identifier for this forward. This value is used to retrieve the forward using the ActionMapping.findForward(String name) method.
path	The module-relative or context-relative URI path to the resource for this ActionForward. This value begins with a slash (for example, /somePage.jsp).
redirect	Set this to TRue if a redirect instruction should be issued to the browser so a new request is issued to the resource for this forward. The default value is false.

The URI generated for the forward is determined by the contextRelative, module, and path attributes. For Struts 1.1 applications, the contextRelative attribute lets you create forwards between modules. For Struts 1.2, use the module attribute instead of contextRelative. Specifying a module value of / is the same as setting contextRelative to true.

The path attribute contains the location to the desired resource. You can include request parameters by appending a query string. Just be sure to use the ampersand character entity (&amp) to separate name-value pairs. Table 7-2 contains some example global forwards and the resulting URIs.

Table 7-2. Sample forwards

Forward definition	Resultant URL
<forward name="home" path="/index.jsp" redirect="true"/>	http://localhost/jsc-ch07/index.jsp
<forward name="goToModule1" module="/mod1" path="/module1.jsp"/>	http://localhost/jsc-ch07/mod1/module1.jsp
<forward name="goToDefaultModule" contextRelative="true" path="/default_module.jsp"/>	http://localhost/jsc-ch07/default_module.jsp
<forward name="goToDefaultModule2" module="/" path="/default_module.jsp"/>	http://localhost/jsc-ch07//default_module.jsp

See Also

Using a global forward specifically to switch to a page in a different module is covered in Recipe 7.5. More information on switching between modules can be found in Recipe 6-7. Global forwards can be used like bridges between workflows as described in Recipe 6.5.

The Struts User Guide provides additional information on configuring and using global and local forwards. The relevant section can be found at http://struts.apache.org/userGuide/building_controller.html#config.