Using a Custom Method to Set the Bind Parameters in a View Object

This topic describes the steps involved in creating the Model, Controller, and View Layers of a databound Struts application that allows users to:

• Enter search criteria in a Struts HTML form
• View the results in another web page

This topic contains the following sections:

• Overview
• Customizing the View Object and Creating the Associated Custom Method
• Creating the Search Page Functionality
• Creating the Results Page and Finishing the Page Flow
• Running the Application

Overview

When the application is complete, running it from the Page Flow Diagram first displays the search request web page, which looks like this:

The search results web page looks like this:

The following diagram shows a simple view of the steps you need to take in the Model, Controller, and View layers to create this page flow:

Following is a more detailed discussion of the high-level steps you need to take in the model, controller, and view layers to create this page flow:

Model Layer

• Create Business Components

  The steps described in End-To-End Solutions for Struts, JSP, and Oracle ADF begin to prepare the model layer for this end-to-end solution. That topic describes the information and steps common to all of the end-to-end solutions that use Struts, JSP, and Oracle ADF Business Components.

• Customize the View Object

  By default, a view object query returns all records in the associated table. The scenario allows users to search for records that meet the criteria they enter in two fields. This behavior requires a where clause in the view object query. To modify the view object query, you edit the View Object in the View Object Editor.

• Create a custom method in the Application Module Class

  Oracle ADF application modules are business components that represent particular application tasks. They are defined partly by XML files and optionally by an application module Java class. For this scenario, you need to add a custom method that sets the binding variables for the where clause in the view object query. To do this, you edit the application module class.

• Make the custom method available

  Once you have created the custom method in the application module class, you need to make it available for clients (that is, web pages) to call. To do this, you use the Application Module Editor. Once you have made it available, JDeveloper displays the method in the Data Control Palette.

Controller Layer (Design Time)

• Create a Dynamic Form Bean

  This page flow uses a form bean to collect the parameter values for the search query. You use the Structure window and Property Inspector to create the form bean. You also use the Structure window and Struts Configuration Editor to add the form bean to the page forward and data actionyou create for this scenario.

• Create a Page Forward

  The page forward element represents a Struts action subclass that always forwards to a specified destination web page. You use the page forward whenever you want to work with the Struts controller to manage page navigation. In this scenario the action associated with the web page displays the search page, which is the first page in the page flow. The search page contains a link to a data action, which executes the query.

  You create page forwards using the the Page Flow Diagram and the Component Palette. The Page Flow Diagram is a graphical modeler that allows you to visually represent the action mapping elements of the struts-config.xml file and build a page flow quickly. The Component Palette provides visual access to the components available for a databound Struts application.

• Create a Data Action

  Oracle ADF provides the data action to prepare the binding context for databound web pages and to execute custom business service methods exposed through the model. Your databound web application works with the data action class through an action mapping in the Struts configuration file. The action mapping uses an additional <set-property> element, modelReference, which provides the information required to set up the Oracle ADF data binding objects. In this scenario the data action executes the query using the values input by the user in the search page.

  You create data pages using the the Page Flow Diagram and the Component Palette. You add the query method to the data page by dragging it from the Data Control Palette onto the data page icon.

• Create a Data Page

  The data page represents a combination of an Oracle ADF action subclass, forward, and web page. The page flow diagram is simplified to show a single element instead of three. Oracle ADF provides the data page to prepare the binding context for databound web pages. The data page manages the model data binding for the page. When you create the web pages, JDeveloper creates data bindings based on the business components you created in the Model layer.

  You create data pages using the the Page Flow Diagram and the Component Palette.

• Create Forwards and Page Links

  Adding a Forward component creates a Struts local <forward> element. Adding the two Forwards between the data pages updates the Struts <action> element definition for the data pages in the web application's struts-config.xml file and makes it possible for the user to move back and forth between the pages in the application. You create the forwards using the Page Flow Diagram and the Component Palette.

View Layer

• Create Databound JSP Pages Using Data Controls

  The content of the JSP pages determines what the user sees on the application web pages. You display and update data on the page by adding data bindings that define the interaction between the UI components and the business components. The data bindings you add to the web pages use the EL (expression language) syntax. EL expressions such as ${bindings.EmployeesView3} give direct access to the accessor methods of each binding's implementing class.

  The JSP pages for this application use a variety of data bindings to display:
  • A search form
  • Search results

  You create the JSP pages in the Visual Editor, and you add data controls to the pages by dragging them from the Data Control Palette. The input form and table you add automatically become databound through a reference to the Oracle ADF binding objects created in the Oracle ADF binding context.

Controller Layer (Run Time)

• Run Application

  At runtime the user's selections are set in the Request object for the each page, which communicates with the data page in the Oracle ADF controller layer. The data page updates the Oracle ADF binding context with the information it receives and initiates the Struts action mapping to display the appropriate page. The web page's Oracle ADF binding expressions, when interpreted, provide the information needed to access the binding context to retrieve and render the data.

Customizing the Query and Creating an Associated Custom Method

To create the custom method and make it available to clients:

1. Specify a custom query for the View Object definition for EmployeesView.

   In the query pane of the View Object Editor, add the Where clause:

   Employees.SALARY > :1 and Employees.DEPARTMENT_ID = :2

   as shown in the following screen capture:

   

   Adding this Where clause modifies the query that defines the view object. Now you need to define a method that sets the binding variables

2. Add the custom method to the application module Java class.

   Add the following code to the application module class file:

   public void setBindVars(Double salary, Integer departmentId)
{
 System.out.println("***In setBindVars*****");
 ViewObject vo = findViewObject("EmployeesView1");
 vo.setWhereClauseParam(0, salary);
 vo.setWhereClauseParam(1, departmentId);
 vo.executeQuery();
}

   For more information, see Extending the Application Module.

3. Make the method available to clients.

   In the System or Application Navigator, right-click the application module definition and choose Edit . Select the Client Interface node. Next, select setBindVars() in the Available list and move it to the Selected list. This step makes the method available from the Data Control Palette.

Creating the Search Page Functionality

Creating the search page in this page flow requires the following steps:

• Create a page forward and a data action.
• Create a dynamic form bean ( org.apache.struts.action.DynaActionForm) to hold the salary and department ID properties.
• Add the setBindVars method to the data action and set additional properties using the <set-properties> element.
• Create a JSP page with a search form.

To create the page forward and data action for the search:

1. Open the Struts Page Flow Diagram.

2. In the Component Palette, click the Page Forward element and drag it to the Page Flow Diagram. Name the page forward /searchRequest .

   This step creates the following action mapping in the struts-config.xml file:

   <action path="/searchRequest" forward="unknown"/>

   When you add a page forward element as the first action mapping for a page flow, JDeveloper adds the <action> element with the <parameter> element set to "unknown" (you will set the value of this in the next step, when you create the JSP page associated with the page forward).

   For more information about action mapping using the Oracle ADF action subclasses, see About the Page Flow in Databound Struts Applications.

3. Double-click the /searchRequest icon and click OK in the Select or Create Page dialog box to create a JSP page named searchRequest.jsp . Deselect the Edit this page now? checkbox when you do this. You will edit the page later.

   JDeveloper creates the searchRequest.jsp file and sets the value of the forward attribute of the action defined in the previous step:

   <action path="/searchRequest" forward="/searchRequest.jsp"/>

4. In the Component Palette, click the Data Action element and drag it to the Page Flow Diagram. Name the data action /executeQuery .

   This step creates the following entry in the struts-config.xml file:

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

   When you add a data action, JDeveloper uses Oracle ADF subclasses for the action className and type attributes. For more information about action mapping using the Oracle ADF action subclasses, see About the Page Flow in Databound Struts Applications.

To create the dynamic form bean and associate it with the page forward and data action:

1. Create a new form bean .

   In the Create New Form Bean dialog enter the name myFormBean . Choose org.apache.struts.actions.DynaActionForm as the bean type. Select the Dynamic check box and click OK.

2. Click on the Form Properties tab. Add the following properties:

   • Name: salary and Type: java.lang.Double
   • Name: departmentId and Type: java.lang.Integer

   

   These two steps define the new form bean in the Struts configuration file:

   <form-bean name="myFormBean" type="org.apache.struts.action.DynaActionForm" dynamic="true"
 <form-property name="salary" type="java.lang.Double"/>
 <form-property name="departmentId" type="java.lang.Integer"/>
</form-bean>

3. Associate the page forward with myFormBean.

   In the Structure window, right click the searchRequest node and select Edit... . In the Struts Configuration Editor, select the Form Beans node. In the Form Beans pane, select myFormBean to associate it with the searchRequest action.

   

   When you create page forwards, data pages, and data actions, JDeveloper by default associates them with the DataForm bean, which dynamically makes the attributes for any binding container available to the form and saves you the work of creating the ActionForm beans required by your applications. However, the search form you create in this scenario cannot use the DataForm bean, so you must change the name attribute for the search-related actions to myFormBean.

4. Associate the executeQuery data action with myFormBean.

   In the Structure window, right click the /executeQuery node and choose Edit... . In the Struts Configuration Editor, choose the Form Beans node. In the Form Beans pane, click on myFormBean to associate it with the executeQuery data action.

To add a method to the data action:

1. Add the setBindVars() method to the executeQuery data action.

   You can add a method to the data action without subclassing the data action by dragging the method from the Component Palette to the data action icon in the Page Flow Diagram. The following diagram shows how the setBindVars() method appears in the Data Control Palette.

   

   When you drag a method to a data action, JDeveloper adds several properties that define the method to the action mapping in the Struts configuration file:

   <set-property property="methodName" value="executeQueryUIModel.setBindVars"/>
<set-property property="resultLocation" value="${requestScope.methodResult}"/>

2. Define the parameter names for the setBindVars() custom method.

   In the Structure window, right click the Struts Config node and choose Edit.... In the Struts Configuration Editor, select the Action Mappings node. In the Action Mappings pane, click on executeQuery and select the Properties tab. Modify the following properties:

   • paramNames[0]. Set the Value to ${param.salary}
   • paramNames[1]. Set the Value to ${param.deptno}

   as shown in the following screen capture:

   

   JDeveloper adds the following entries to the action for the executeQuery data action:

   <set-property property="numParams" value="2"/>
<set-property property="paramNames[0]" value="${param.salary}"/>
<set-property property="paramNames[1]" value="${param.deptno}"/>

3. Click OK to close the Struts Configuration Editor.

To create the search page:

1. In the Page Flow Diagram, double-click on the /searchRequest icon to open searchRequest.jsp in the Visual Editor.

2. Select Struts HTML in the Component Palette.

   You must use the Struts HTML tags for the search form, because the HTML form tag does not specify an associated action.

3. From the Component Palette, drag a form tag to the JSP page. JDeveloper displays the JavaServer Page Tag Editor.

   In the JavaServer Page Tag Editor, set the value of the action attribute to executeQuery.do and click OK.

4. From the Component Palette, drag a text tag inside the form.

   In the JavaServer Page Tag Editor, set the value of the property attribute to salary and click OK . Add the label Salary greater than: before the text input field.

5. Drag a second text tag inside the form.

   In the JavaServer Page Tag editor, set the value of the property attribute to deptno and click OK .

   Add the label Department ID is: before this text input field.
6. Drag a submit tag below the text input fields.

7. (Optional) Add a heading above the form.

   

8. Save the page.

9. Return to the Page Flow Diagram and from the Component Palette, drag a Page Link element between the /searchResults and /executeQuery icons. The Page Flow Diagram looks like the following screen capture:

   

   Note: Although adding the Struts HTML form and setting the action for the form creates a page link, the Page Flow Diagram does not automatically reflect edits made inside JSP pages. For more information, see About Web Page Edits and the Page Flow Diagram.

Creating the Results Page and Finishing the Page Flow

To create the results page and finish the page flow:

1. Open the Struts Page Flow Diagram if it is not already open.

2. In the Component Palette, click the Data Page element and drag it to the Page Flow Diagram. Name the data page /searchResults .

   This step creates a new action mapping in the struts-config.xml file.

3. Double-click the data page icon to open the Select or Create Page dialog box and create a JSP page named searchResults.jsp . Make sure the Edit this page now? checkbox is selected and click OK to open the page in the Visual Editor.

4. In the Data Control Palette, select EmployeesView. Select Read-Only Table from the Drag and drop as list and drag EmployeesView to the empty JSP page:

   The Data Control Palette displays the business services available for the page. In this step, you are adding a read-only form that uses a view object, EmployeesView1, to display the search results from the Employees table in the HR database.

   When you add the databound table to the web page, JDeveloper creates two Oracle ADF project files, DataBindings.cpx and searchResultsModelUI.xml, in the view folder. DataBindings.cpx defines the binding container for the application as a whole. searchResultsModelUI.xml is the model reference, which defines the data controls used by the individual web page. Because these files completely define the method and parameters needed to display the table, you do not need to take many of the steps that you had to take to define and use the custom method you used for the search form.

   At this point, JDeveloper also updates the struts-config.xml file to define the model reference in the associated <action> element by adding a <set-property> element in the action mapping:

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

   For more information about the Oracle ADF project files, see About the Oracle ADF Project Files. For more information about the Data Control Palette, see Inserting UI Components Using the Data Control Palette.

5. Save and close searchResults.jsp.

6. Add a Page Link from the /searchResults icon to the /searchRequest icon.

   This adds a link to the bottom of the generated search results page.

7. Add a Forward from the /executeQuery icon to the /searchResults icon.

   This defines the <forward> element for the executeQuery data action:

   <forward name="success" path="/searchResults.do"/>

   The Page Flow Diagram should look similar to this:

   

Running the Application

You are ready to run the databound search page from the Struts Page Flow Diagram.

To run the application:

1. Return to the Page Flow Diagram by clicking on the struts-config.xml tab above the Visual Editor.
2. Right-click on the searchRequest icon and select Run.

3. When you enter values in the search fields and click Submit, the application displays the search results.

   Click on the link below the search results table to perform another search.

Copyright © 1997, 2004, Oracle. All rights reserved.