4.7 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

Note:

A SOA application does not require using the ADF Data Control. However, the ADF Data Control is useful for showing the products on the client and for testing purposes.

4.7.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 JSF 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.

4.7.2 Understanding the Data Control Files

When you create a data control, the following XML files are generated in the service layer:

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 of the Oracle Application Development Framework Developer's Guide.

4.7.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 service 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.

4.7.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 service 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

4.7.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.

4.7.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.

4.7.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 service project. The palette displays a separate root node for each business service that you register.

Figure 4-9 Data Control Palette

4.7.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:

Constructors - Createable types are contained within the Constructors 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 Oracle Application Development Framework Developer's Guide.

4.7.3.2 Refreshing ADF Data Controls After Modifying Business Services

After you have already created the data control definition for your service 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 service project.

4.7.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.

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

In the service 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), you can refresh the data control by right clicking the session bean and choosing Create Data Control.

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

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

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 service project. Right-click the data control node and choose Delete.

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

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

In the service project, if you rename your business service or move it to a new package, you must update the reference to the service 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.