About the Page Flow in Databound Struts Applications

You can use the Struts Page Flow Diagram to assemble databound applications that rely on Oracle ADF data controls to access business services and the Struts controller to manage page navigation.

This topic contains the following sections:

Overview
Data Pages in the Databound Struts Page Flow
Data Actions in the Databound Struts Page Flow
Pages and Page Forwards in the Databound Struts Page Flow

Overview

Oracle ADF provides the classes oracle.adf.controller.struts.actions.DataAction and oracle.adf.controller.struts.actions.DataForwardAction (represented in the Page Flow Diagram as a data page) to prepare the binding context for databound web pages. Your databound web application works with these classes through entries in the Struts configuration file. JDeveloper creates these entries when you drag a data action or data page from the Component Palette onto your page flow diagram. Also, if you drag a data control from the Data Control Palette to a web page that is not already associated with a data page or data action, JDeveloper converts the web page to your choice of a data page or data action to provide the data binding context.

The DataForwardAction and DataAction classes extend org.apache.struts.action.Action and provide a findForward() method that specifies the destination of the action. The data action, data page, and standard Struts action classes perform the same general function. However, at runtime the data action or data forward action receives a modelReference property value from the action mapping, which allows it to refer to the Oracle ADF binding objects.

For information about when to use a data page or data action, see Deciding When to Use a Data Page or a Data Action.

Data Pages in the Databound Struts Page Flow

When you use the Struts Page Flow Diagram to create a data page, JDeveloper updates the struts-config.xml file. For example, if you drag the data page icon to an empty Page Flow Diagram and rename it /myPage, you get a data page icon with a warning icon overlaid to show that the associated web page has not been created and the model reference for the data page has not been set:

Datapage icon with warning overlaid

JDeveloper creates the following entries in the struts-config.xml file:

<form-beans> <form-bean name="DataForm" type="oracle.adf.controller.struts.forms.BindingContainerActionForm"/> </form-beans> <action-mappings> <action path="/myPage" className="oracle.adf.controller.struts.actions.DataActionMapping" type="oracle.adf.controller.struts.actions.DataForwardAction" name="DataForm" parameter=unknown"> </action> </action-mappings> <message-resources parameter="view.ApplicationResources"/>

These entries include:

An action mapping with the path the same as the name assigned to the icon in the Page Flow Diagram and the type set to the oracle.adf.controller.struts.actions.DataForwardAction class. Note the attribute parameter. When you specify the associated web page, the value of this attribute changes from "unknown" to the page name.
A form bean named DataForm under the <form-beans> element. JDeveloper also adds the value "DataForm" to the name attribute of the associated Action. The data form bean dynamically makes the attributes for any binding container available to forms in the application web pages and saves you the work of creating the ActionForm beans required by your applications. For more information about the data form bean, see About the Oracle ADF Data Form Bean.
A <message-resources> element pointing to the message resource bundle for the application. For more information about the default resource file, see About the Struts ApplicationResources.properties File.

When you create the associated web page (myPage.jsp, in this example) in a Struts application and add a data control, such as a table, to the page, the data page icon appears normal:

Datapage icon

At the same time, JDeveloper updates the action mapping in the struts-config.xml file as shown in bold:

<action-mappings> <action path="/myPage" className="oracle.adf.controller.struts.actions.DataActionMapping" type="oracle.adf.controller.struts.actions.DataForwardAction" name="DataForm" parameter="/myPage.jsp"> <set-property property="modelReference" value="myPageUIModel"/> </action> </action-mappings>

JDeveloper updates the value of the parameter attribute in the action mapping to the name of the associated web page file. In addition,JDeveloper adds a <set-property> definition in the action with the property set to modelReference and the value set to the name of the binding definition (pageName UIModel). When you add the first data control to the associated web page, JDeveloper also creates these project files:

A client binding definition file (myPageUIModel.xml)
A client project definition file (DataBindings.cpx), which creates the Oracle data controls registered with your application's business services

For information about how to create a data page, see Adding a Data Page to the Page Flow Diagram.

Data Actions in the Databound Page Flow

When you use the Struts Page Flow Diagram to create a data action, JDeveloper updates the struts-config.xml file. For example, if you drag the data action icon to an empty Page Flow Diagram and rename it as shown in this diagram:

Data action icon with overlaid warning

JDeveloper creates the following entries in the struts-config.xml file:

<form-beans> <form-bean name="DataForm" type="oracle.adf.controller.struts.forms.BindingContainerActionForm"/> </form-beans> <action-mappings> <action path="/myAction" className="oracle.adf.controller.struts.actions.DataActionMapping" type="oracle.adf.controller.struts.actions.DataAction" name="DataForm"/> </action-mappings>

There are two main differences between this entry and the entry for the data page in the previous section:

The action type is oracle.adf.controller.struts.actions.DataAction
The action mapping for a data action does not use the parameter attribute. Instead, it uses the <forward> element, which is initially undefined.

If you use a data action, you define the <forward> element when you drag the Forward icon to the Page Flow Diagram. For example, you can forward to another data action, a data page, a page forward, or a web page. In this example, the forward is to a web page, myPage.jsp:

Data action with forward to web page

When you add the forward to the web page, JDeveloper updates the action mapping for the data action as shown in bold:

<action path="/myAction" 
    className="oracle.adf.controller.struts.actions.DataActionMapping" 
        type="oracle.adf.controller.struts.actions.DataAction" name="DataForm">

  <set-property property="modelReference" value="myPageUIModel"/>

  <forward name="success" path="/myPage.jsp"/>

</action>

JDeveloper adds:

A <set-property> definition in the action with the property set to modelReference and the value set to the name of the binding definition (pageNameUIModel).
An action <forward> element with the default value success and, in this case, the path myPage.jsp.

When you add the first data control to the web page to which the data action forwards, JDeveloper creates the same project files as for a data page:

A client binding definition file (myPageUIModel.xml)
A client project definition file (DataBindings.cpx)

Note: For more information about how action mappings are represented in the Struts configuration file, see About the Struts Page Flow in Web Applications.

For information about how to create a data action, see Adding a Data Action to the Page Flow Diagram.

Using Pages and Page Forwards in Databound Applications

Depending on the design of your application, you may want to use a data action that forwards to a separate page forward or page instead of using a data page. You may consider this approach to be appropriate, for example, when you are forwarding to a single page from multiple data actions. The page forward performs a simple forward to a destination web page. For information about creating a page forward, see Using a Page Forward Element to Define a Struts Forward Action in the Page Flow Diagram

The Component Palette also provides a page element for use in a Struts application, but the page does not allow for page navigation management through the controller. Detailed Help on the page and page forward elements is available from the Component Palette when you right-click the element name and choose Help.

If you use data controls in a page or page forward, the web page must be associated with a data action or must be part of a data page. If you drag a data control from the Component Palette to a web page before associating it with an action class, the following dialog appears:

Select Page Flow Data Binding Option dialog

You can use this dialog to choose a data page or data action in the current context. You can also use it to set a default choice for converting any page that needs to be databound.