1. Right-click the top-level node for the data model project in the application workspace and choose New and then From Gallery.
2. In the New Gallery, expand Business Tier, select Data Controls, select the type of data control that you want to create, and click OK.
3. Complete the remaining steps of the wizard.

   For information on creating adapter-based data controls, see subsequent chapters of this guide for the different types of data controls.

When you create a data control, JDeveloper creates the data control definition file (DataControls.dcx), opens the file in the overview editor, and displays the file's hierarchy in the Data Controls panel. This file enables the data control to work directly with the services and the bindings.

You can see the code from the corresponding XML file by clicking the Source tab in the editor window.

The Data Controls panel lists all the data controls that have been created for the application's business services and exposes the hierarchies of collections (row sets of data objects), attributes, methods, and built-in operations that are available for binding to UI components.

For example, Figure 2-3 shows the Data Controls panel with the OrdersSessionEJBLocal data control. The collection nodes (such as customerFindAll, customerFindById, empFindAll) represent data collections that are returned by query methods (in this case, getter methods in the session facade). These collection objects can be dropped on to pages to create UI components such as forms and tables.

Other service methods (in the case of JPA-based data controls, methods that are not prefixed with get) are represented by method icons. These objects can be dropped on a form as a command button or link. If a method accepts arguments, those arguments appear in a Parameters node as parameters nested inside the method's node. Objects that are returned by the methods appear as well.

Figure 2-3 Data Controls Panel Main Nodes

Description of "Figure 2-3 Data Controls Panel Main Nodes"

Each returned object displays any attributes, methods, and nested collections that were defined on the associated object. Figure 2-4 shows the attributes and methods defined on the Item bean that is returned by the itemFindAll collection.

Figure 2-4 Child Nodes to Returned Collections

Description of "Figure 2-4 Child Nodes to Returned Collections"

Depending on data control type, various built-in operations are exposed. For some data controls, declarative named criteria are also available, which you can use to create search forms.Figure 2-5 shows operations and the default named criteria for an EJB data control.

Figure 2-5 Data Control Panel Operations and Named Criteria

Description of "Figure 2-5 Data Control Panel Operations and Named Criteria"

The data control framework defines a standard set of operations for data controls. These operations are implemented using functionality of the underlying business service. At runtime, when one of these data collection operations is invoked by name by the data binding layer, the data control delegates the call to an appropriate service method to handle the built-in functionality. For example, in EJB and bean data controls, the Next operation relies on the bean collection's iterator.

Most of the built-in operations affect the current row. However, the execute operation refreshes the data control itself, and the commit and rollback operations affect all changes made within the boundaries of a transaction.

The operations available vary by data control type and the functionality of the underlying business service. Here is the full list of built-in operations:

• Create: Creates a new row that becomes the current row. For JPA-based data controls, this new row is also added to the row set.

• CreateInsert: Creates a new row that becomes the current row and inserts it into the row set. Available only for ADF Business Components application modules.

• Create With Parameters: Uses named parameters to create a new row that becomes the current row and inserts it into the row set. Available only for ADF Business Components application modules.

• Delete: Deletes the current row.

• Execute: Refreshes the data collection by executing or reexecuting the accessor method.

  ExecuteWithParams: Refreshes the data collection by first assigning new values to variables that passed as parameters, then executing or reexecuting the associated query. This operation is only available for data control collection objects that are based on parameterized queries.

• First: Sets the first row in the row set to be the current row.

• Last: Sets the last row in the row set to be the current row.

• Next: Sets the next row in the row set to be the current row.

• Next Set: Navigates forward one full set of rows.

• Previous: Sets the previous row in the row set to be the current row.

• Previous Set: Navigates backward one full set of rows.

• removeRowWithKey: Tries to find a row using the serialized string representation of the row key passed as a parameter. If found, the row is removed.

• setCurrentRowWithKey: Tries to find a row using the serialized string representation of the row key passed as a parameter. If found, that row becomes the current row.

• setCurrentRowWithKeyValue: Tries to find a row using the primary key attribute value passed as a parameter. If found, that row becomes the current row.

• commit: Persists to the database all changes that are made in the current transaction.

• rollback: Reverts all changes made within the context of the current transaction.

1. Select an item in the Data Controls panel and drag it onto the visual editor for your page. For a definition of each item in the panel, see Table 2-1.

   Tip:

   If you need to drop an operation or method onto a method activity in a task flow, you can simply drag and drop it onto the activity in the diagram.

2. From the ensuing context menu, choose a UI component.

   When you drag an item from the Data Controls panel and drop it on a page, JDeveloper displays a context menu of all the default UI components available for the item you dropped. The components displayed are based on the libraries in your project.

   Figure 2-6 shows the context menu displayed when a data collection from the Data Controls panel is dropped on a page.

   Figure 2-6 Dropping Component From Data Controls Panel

   
   Description of "Figure 2-6 Dropping Component From Data Controls Panel"

   Depending on the component you select from the context menu, JDeveloper may display a dialog that enables you to define how you want the component to look. For example, if you select ADF Table from the context menu, the Edit Table Columns dialog launches.

   The UI components selected by default are determined first by any UI hints set on the corresponding business object. If no UI hints have been set, then JDeveloper uses input components for standard forms and tables, and output components for read-only forms and tables. Components for lists are determined based on the type of list you chose when dropping the data control object.

   Once you select a component, JDeveloper inserts the UI component on the page in the visual editor. For example, if you drag a collection from the Data Controls panel and choose ADF Table from the context menu, a table appears in the visual editor, as shown in Figure 2-7.

   Figure 2-7 Databound UI Component: ADF Table

   
   Description of "Figure 2-7 Databound UI Component: ADF Table"

   By default, the UI components created when you use the Data Controls are bound to attributes in the ADF data control and may have built-in features, such as:

   • Databound labels

   • Tooltips

   • Formatting

   • Basic navigation buttons

   • Validation, if validation rules are attached to a particular attribute.

   The default components are fully functional without any further modifications. However, you can modify them to suit your particular needs. Each component and its various features are discussed further in Creating a Databound Web User Interface in Developing Fusion Web Applications with Oracle Application Development Framework.

   Tip:

   If you want to change the type of ADF databound component used on a page, the easiest method is to use either the visual editor or the structure window to delete the component, and then drag and drop a new one from the Data Controls panel. When you use the visual editor or the structure window to delete a databound component from a page, if the related binding objects in the page definition file are not referenced by any other component, JDeveloper automatically deletes those binding objects for you (automatic deletion of binding objects will not happen if you use the source editor).

When a web application is built using the Data Controls panel, JDeveloper does the following:

• Creates a DataBindings.cpx file in the default package for the project (if one does not already exist), and adds an entry for the page.

  A DataBindings.cpx files defines the binding context for the application. The binding context is a container object that holds a list of available data controls and data binding objects. For information on binding context, see What Happens at Runtime: How the Binding Context Works in Developing Fusion Web Applications with Oracle Application Development Framework. The DataBindings.cpx file maps individual pages to the binding definitions in the page definition file and registers the data controls used by those pages. For information on data bindings, see Working with the DataBindings.cpx File in Developing Fusion Web Applications with Oracle Application Development Framework.

• Creates the adfm.xml file in the META-INF directory. This file creates a registry for the DataBindings.cpx file, which allows the application to locate it at runtime so that the binding context can be created.

• Registers the ADF binding filter in the web.xml file.

  The ADF binding filter preprocesses any HTTP requests that may require access to the binding context. For information on the binding filter configuration, see Configuring the ADF Binding Filter in Developing Fusion Web Applications with Oracle Application Development Framework.

• Adds several libraries to the view project, including the following:

  • ADF Faces Databinding Runtime

  • ADF Model Runtime

  • MDS Runtime

• Adds a page definition file (if one does not already exist for the page) to the page definition subpackage. The default subpackage is view.pageDefs in the adfmsrc directory.

  Tip:

  You can set the package configuration (such as name and location) in the ADF Model settings page of the Project Properties dialog (accessible by double-clicking the project node).

  The page definition file (pageNamePageDef.xml) defines the ADF binding container for each page in an application's view layer. The binding container provides runtime access to all the ADF binding objects for a page. For information on the page definition file, see Working with Page Definition Files in Developing Fusion Web Applications with Oracle Application Development Framework.

  Tip:

  The current binding container is also available from AdfContext for programmatic access.

• Configures the page definition file, which includes adding definitions of the binding objects referenced by the page.

• Adds the given component to the page.

  These prebuilt components include ADF data binding expression language (EL) expressions that reference the binding objects in the page definition file. For information on ADF data binding EL expressions creation, see Creating ADF Data Binding EL Expressions in Developing Fusion Web Applications with Oracle Application Development Framework.

• Adds all the libraries, files, and configuration elements required by the UI components. For information on the artifacts required for ADF Faces databound components, see the ADF Faces Configuration appendix in Developing Web User Interfaces with Oracle ADF Faces.

When a data control modifies a collection, the data control must instantiate a new instance of the collection in order for the ADF Model layer to understand that it has been modified. In other words, although some action in the client may change the collection, that change will not be reflected in the UI unless a new instance of the collection is created. However, for performance reasons, accessor and method iterators cache their results set (by default, the cacheResults attribute on the iterator is set to true). This setting means that the iterator is refreshed and a new instance of the collection is created only when the page is first rendered. The iterator is not refreshed when the page is revisited, for example, if the page is refreshed using partial page rendering, or if the user navigates back to the page.

For example, say you want to allow sorting on a table on your page. Because you want the page to refresh after the sort, you add code to the listener for the sort event that will refresh the table using partial page rendering (for information on partial page rendering content, see Rendering Partial Page Content in Developing Web User Interfaces with Oracle ADF Faces). Because the instance of the collection for the table has already been instantiated and is cached, the accessor iterator will not reexecute, which means that a new instance of the collection with the new sort order will not be created, so the sort order on the page will remain the same.

To work around this issue, you can either configure the iterator so that it does not cache the results, or you can place a button on the page that can be used to reexecute the iterator when the page is refreshed.