TECHNOLOGY: Oracle ADF
Build Your OwnBy Frank Nimphius
Build and deploy Oracle ADF declarative components, and gain the benefits of reuse.
Declarative components in Oracle Application Development Framework (Oracle ADF) enable application developers to build custom JavaServer Faces (JSF) components from existing Oracle ADF Faces components (Oracle ADF Faces is a feature of Oracle ADF) and deploy them as reusable Oracle ADF libraries. Developers who want extra functionality with existing Oracle ADF Faces components or who are building a composite component such as an address field can use the declarative component feature to ensure layout consistency as they reuse components throughout Oracle ADF applications.
This article provides an overview of declarative components in Oracle ADF and provides a hands-on guide that walks through the declarative build process.
About Oracle ADF Declarative Components
Oracle ADF declarative components are standard JSF components that expose their state and behavior through attributes. The attributes exposed by a component define a public API that developers use to enable bidirectional communication with the declarative component. Note that declarative components don’t have their own Oracle ADF PageDef files and therefore cannot have their own bindings defined.
Oracle ADF provides two types of declarative components:
Declarative Component Attributes
Declarative components provide two types of attributes that collectively define their public application interface. Developers can create and edit these attributes, using Oracle JDeveloper’s Property Inspector feature.
Declarative Component Facets
In JSF, facets are named areas within a component that application developers can use to add JSF child components such as toolbars and context menus. In the same way, declarative components can also include facet definitions to enable application developers to add JSF child components. The facet location within a declarative component is defined by another Oracle ADF Faces component called the facet reference.
JSPX Versus Facelets
The view declaration language (VDL) in JSF defines the technology that acts as a container for JSF component markup tags. Through JSF Release 1.2, JavaServer Pages (JSP) was the default VDL for JSF applications, and it is still supported in JSF 2.x. However, Facelets is a new VDL that has become the new default and recommended container in JSF 2.x, because of its better alignment with the JSF request lifecycle. Because JSPX documents are different from Facelets, developers must build Oracle ADF declarative components for a specific VDL, so it’s important to know the target VDL for which a component needs to be built. In Oracle JDeveloper 11g Release 1, the VDL is always JSPX, but in Oracle JDeveloper 11g Release 2 and later releases, it can be JSPX or Facelets.
Geometry management is Oracle ADF functionality that automatically sizes Oracle ADF Faces components according to the available view size. Geometry management works in cases when the surrounding JSF layout component is able to stretch its child components. Although dynamic declarative components do participate in Oracle ADF geometry management, declarative components don’t. To size declarative components, developers need to expose and implement custom width and height attributes.
Using Separate Workspaces
Because declarative components are reusable artifacts in Oracle ADF and not built specifically for a single application, it is best to develop them in their own Oracle JDeveloper workspace. At the very least, declarative components should be developed in a separate project. This approach simplifies deployment and also helps maintain reusable code that is independent from application-specific code.
Hands-on Overview: A Simple Data Export Application
Oracle ADF Faces provides a behavior tag—af:exportCollectionActionListener—that declaratively enables a command button or a command link for exporting data from a collection component such as a table or a tree. However, the export functionality is limited to data rows currently displayed in the table, and it outputs only to the Microsoft Excel HTML document format.
To support other data export formats such as PDF and regular HTML or to print not-yet-queried data to the client, developers can build a declarative component. The instructions in this article show how to build, deploy, and test a declarative component that exports Oracle ADF table data to an HTML file download, as shown in Figure 1.
Figure 1: Custom Oracle ADF component for exporting data to HTML
The declarative component described in the following example performs a simple HTML file export of data, making it easier to avoid having to use third-party packages such as Apache POI for Excel. Some parts of the declarative component and the Oracle ADF sample application have been prebuilt for you, so you can focus on building declarative components. Because the application is partially built, it is especially important to follow the hands-on instructions closely.
Before following the steps in this article, download and install the Studio edition of Oracle JDeveloper 11g Release 2. It is available as a free download on Oracle Technology Network at bit.ly/KDqHjz. You also need access to an Oracle Database instance with an unlocked HR schema. Next download the o43adf-1940728.zip sample application and unzip the file.
This sample application includes two Oracle ADF workspaces. The first workspace represents the Oracle ADF application that consumes the declarative component for testing. The second workspace holds the declarative component itself.
The workspace for the test application has been prebuilt. The only change needed is to change the database connection used by the Model project of the Oracle ADF Business Components feature of Oracle ADF to point to your HR database schema. To do so, follow the instructions below:
Next, start the Oracle WebLogic Server instance integrated with Oracle JDeveloper. To start Oracle WebLogic Server, select Run -> Start Server Instance.
If this is the first time you’ve run the integrated Oracle WebLogic Server, a Create Default Domain dialog box will open. Create a password for the default Oracle WebLogic Server domain, and select an address from those listed for Listen Address. For example, choose localhost rather than leaving the address empty.
Click OK to save the changes and to create and configure the default domain for Oracle ADF.
Creating an Oracle JDeveloper Workspace and Project
The next step is to create a new Oracle JDeveloper workspace for the declarative component.
At this point, you have created the Oracle JDeveloper workspace and project in which the Oracle ADF declarative component will be built. You have also configured the project to access the Oracle ADF binding runtime classes that are needed to export table data.
Declarative Component: Definition
The next step is to define the declarative component.
At this point, your new workspace contains an empty declarative component, configured with a single facet to hold an Oracle ADF bound table as a child component. It contains two attributes that developers will use to define a title for the exported HTML data and the number of rows to export. The declarative component should appear in the visual editor in Oracle JDeveloper.
Note: The runtime logic you add later to the declarative component will throw an exception if the child component is not an Oracle ADF bound table.
Declarative Component: Implementation
The next step is to add the declarative component implementation, which is the code for exporting child component data to HTML.
At this point, you have created a declarative component that expects an Oracle ADF bound table as a child component and uses a managed bean in the backing bean scope to access the table binding to export row data to HTML. The backing bean scope of the managed bean ensures that multiple instances of the declarative component can be added to a single Oracle ADF Faces page.
Deploying the Component into an Oracle ADF Library
To reuse the declarative component in an Oracle ADF project, it must first be deployed into an Oracle ADF library.
At this point, you have created an Oracle ADF library file (oramag070813.jar) and saved it in the Oramag070813\OramagComp\OramagPanelCollection\deploy directory in the file system.
Using the Resource Palette
The next step is to create an Oracle JDeveloper Resource Palette reference to this library, to allow reuse in Oracle ADF applications.
Testing the Component
To test the declarative component, switch workspaces in Oracle JDeveloper to the provided sample application and import the Oracle ADF library from the Resource Palette.