| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g (10.1.3.1.0) Part Number B25947-01 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g (10.1.3.1.0) Part Number B25947-01 |
|
|
View PDF |
At design time, you use the Data Control Palette to perform drag and drop data binding for JSF, JSP/Struts, and Swing applications. Each application module in the workspace appears automatically in the Data Control Palette. Using the SRService application module from the SRDemo application as an example this section highlights exactly what you'll see in the Data Control Palette when you work with your own application modules.
Figure 10-3 shows the SRService application module that implements the business service layer of the SRDemo application. Notice that its data model includes numerous view object instances, including several master/detail hierarchies. The view layer of the demo consists of JSF pages whose UI components are bound to data from the view object instances in the SRService's active data model, and to built-in operations and service methods on its client interface. In Section 10.6, "Overview of How SRDemo Pages Use the SRService", you'll find an overview of exactly what aspects of this application module each page uses.
By default, an application module will appear in the Data Control Palette as a data control named AppModuleNameDataControl. For example, the SRService originally had the name SRServiceDataControl. To change the default data control name to a shorter, or simply more preferable name, do the following:
To change the application module name:
Open the application module in the Application Module Editor.
Open the Custom Properties page.
In the Name combobox, select the DATA_CONTROL_NAME property from the dropdown list.
Enter your preferred data control name in the Value field and click OK to close the wizard.
Figure 10-4 shows the custom property setting that changed the data control name of the SRService from the default SRServiceDataControl to the shorter SRService name that matches the name of the application module. You'll notice the change immediately in the Data Control Palette.
Note that as you begin to bind data from the application module to your application pages or panels, the data control name for your application module will appear in the DataBindings.cpx file in your user interface project and in each data binding page definition XML file. In addition, you might refer to the data control name in code when needing to work programmatically with the application module service interface. For this reason, if you plan to change the name of your application module, Oracle recommends doing this change before you being building your view layer.
|
Note: In JDeveloper Release 3, if you decide to change the application module's data control name after you have already referenced it in one or more pages, you will need to open the page definition files where it is referenced and update the old name to the new name manually. Future releases of JDeveloper may extend its refactoring support to make renaming a data control simpler. |
Figure 10-5 illustrates how the Data Control Palette displays the view object instances in the SRService's active data model. Each view object instance appears as a named data collection whose name matches the view object instance name. Note the hierarchical structure of the data collections, and that for viewing simplicity, the figure omits some details in the tree that appear for each view object. These additional view object details are highlighted in Section 10.3.6, "How View Objects Appear in the Data Control Palette". The Data Control Palette reflects the master/detail hierarchies in your application module data model by displaying detail data collections nested under their master data collection.
The Data Control Palette also displays each custom method on the application module's client interface as a named data control custom operation whose name matches the method name. If a method accepts arguments, they appear in a Parameters folder as operation parameters nested inside the operation node.
When you initially add a view object instance to the data model, if you haven't typed in an instance name yourself, it gets added with a name composed of the view object name with a numeric suffix appended. For example, adding an instance of a ServiceRequests view object to the data model, the default view object instance name would be ServiceRequests1. You can easily rename the view object instances in the Data Model page of the Application Module Editor.
As you begin to bind data from the data collections in the Data Control Palette to your application pages or panels, in addition to the data control name, the data collection names will be referenced in the page definition XML files used by the ADF Model data binding layer. Since the names of your view object instance in the application module data model are used as the names of these data collections, Oracle recommends reviewing your view object instance names before using them to build data bound pages to ensure the names are descriptive.
|
Note: In JDeveloper Release 3, if you decide to change a view object instance name after you have already referenced it in one or more pages, you will need to open the page definition files where it is referenced and update the old name to the new name manually. Future releases of JDeveloper may extend its refactoring support to make renaming a view object instance simpler. |
The application module data control exposes two data control built-in operations named Commit and Rollback as shown in Figure 10-6. At runtime, when these operations are invoked by the data binding layer, they delegate to the commit() and rollback() methods of the Transaction object associated with the current application module instance. Note that the Operations folder in the data controls tree omits all of the data collections and custom operations for a more streamlined view.
|
Note: In an application module with many view object instances and custom methods, you may need to scroll the Data Control Palette display to find the Operations folder that is the direct child node of the data control. This folder is the one that contains its built-in operations. |
Figure 10-7 shows how each view object instance in the application module's data model appears in the Data Control Palette. The view object attributes are displayed as immediate child nodes of the corresponding data collection. If you have selected any custom methods to appear on the view object's client interface, like the performSearch() method in the figure, they appear as custom operations immediately following the view object attribute at the same level. If the method accepts arguments, these appear in a nested Parameters folder as operation parameters.
As shown in Figure 10-7, the Operations folder under the data collection displays all its available built-in operations. If an operation accepts one or more parameters, then they appear in a nested Parameters folder. At runtime, when one of these data collection operations is invoked by name by the data binding layer, the application module data control delegates the call to an appropriate method on the ViewObject interface to handle the built-in functionality. The built-in operations fall into three categories: operations that affect the current row, operations that refresh the data collection, and all other operations.
Create — creates a new row that becomes the current row
Delete — deletes the current row
First — sets the current row to the first row in the row set
Last — sets the current row to the last row in the row set
Previous — sets the current row to the previous row in the row set
Next — sets the row to the next row in the row set
Previous Set — navigates forward one full page of rows
Next Set — navigates backward one full page of rows
setCurrentRowWithKey — tries to finds a row using the serialized string representation of row key passed as a parameter. If found, it becomes the current row.
setCurrentRowWithKeyValue — tries to finds a row using the primary key attribute value passed as a parameter. If found, it becomes the current row.
Execute — refreshes the data collection by (re)executing the view object's query, leaving any bind parameters at their current values.
ExecuteWithParams — refreshes the data collection by first assigning new values to the named bind variables passed as parameters, then (re)executing the view object's query.
|
Note: TheExecuteWithParams operation only appears for view objects that have defined one or more named bind variables at design time. |
If you build composite application modules, by including nested instances of other application modules, the Data Control Palette reflects this component assembly in the tree hierarchy. For example, assume that in addition to the SRDemo application's oracle.srdemo.model.SRService application module that you have also created the following application modules in the same package:
An application module named ProductService, and renamed its data control to ProductService
An application module named CompositeService, and renamed its data control to CompositeService
Then assume that you've added two view object instances named OtherViewObject and AnotherViewObject to the data model of CompositeService and that on Application Modules page of the Application Module Editor you have added an instance of the SRService application module and an instance of the ProductMaintenance application module to reuse them as part of CompositeService. Figure 10-8 illustrates how your CompositeService would appear in the Data Control Palette. The nested instances of SRService and ProductService appear in the palette tree display nested inside of the CompositeService data control. The entire data model and set of client methods that the nested application module instances expose to clients are automatically available as part of the CompositeService that reuses them.
One possibly confusing point is that even though you have reused nested instances of SRService and ProductService inside of CompositeService, the SRService and ProductService application modules also appear themselves as top-level data control nodes in the palette tree. JDeveloper assumes that you might want to sometimes use SRService or ProductService on their own as a separate data controls from CompositeService, so it displays all three of them. You need to be careful to perform your drag and drop data binding from the correct data control. If you want your page to use a view object instance from the nested SRService instance's data model that is an aggregated part of the CompositeService data control, then ensure you select the data collection that appears as part of the CompositeService data control node in the palette.
It is important to do the drag and drop operation that corresponds to your intended usage. When you drop a data collection from the top-level SRService data control node in the palette, at runtime your page will use an instance of the SRService application module acquired from a pool of SRService components. When you drop a data collection from the nested instance of SRService that is part of CompositeService, at runtime your page will use an instance of the CompositeService application module acquired from a pool of CompositeService components. Since different types of application module data controls will have distinct transactions and database connections, inadvertently mixing and matching data collections from both a nested application module and a top-level data control will lead to unexpected runtime behavior. Forewarned is forearmed.
