As Published In
Oracle Magazine
July/August 2013

TECHNOLOGY: Oracle ADF

  

Build Your Own

By 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:

  • Tag-library-based declarative components are used to build new JSF components out of one or many existing Oracle ADF Faces components. This component type exposes value attributes and method attributes and can be deployed in Oracle ADF libraries for reuse across application boundaries.

  • Dynamic declarative components (DDCs) are reusable layout fragments that are defined in and for a specific view layer project. DDCs are used to simplify the creation of recurring complex layouts such as custom panel tabs. This type of declarative component supports value attributes but does not support method attributes (as discussed below).

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.

  • Value attributes are comparable to JavaBeans properties and can be used to pass data into or read it from a declarative component. In the latter case, developers use expression language (EL) to reference a managed bean or an Oracle ADF binding property.

  • Method attributes are used by the declarative component to dispatch Oracle ADF Faces and JSF events to be handled by the consuming Oracle ADF application. To create a declarative component that can raise events, developers create a named method attribute at design time with a signature that defines the method return type (usually void) and the method parameter type (such as javax.faces.event.ValueChangeEvent) to notify the consuming application about a value change.

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 

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. 

o43adf-f1

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.

Getting Ready

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:

  1. Launch Oracle JDeveloper 11g Release 2. From the Oracle JDeveloper menu bar, select File -> Open and navigate to the directory containing the unpacked sample application.

  2. Open the Oramag070813/sample folder, and select the oramag070813.jws file. Click Open to load the workspace.

  3. Select View -> Database -> Database Navigator, and expand the oramag070813 node to display the hrconn node.

  4. Right-click hrconn, and select Properties from the menu. Edit the database connection information to work with your setup. Test the changes, and click OK.

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.

  1. Switch to the Oracle JDeveloper Application Navigator by clicking the Application Navigator tab in the integrated development environment (IDE).

  2. Choose File -> New from the Oracle JDeveloper menu to create a new application. In the New Gallery, select General -> Applications.

  3. Choose the Custom Application entry, and click OK.

  4. Click Browse next to the Directory field to locate the Oramag070813 folder in the directory in which you unzipped the sample files. Then click Select.

  5. Set the Application Name field value to OramagCom.

  6. Set the Application Package Prefix field value to oramag.sample.julaug .thirteen, and click Next to navigate to the second wizard dialog box.

  7. Set the Project Name field value to OramagPanelCollection.

  8. Hold down the Ctrl key while selecting ADF Faces and ADF Page Flow from the Available list of project features, and click the selection button (the right-arrow icon).

  9. Click Next, and change the Default Package field value to oramag.sample.julaug.thirteen.comp.

  10. Click Finish.

  11. In the Application Navigator, right-click the OramagPanelCollection node and choose Project Properties from the menu that appears.

  12. Select the Libraries and Classpath node, and click Add Library.

  13. In the Add Library dialog box, select ADF Model Generic Runtime and click OK twice.

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.

  1. Right-click the OramagPanelCollection node, and choose New from the menu.

  2. Under Categories, select the Web Tier -> JSF/Facelets node and ADF Declarative Component. Click OK.

  3. In the Create ADF Declarative Component dialog box, set the Declarative Component Name field value to HtmlExportPanelCollection.

  4. Keep the default values for File Name, Directory, and Declarative Component Package, and click Add Tag Library.

  5. In the Create Declarative Component Tag Library dialog box, define the value for the Tag Library Name field as HtmlExportPanelCollection.

  6. Set the Tag Library URI field value to /htmlexport/collection. This field defines a namespace for the custom component so it can be uniquely addressed on a JSF page.

  7. Set the Tag Library Prefix field value to oramag. In the way Oracle ADF Faces components are prefixed with af:, this custom component will be prefixed with oramag: when referenced on an application page.

  8. Click OK.

  9. Leave the Use Custom Component Class checkbox—which enables you to render a Java class you can use to override JSF implementation details such as component encoding and decoding—unchecked.

  10. Ensure that the Document Type selection is set to Facelets. This setting is required because the precreated Oracle ADF sample application used for testing the component also uses Facelets.

  11. With the Facet Definition tab selected, click the green plus (+) icon.

  12. Define the Facet Name field value as tableArea, and enter Drop target for ADF Faces table components for Description.

  13. Select the Attributes tab, and click the green plus (+) icon to create a component attribute with the following values:

    Name exportTitle
    Type java.lang.String
  14. Again, click the green plus icon (+) to create a second attribute, with the following values:

    Name exportRows
    Type java.lang.Integer
  15. Click OK to create the component definition.

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.

  1. Choose View -> Component Palette from the Oracle JDeveloper menu to select the Component Palette.

  2. In the Component Palette, expand the Layout accordion, select the Panel Collection component (the sixth component in the Layout accordion), and drag it into the visual page editor that shows the HtmlExportPanelCollection.jsf file. 

    Note: The Panel Collection component in Oracle ADF Faces is used to decorate the Oracle ADF Faces table, tree, and treeTable components with menus for showing, hiding, and sorting attributes. This hands-on guide creates a declarative component that adds HTML export functionality to this component.

  3. Stay in the Layout accordion in the Component Palette. Find and select the Facet Definition component in the Core Structure subsection, and drag it into the center of the Panel Collection component.

  4. In the Insert Facet Definition dialog box that appears, select tableArea for Facet Name and click OK

    Note: The Facet Definition tag adds metadata that defines where in the component application developers can declaratively add UI components later.

  5. Save your work.

  6. Next, choose View-> Structure from the Oracle JDeveloper menu to open the Structure window.

  7. In the Structure window, expand the af:panelCollection – dc_pc1 entry and right-click the f:facet – toolbar entry.

  8. Select Insert Inside f:facet – toolbar -> Toolbar to add a new toolbar component.

  9. Still in the Structure window, right-click af:toolbar and choose Insert Inside af:toolbar -> Toolbar Button.

  10. Select View -> Property Inspector from the Oracle JDeveloper menu to open Property Inspector.

  11. Ensure that the af:commandToolbarButton component is selected in the Structure window, and change the Text property value to export to HTML, using Property Inspector.

  12. Switch back to the Component Palette by clicking the Component Palette tab, and expand the Operations accordion.

  13. Select the File Download Action Listener component in the Listeners subhead area. While pressing the left mouse button, drag the File Download Action Listener component into the toolbar button component in the visual editor of the Structure window.

  14. Ensure that the af:fileDownloadActionListener entry is selected in the Structure window, and open Property Inspector.

  15. Set the Content Type property to text/html and the File Name property to exportedData.html.

  16. Click the down-arrow icon next to the Method property, and choose Edit from the menu to create a new managed bean method to handle the data export.

  17. In the Edit Property: Method dialog box, click New (next to the Managed Bean field).

  18. Edit the dialog box fields as follows:

    Bean Name CustomPanelCollectionBean
    Class Name CustomPanelCollectionBean
    Package oramag.sample.julaug.thirteen.comp
    Extends java.lang.Object
    Scope backingBean
    Registration Configuration File

  19. Click OK.

  20. Back in the Edit Property: Method dialog box, click New (next to the Method field).

  21. Set the Method Name field value as handleFileDownload, and click OK twice.

  22. In the Application Navigator, expand the OramagPanelCollection -> Application Sources -> oramag.sample.julaug -> thirteen -> comp package, and double-click the CustomPanelCollectionBean.java file.

  23. Return to the operating system. Use any file browser to navigate to the directory containing the unpacked sample application, and open the template folder.

  24. Open the contained CustomPanelCollectionBean.txt file in a text editor, and use Ctrl-A and Ctrl-C to copy its full contents to the clipboard.

  25. Return to Oracle JDeveloper. Place the cursor inside the Java code editor, which shows the CustomPanelCollectionBean.java file, and replace its contents with the clipboard contents by using Ctrl-A and Ctrl-V.

  26. Switch to the visual page editor, by clicking the HtmlExportPanelCollection .jsf tab header.

  27. In the Oracle JDeveloper Structure window, select the af:componentDef -> af:panelCollection – dc_pc1 component node, and open Property Inspector.

  28. Navigate to the Binding property in the Advanced section, click the down-arrow icon, and choose Edit from the menu.

  29. In the Edit Property: Binding dialog box, select CustomPanelCollectionBean for Managed Bean and customPanelCollection for Property.

  30. Click OK.

  31. Save your work, and close the code editor.

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.

  1. Right-click the OramagPanelCollection node in the Application Navigator, and choose Project Properties from the menu.

  2. Select the Deployment node, and click New.

  3. In the dialog box that appears, ensure that Profile Type is ADF Library JAR File and set Deployment Profile Name to oramag070813. Then click OK three times in sequence to confirm these selections.

  4. Save your work again. Then right-click the OramagPanelCollection node. Choose Deploy -> oramag070813 from the menu, and click Next followed by Finish.

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. 

 Next Steps

    

DOWNLOAD
 Oracle JDeveloper 11g
 the sample application for this article

READ more about
 Oracle ADF
 dynamic declarative components
 Oracle ADF Faces export collection listener  

READ more Nimphius
 Oracle ADF Code Corner
 Oracle Technology Network Oracle JDeveloper forum
 Oracle ADF Insider

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.

  1. Choose View -> Resource Palette from the Oracle JDeveloper menu to open the Resource Palette window.

  2. Click the folder icon at the top, and choose New Connection -> File System.

  3. In the dialog box that appears, define Connection Name as htmlExportPanelCollection.

  4. Click Browse to navigate to and select the Oramag070813\ OramagComp\OramagPanelCollection\deploy folder, and click Select

    Note: Make sure you select the deploy folder and not the JAR file within.

  5. Click OK

     

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.