Working with the Oracle ADF Model Layer

Generating a Session Bean on Selected JPA Entities

You can generate session beans on JPA entities.

To generate a session bean on selected JPA entities:

1. Right-click your JPA project to open the context menu.

2. In the context menu, select New > Session Bean (EJB 3.x) from JPA Entities.

3. On the Session Bean (EJB 3.x) page of the Create EJB 3.x Session Bean from JPA Entities wizard, specify a Java package and a class name. Then click Next.

4. On the Select Entities page, indicate which entities to access via the generated session bean. Then click Finish.

5. You can view the generated session bean in the Project Explorer.

Generating a JSF Managed Bean

You can generate a JSF Managed Bean which is a wrapper on a session bean.

To generate a JSF Managed Bean:

1. Right-click the session bean in the Project Explorer to open the context menu.

2. In the context menu, select New > Data Model Components > Generate JSF Managed Bean.

3. On the Managed Bean page of the Create Managed Bean wizard, specify the Java package and the Session bean to wrap. Then click Finish.

4. View the generated JSF Managed Bean in the Project Explorer.

Generating a Session Bean and a JSF Managed Bean using the Data Components Model Wizard

You can generate a Session Bean facade on selected entities and generate a JSF Managed Bean to wrap the services in the session facade using the Data Components Model Wizard.

To generate a Session Bean and a JSF Managed Bean using the Data Components Model Wizard:

1. Open the New Gallery by selecting File > New > Other.

2. Expand Application Development Framework, and double-click Data Model Components.

3. On the Session Bean (EJB 3.x) page of the Create Data Model Components wizard, specify the Java package and class name for the session bean. Then click Next.

4. On the Select Entities page, indicate which entities to access via the generated session bean, then click Next.

5. On the Data Object page, select JSF Managed Bean or ADF Data Control as the Data object type. Then specify name and location details for the Managed Bean and click Finish. For more information on ADF Model Data Binding see "Working with ADF Model Data Binding".

6. In the Project Explorer, view the generated session bean facade in the JPA project and the JSF Managed Bean in the web project.

Editing a Session Bean

You can edit sessions beans.

To edit the session bean facade:

1. Right-click the session bean to open the context menu.

2. In the context menu, select Data Model Components > Edit Session Bean Facade.

3. On the Select Entities page, indicate which entities you want to add to or remove from the session bean facade.

For more information on EJB session beans, see "Understanding Enterprise JavaBeans" in the Oracle Fusion Middleware Programming Enterprise JavaBeans for Oracle WebLogic Server.

Creating ADF Data Controls

Once you have your application's services in place, you can use OEPE to create data controls that provide the information needed to declaratively bind UI components to those services. In an ADF application, you can create a data control for the session bean or POJO, and that data control will contain representation of all data on the bean. The data control consists of a number of XML metadata files that define the capabilities of the service that the bindings can work with at runtime.

To create a data control from the Project Explorer:

1. In the Project Explorer, right-click the session bean or POJO for which you want to create a data control.

2. From the context menu, select Model Components > Create ADF Data Control.

Alternatively, you can also create a data control from the New Gallery.

To create a data control from the New Gallery:

1. Right-click your model project and select New > Other from the context menu.

2. In the New gallery, choose Oracle > Application Development Framework > ADF Data Control.

3. On the Bean Class page, select project [Project] and the bean [Bean Class] from which to create the data control. Note: The Project dropdown list contains all eligible projects in the workspace.

4. Preview and confirm the project changes on the Summary page and click Finish.

The metadata file datacontrols.dcx is created in the adfmsrc > model node of your Model project, as shown in Figure: Data Control File in Project Explorer. When you create a data control based on an EJB session bean, the data control contains a representation of all the methods exposed on the bean, as well as underlying entity beans, and the methods and properties exposed on those.

Data Control File in Project Explorer

For a description of Oracle ADF Data Bindings metadata files and links to more information, see Appendix A Oracle ADF XML Files.

With a web page in focus, you can open the Data section of the Palette to view and drag-and-drop data controls, JSF Managed Beans, and page variables on to the page, shown in Figure: Data Palette.

Data Palette

Using the ADF Data Control Manager

The Data Control Manager shows all the data controls available to your ADF project. Use the Data Control Manager to view details about your data control objects, including the data type associated with your Java elements, and related artifacts.

The Data Controls tab of the Data Control Manager shows the data control tree. The Structure Definitions tab shows the structure definition control objects. Every data control object exposes the structure definition of your data objects and is shown in the Structure Definitions view. When you are customizing your data structure in the 12c runtime, you customize the structure definition object. Customizing a structure definition object impacts every data control object that exposes that structure definition object.

Note that in 12c applications you can customize your data structure definition object, but in 11g applications, the Data Control Manager shows your available data controls, java elements, and object types, but doesn't allow customizing of the structure definition object.

There are a three ways to access the Data Control Manager:

1. Opening a data control .dcx file.

2. When creating a data control, the last page of the wizard has a check box that you can select to open the data control manager.

3. If you are editing a ADF page, you can open the manager through the Data Palette view: Palette > Data tab > right-click the control > Data Control Manager.

Figure: Data Control Manager - Show Structure Definition shows the Data Control Manager with the Show structure definition link available. When you select a data control object, with an editable structure definition, this link changes to Edit structure definition as shown in Figure: Data Control Manager - Edit Structure Definition.

Clicking on the Edit structure definition link selects the appropriate structure definition on the second tab of the Data Control Manager, as shown in Figure: Data Control Manager - Edit List of Values. In this dialog, you can enter custom label and tool tip text used by a widget that is rendering the selected data control object on a ADF web page. You can also create, edit, or delete a list of values for the structure definition, as shown in. Use the list of values to determine which values are available for the selected attribute defined by either a collection accessor or an attribute of a collection accessor.

In the web page editor, when you select from a list of available widgets for an attribute of a data control, OEPE determines whether the list of values can be used at runtime. If yes, it displays the name of the list of values in the Edit List Binding dialog, as shown in Figure: Data Control Manager - Edit List Binding.

Data Control Manager - Show Structure Definition

Data Control Manager - Edit Structure Definition

Data Control Manager - Edit List of Values

Data Control Manager - Edit List Binding

Using the Data Palette to Create UI Components

OEPE provides you with a predefined set of UI components from which to choose for each data control item you drop.

To use the Data Palette to create UI components:

1. Select an item in the Data Controls panel and drag it onto the editor for your page. You can also drag it and drop it from the data palette to the Outline view.

2. From the ensuing context menu, select a UI component. When you drag an item from the Data palette and drop it on a page or task flow, OEPE displays a context menu of all the default UI components available. The UI components currently supported are: Form, Graph, Navigation, Single Selection, and Table.

   Depending on the component you select from the context menu, OEPE displays a dialog that enables you to define how you want the component to look.

   For example, if you select Form > ADF Form, the Create Form dialog is opened, as shown in Figure: Create Form Dialog. You can specify if you want it to be a Read-Only Form. Additionally, you can edit the Fields table to change the Display Label, Value Binding, and Component to Use elements. Additionally, you can add or delete value bindings, and specify if you want to include navigation controls and a submit button.

   Create Form Dialog

   
   

   The resulting code appears in the source editor for your page.

3. You can click the Edit Component Definition toolbar button on the Properties window to edit the properties of your UI component.

For more information about using the data palette, see the "Using ADF Data Controls" section of the Oracle Fusion Middleware Developing Applications with Oracle ADF Data Controls.

To run the ADF page containing your newly added component, right-click the page in the Project Explorer and select Run As > Run on Server. For more information, see Deploying an Oracle ADF Application.

Using the Bindings Tab in the Properties Window

You can view the bindings associated with a page in the Bindings tab of the Properties window. The tab provides contextual bindings information based on the tag currently in focus in the editor, as shown in Figure: Bindings tab in Properties Window. The Bindings tab provides the following features:

• If you place the cursor in the jsp:root tag of the page, the Bindings tab provides an overview of all the bindings used in the page.

• Each binding is listed along with its iterator and associated data control, in addition to the tags it is used in.

• Click on the binding id or iterator to open the item in the page definition editor.

• Click on a tag to highlight that portion of the source code in the web page editor.

Bindings tab in Properties Window

Working with Page Definition Files

Page definition files define the binding objects that populate the data in UI components at runtime. For every page that has ADF bindings, there must be a corresponding page definition file that defines the binding objects used by that page. Page definition files provide design time access to all the ADF bindings. At runtime, the binding objects defined by a page definition file are instantiated in a binding container, which is the runtime instance of the page definition file.

When you drag and drop an item from the Data Palette to the page, OEPE automatically creates a page definition file for that page and adds definitions for each binding object referenced by the component. For each subsequent databound component you add to the page, OEPE automatically adds the necessary binding object definitions to the page definition file. By default, the page definition files are located in the view.PageDefs package in the adfmsrc directory of the web project.

OEPE names the page definition files using the following convention:

pageNamePageDef.xml

where pageName is the name of the JSP page. For example, if the JSF page is named home.jsp, the default page definition file name is homePageDef.xml.

Opening a Page Definition File in the Page Definition Editor

You can open a page definition file in the page definition editor using any of the following ways:

• Right-click the page in the Project Explorer and select Open Page Definition. If the page does not have an associated page definition file, OEPE asks if you want to create it.

• With a page active in the editor, from the main menu, select Navigate > Go To > Page Definition.

• In the Bindings tab of the Properties view, click on a binding id to open it in the page definition editor.

• If the page definition file already exists, you can double-click it in the Project Explorer.

Understanding the Page Definition Editor

The page definition editor allows you to view and configure bindings, as shown in Figure: Page Definition Editor. It consists of the following sections:

• Outline: Shows three different types of objects: bindings, executables, and the data controls in use. You can also add a new binding or executable using the New button (green plus icon). When you click an item in the Outline section, its corresponding details are shown in the right pane in the Binding (for bindings) and Iterator Binding (for executables) section.

• Binding: Displays information about the binding currently selected in the Outline section.

  Page Definition Editor

  
  

• Executable: Displays information about the executable currently selected in the Outline section.

• Iterator Binding: Displays information about the currently selected iterator in the Outline section.

• Usage: Displays usage information. For a binding, it displays the tags that use it. For an executable, it displays the bindings that use it. For a data control, the bindings and executables that use it are displayed.

• Bindings Summary or Executable Summary, Validation Details, Usage Details: These sections display summary information when the parent Bindings or Executables folder is selected in the Outline section.

• Data Control: Displays the Id and Type of the currently selected data control.

• Data Control Child: Displays the Id and Type of the currently selected Data Control child element.

The toolbar icons on the top right corner of the page definition editor are:

• Open file_name: Click to open the associated JSP page, where file_name is the name of the file.

• Open 'adfmsrc/view/DataBindings.cpx': Click to open the DataBindings.cpx file.

• Open this page definition using the XML editor

• Hide Outline: Click to hide the Outline section.

The page definition editor is tolerant of artifacts that are not supported. For example, in Figure: Unsupported Artifact, the editor recognizes the tasteful executable even though the artifact is not supported.

Unsupported Artifact

If a page definition file is modified outside of the page definition editor, the editor will inform you via the External Changes Detected dialog. The contents of the file are then reloaded. Additionally, the editor also supports Forward and Back navigation from the Eclipse IDE. You can navigate previous selections using either the left and right arrows on the Eclipse toolbar or the main menu items Navigate > Back and Navigate > Forward.

Understanding Bindings and Executables

Declarative bindings abstract the details of accessing data from data collections in a data control and of invoking its operations.

Bindings

There are three types of Bindings binding objects used to bind UI components to objects on the data control:

• Value: Displays data in UI components by referencing an iterator binding. Each discrete UI component on a page that will display data from the data control is bound to a value binding object. Value binding objects include:

  • Attribute Values: Binds text fields to a specific attribute in an object (also referred to as an attribute binding object.)

  • List: Binds the list items to all values of an attribute in a data collection.

  • Tree: Binds an entire table to a data collection and can also bind the root node of a tree to a data collection.

  • Button (boolean): Binds a checkbox to a boolean value for an attribute.

• Method Action: Binds command components, such as buttons or links, to custom methods on the data control. A method action binding object encapsulates the details about how to invoke a method and what parameters (if any) the method is expecting.

• Action: Binds command components, such as buttons or links, to built-in data control operations (such as, Commit or Rollback) or to built-in collection-level operations (such as, Create, Delete, Next, or Previous).

• Task Flow: A binding used to encapsulate a reusable portion or region of an application. You can isolate a small, specific piece of application functionality as a region that can be reused throughout the application. Task flow binding enables you to extract, parameterize, and package

There are five types of supported executable binding objects:

• Iterator: Binds to an iterator that iterates over view object collections. There is one iterator binding for each collection used on the page. All of the value bindings on the page must refer to an iterator binding in order for the component values to be populated with data at runtime.

  When you drop a collection or an attribute of a collection on the page, an iterator binding is automatically added as an executable. Iterator binding objects bind to an underlying ADF RowSetIterator object, which manages the current object and current range information. The iterator binding exposes the current object and range state to the other binding objects used by the page. The iterator range represents the current set of objects to be displayed on the page. The maximum number of objects in the current range is defined in the rangeSize attribute of the iterator. For example, if a collection in the data control contains products and the iterator range size is 25, the first 25 products in the collection are displayed on the page. If the user scrolls down, the next set of 25 is displayed, and so on. If the user scrolls up, the previous set of 25 is displayed. If your view object uses range paging, then you can configure the iterator binding to return a set of ranges at one time.

• Method Iterator: Binds to an iterator that iterates over the collections returned by custom methods in the data control.

  A method iterator binding is always related to a method action binding object. The method action binding encapsulates the details about how to invoke the method and what parameters (if any) the method is expecting. The method action binding is itself bound to the method iterator, which provides the data.

  You will see method iterator executable binding objects only if you drop a method return collection or an attribute of a method return collection from a custom method on the data control.

• Variable Iterator: Binds to an iterator that exposes all the variables in the binding container to the other bindings. While there is an iterator binding for each collection, there is only one variable iterator binding for all variables used on the page. (The variable iterator is like an iterator pointing to a collection that contains only one data object whose attributes are the binding container variables.)

  Page variables are local to the binding container and exist only while the binding container object exists. When you use a data control method (or an operation) that requires a parameter that is to be collected from the page, OEPE automatically defines a variable for the parameter in the page definition file. Attribute bindings can reference the page variables.

• Accessor Iterator: Iterates over detail collections returned by accessor methods. Accessor iterators are always related to a master iterator, which is a method iterator. The accessor iterator returns the detail objects related to the current object in the master (or method) iterator.

• Invoke Action: Binds to a method that invokes the operations or methods defined in action or method action bindings during any phase of the page lifecycle.

Adding Bindings and Executables

Bindings are added on the Page Definition page, which can be accessed by right-clicking your page in the Project Explorer, and choosing Open Page Definition. For information on tree bindings see "Working with Tree Bindings".

To add a new binding:

1. In the Outline section, click the New icon and then select Binding.

2. In the New Binding dialog, select the type of the new binding, for example, list, and enter the Id. Then click OK. The binding is added to the Outline section in the page definition editor.

3. In the editor, specify binding attributes for the new binding that you just created. For example, if you created a list binding, select the Target Attribute from the Edit List Binding dialog, as well as a List Source Attribute. You can also add or delete Field Mappings.

To add a new executable:

1. In the Outline section of the Page Definition editor, click the New icon and then select Executable.

2. In the New Executable dialog, select the type of the new executable, for example, methodIterator, and enter the Id. Then click OK. The executable is added to the Outline section in the page definition editor.

3. In the editor, specify attributes for the executable that you just created. For example, if you created a methodIterator, select a method action in the Binds field and specify a Range Size.

Working with Tree Bindings

Tree bindings are used to display a collection of data in forms requiring a nested data structure. For example, if you are displaying an organization chart, for the organization entities such as Department, Location, and Employee, a tree binding is used to display the parent and each child node using a unique type. So, if Department is the root entity type, you can bind and show attributes of Department, such as Department Name and ID, as well as show attributes for child entity types Location and Employee.

The system adds the ADF Tree component for a tree or hierarchical format, or the ADF Table component for a tabular display. For display such as organization charts or for any nested structure, the Hierarchy Viewer component is used.

To add a new tree binding:

1. In the Outline section of the Page Definition editor, click the New icon and then select Binding.

2. In the New Binding dialog, select Tree and enter the ID. Click OK. The binding is added.

To add or change binding attributes for the new binding that you just created:

1. Add and edit attributes for new bindings on the right side of the Page Definition editor. Click on the page icon for Target Attribute. In the Edit Tree Binding dialog, select the data collection to bind. Click OK.
   

2. The editor displays the entity type of the data collection in the Hierarchy section on the left.

   
   

3. Click Add (plus icon) in the Attribute Name section on the right to select the attributes of the entity data type you added to the Hierarchy section.

   
   

4. Double-click on the newAttribute entry and click on the drop-down icon to select the attribute.

   
   

5. To add a new entity type as a child of the selected node, Click Add in the Hierarchy section and select from the available type. Repeat steps 3-4 to select attributes of the type.

   
   

For more information about bindings and executables, see sections 12.6.2.1 ("Bindings Binding Objects") and 12.6.2.2 ("Executable Binding Objects") in the "Using ADF Model in a Fusion Web Application" chapter of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

ADF Page Definition Artifact Validation

OEPE provides real-time and on-demand validation of your page definition files even while the page definition editor is closed. Page definition validation warnings and errors are reported in the Markers view under the section ADF Page Definition Problems. You can set workspace preferences for ADF page definition validation from the Preferences dialog.

To specify preferences for ADF page definition validation:

1. From the main menu, select Window > Preferences to open the Preferences dialog.

2. In the Preferences dialog, select ADF > Artifact Validation to open the Artifact Validation page.

3. Specify validation options as per your preference:

   • Disable validation: Click to stop ADF page definition validation.

   • Reduce all validation errors to warnings: Selected by default. Deselect if you want validation issues to be reported as errors, thereby preventing deployment to WebLogic Server. This option is disabled if Disable validation is selected.

   • Run Validation: Click to run a workspace-wide validation based on current saved preferences. This option is disabled if Disable validation is selected.

   • On clicking OK or Apply:

     • If Disable validation is unselected or the Reduce all validation errors to warnings option was changed, a workspace-wide validation occurs.

     • If Disable validation is selected, all ADF Validation Markers are deleted.

     • Open page definition editors immediately reflect the changes.