3.10 Exposing Services with ADF Data Controls

The easiest way to bind services to a user interface is by using the ADF Data Control.

This section includes information on the following:

How to Create ADF Data Controls
Understanding the Data Control Files
Understanding the Data Control Palette

3.10.1 How to Create ADF Data Controls

To create an ADF data control from an EJB session bean, right-click a session bean in the Navigator and choose Create Data Control or drag a session bean onto the Data Control Palette.

Note:

J2EE developers who do not want to rely on Oracle-specific libraries may use managed beans instead of the ADF data control. This is more complex and beyond the scope of this book.

When you create a data control from an EJB 3.0 session bean, several XML files are generated and displayed in the Navigator. The generated files and the Data Control Palette are covered in the following sections.

3.10.2 Understanding the Data Control Files

When you create a data control, the following XML files are generated in the model

DataControls.dcx - data control definition file
<session_bean>.xml - structure definition file
ReadOnlyCollection.xml - design-time XML file
ReadOnlySingleValue.xml - design-time XML file
UpdateableCollection.xml - design-time XML file
UpdateableSingleValue.xml - design-time XML file
<entity_name>.xml - entity definition file, one per entity

How these files are related and used are covered in greater detail in Appendix A, "Reference ADF XML Files".

3.10.2.1 About the DataControls.dcx File

The DataControls.dcx file is created when you register data controls on the business services. The .dcx file identifies the Oracle ADF model layer adapter classes that facilitate the interaction between the client and the available business service. In the case of EJB, web services, and bean-based data controls, you can edit this file in the Property Inspector to add or remove parameters and to alter data control settings. For example, you can use the .dcx file to set global properties for various items, such as whether to turn on/off sorting.

3.10.2.2 About the Structure Definition Files

When you register a session bean as an Oracle ADF data control, an XML definition file is created in the Model project for every session bean. This file is commonly referred to as the structure definition file. The structure definition file has the same name as the session bean, but has a .xml extension.

A structure definition is made up of three types of objects:

Attributes
Accessors
Operations

3.10.2.3 About the Entity XML Files

When you create a data control, an XML file is generated for each entity (TopLink, EJB, or Java bean). These files are used for both ADF design-time and runtime. These files describe the structure of the class as well as UI hints, validators and labels for each attribute.

3.10.2.4 About the Design-time XML Files

Four files are generated solely for the design-time:

ReadOnlyCollection.xml
ReadOnlySingleValue.xml
UpdateableCollection.xml
UpdateableSingleValue.xml

These files are referenced by MethodAccessor definitions as the CollectionBeanClass which describes the available operations. Typically you do not edit this file by hand, but you could customize items on the Data Control Palette.

3.10.3 Understanding the Data Control Palette

Client developers use the Data Control Palette to create databound HTML elements (for JSP pages), databound Faces elements (for JSF JSP pages), and databound Swing UI components (for ADF Swing panels). The Data Control Palette comprises two selection lists:

Hierarchical display of available business objects, methods, and data control operations
Dropdown list of appropriate visual elements that you can select for a given business object and drop into your open client document

Additionally, web application developers use the Data Control Palette to select methods provided by the business services that can be dropped onto the data pages and data actions of a page flow.

The Palette is a direct representation of the XML files examined in the previous sections, so by editing the files, you can change the elements contained in the Palette.

The hierarchical structure of the business services displayed in the Data Control Palette is determined by which business services you have registered with the data controls in your model project. The palette displays a separate root node for each business service that you register.

Figure 3-15 Data Control Palette

3.10.3.1 Overview of the Data Control Business Objects

The root node of the Data Control Palette represents the data control registered for the business service. Proceeding down the hierarchy from the root data control node, the palette represents bean-based business services as constructors, attributes, accessors or operations:

Constructurors - Createable types are contained within the Construtors node. These types call the default constructor for the object.
Attributes - such as bean properties, which can define simple scalar value objects, structured objects (beans), or collections.
Accessors - get() and set() methods.
Operations - such as bean methods, which may or may not return a value or take method parameters. For Web Services, the Data Control Palette displays only operations.

For more information on using the Data Control Palette, see Chapter 5, "Displaying Data in a User Interface". For more information on the Data Control files and how they related to each other, see Appendix A, "Reference ADF XML Files".

3.10.3.2 Refreshing ADF Data Controls After Modifying Business Services

After you have already created the data control definition for your Model project, you may decide to update the data control after modifying your business services. Refreshing the data control definition makes the latest business service changes available to the ADF application.The action you take to refresh the data control definition depends upon the type of change to the model project.

3.10.3.2.1 Viewing modified data controls in the Data Control Palette:

If the palette is not yet displayed, select the View menu and choose Data Control Palette. If the palette is already displayed, right-click in the palette and choose Refresh.

3.10.3.2.2 Refreshing a data control definition for business services you have modified

In the model project, define the new properties of the bean or other business service you want to create. Compile the .java file to regenerate the business service's metadata in its corresponding .xml file. If the modified business service is bean-based (such as an EJB session bean), right-click the bean's .xml file and choose Refresh.

Note: In the case of ADF Business Components, the data control definition is automatically updated whenever you make changes to your ADF BC project files.

3.10.3.2.3 Removing a data control definition for business services that have been removed:

To To remove a data control definition, in the view project, select the DataBindings.dcx file and in the Structure window, select the data control node that represents the business service that no longer appears in your Model project. Right-click the data control node and choose Delete.

JDeveloper updates the data control definition file (DataBindings.dcx) in the Model project. The DataBindings.dcx file identifies the Oracle ADF model layer adapter classes that facilitate the interaction between the client and the available business services.

3.10.3.2.4 Updating a data control after renaming or moving a business services

In the model project, if you rename your business service or move it to a new package, you must update the reference to the model project in the client's data control definition.

In the view project, select the DataBindings.dcx file. In the Structure window, select the data control node that represents the moved business service. In the Property Inspector, edit the Package attribute to supply the new package name.