Libraries You Can Depend On
By Steve Muench
Modularize your applications by using Oracle Application Development Framework libraries.
Task flows in Oracle Application Development Framework (Oracle ADF) help you organize an application around the end-user tasks it supports. But as an application grows, the number of task flows and related business components inevitably increases. The more application artifacts you pile into a single workspace, the harder it is to understand the application’s logical organization and the slower navigation becomes. In addition, frequently updated “catalog” files such as DataBindings.cpx can become problem areas for team development, requiring frequent merge-conflict resolution as different developers work on different task flows. This column shows how Oracle ADF libraries can help address these problems by enabling a more modular application architecture.
An Oracle ADF library is a standard Java archive (JAR) file that contains Oracle ADF components along with information that enables Oracle JDeveloper to simplify browsing and reusing them. This information also enables Oracle JDeveloper to help you manage library dependencies. By using Oracle ADF libraries, you can assemble your application from task flows and business components that are developed in separate workspaces.
To begin, download the starter workspace at otn.oracle.com/oramag/oracle/10-may/o30frame.zip and ensure that you’re using the studio edition of the Oracle JDeveloper 220.127.116.11 production release, available as a free download on Oracle Technology Network (OTN) at otn.oracle.com/software/products/jdev. Start by extracting the contents of the o30frame.zip file into the root directory of the C: drive on a machine running Microsoft Windows. If you choose a different location or are running on a different platform, you’ll need to adjust the path references accordingly in the rest of this column. Now open the C:/FrameworksMayJun2010/MainApp/MainApp.jws workspace in Oracle JDeveloper. Before proceeding, adjust the properties of the connection named scott in the Application Resources zone of the Application Navigator until you can successfully test a connection to a SCOTT schema. If you need to create the tables in SCOTT, use the provided CreateDeptEmpTables.sql script in the MainApp workspace’s Model project.
Sample Application Overview
The sample application enables users to maintain department and employee data. It is modularized into four separate workspaces. The Entities workspace contains the core entity object layer used by all the task flows. The EmpFlow workspace contains the task flows for managing employees and depends on the core entities library. The MainApp workspace provides a simple “main menu” page that enables users to launch the empflow and deptflow task flows, which it references from Oracle ADF libraries. The DeptFlow workspace contains a partially completed task flow for managing departments. The Libs directory contains all the Oracle ADF libraries for the application as a whole.
To get a quick overview of what the application does, right-click the ViewController project and choose Run . When your browser opens, you’ll see a simple page with two links. Click the Manage Employees link to display a list of employees. Select an employee, click Edit , change the employee’s salary, and click Save . Note that the changed value is reflected in the employee list. Click Done to return to the initial page. The Manage Departments link isn’t functional. To bring it to life, you’ll complete the DeptFlow workspace, using techniques that mirror those already in use by the EmpFlow workspace.
In the Application Navigator for the MainApp workspace, expand the ViewController project’s Application Sources and note that it contains a DataBindings.cpx file in the oramag.mainapp.view package. Open the Web Content folder, and note that it contains a single Home.jspx page. This “main menu” page contains links that call task flows to enable end users to perform the tasks available to them. Expand the Page Flows folder, and double-click the adfc-config node.
In the task flow diagram, you can see that the Home view activity contains a control flow line for calling the empflow task flow. However, the empflow task flow is not part of this project. If you double-click the empflow task flow call activity in the diagram, the called task flow will open in the editor. If you try to move any of the activity nodes to a new location on the diagram, you won’t be able to, because this diagram is read-only. To understand why, position your cursor over the empflow.xml tab title area to study the tooltip that appears (after a short delay). It shows the name of the file displayed in this editor. (If the tooltip disappears before you can finish reading it, move your cursor off the tab title and then hover over it again to get a few more seconds to study it.) You can see that the file path contains EmpFlow.jar . This is the name of the Oracle ADF library archive file that contains the task flow. That library is produced by the sample application’s EmpFlow workspace. The MainApp workspace’s ViewController project reuses the empflow task flow from that library.
Next, open the EmpFlow workspace by choosing File -> Open from the Oracle JDeveloper main menu and selecting the C:/FrameworksMayJun2010/EmpFlow/EmpFlow.jws file. Note that the EmpFlow workspace’s contents replace the MainApp workspace’s contents in the Application Navigator. (The control at the top of the Application Navigator displays the name of the current workspace and enables you to select any other open workspace to make it current when necessary.)
In the EmpFlow workspace’s ViewController project, expand the Web Content folder and the Page Flows folder it contains. Note that the empflow task flow appears there. Also expand the Application Sources folder and the package nodes it contains until you see this workspace’s DataBindings.cpx file. Note that it is in the oramag.empflow.view package. When you create supplementary workspaces to produce task flows in a library, each workspace must use a unique default package name so that the DataBindings.cpx file in that workspace’s ViewController project does not conflict with any other DataBindings.cpx file used in the application. The EmpFlow workspace’s ViewController project uses the oramag.empflow.view default package name to avoid clashing with the DataBindings.cpx file in the MainApp workspace’s ViewController project.
To see the default package name setting, double-click the ViewController project in the EmpFlow workspace to open the Project Properties dialog box. On the Project Source Paths page, note the Default Package field at the bottom. When you create a new workspace, the first step is to ensure that you have configured a unique default package name for both your Model project and your ViewController project. This way, when you begin building components, the files will be created in the correct, unique location.
Click Cancel to dismiss the dialog box. In the sections that follow, you’ll complete the deptflow task flow, deploy it in an Oracle ADF library, and then reuse the new task flow in the MainApp application.
Using a Library from the Resource Palette
The deptflow task flow lives in the DeptFlow workspace. Open this workspace in Oracle JDeveloper by choosing File -> Open from the main menu and selecting the C:/FrameworksMayJun2010/DeptFlow/DeptFlow.jws file. The Model project already contains a DeptModule application module, so the first order of business is to create a view object to work with the list of departments. The entity objects used by all of the application’s task flows were developed in a separate Entities workspace and deployed to an Entities.jar Oracle ADF library. You’ll start by adding the appropriate Dept entity object from this library to the current project to build a view object on top of it.
Choose View -> Resource Palette to display Oracle JDeveloper’s palette of reusable resources, which helps make quick work of this task. To reference resources, such as Oracle ADF libraries, on the file system, you add one or more entries called file system connections to the Resource Palette. A file system connection provides a nickname for a directory on disk where reusable resources reside. Click the folder-with-a-plus-sign icon to the left of the Resource Palette’s search box, and choose New Connection -> File System from the menu. When the Create File System Connection dialog box appears, enter Libraries for Connection Name and click Browse to choose a directory path. Find the C:/FrameworksMayJun2010/Libs directory, click it, and then click Select . Click Test Connect to ensure that the directory path is correct. If it is, click OK.
A new File System node appears in the Resource Palette. Expand it to reveal the new Libraries connection, and expand that to see the Entities.jar Oracle ADF library. Expand this library node and the Business Components folder it contains, and then select the Dept entity object in the oramag.model.entities package. Click the Model project in the Application Navigator to ensure that it is the active project, and then right-click the Dept entity object in the Resource Palette and choose Add to Project . When the Confirm Add ADF Library dialog box appears, click Add Library . This action performs two configuration tasks under the covers. First, it updates the current ( Model ) project to depend on this new Oracle ADF library by adding the JAR file to the ADF Library entry in the project’s library list. Second, it imports the package of Oracle ADF business components containing the Dept object, so that these components are available to reference in the design-time editors.
Next, create a view object to retrieve the department rows. In the Application Navigator, right-click the oramag.deptflow.model package node in the Model project and choose New View Object . When the Create View Object dialog box appears, complete the following steps:
Double-click the DeptModule application module to open it in the editor. On the Data Model page, select DeptView in the Available View Objects list, enter Departments in the New View Instance field (below the Available View Objects list), and click > to add a new view instance with this name to the data model.
Creating Libraries and Configuring Dependencies
Each project that will be part of a set of reusable components should produce its own Oracle ADF library JAR, so now you’ll create a new Oracle ADF library deployment profile for the DeptFlow workspace’s Model project’s components. In a subsequent step, you’ll also create an Oracle ADF library deployment profile for the ViewController project.
Start by double-clicking the Model project to open the project properties editor. On the Deployment page, click New to create a new deployment profile. When the Create Deployment Profile dialog box appears, set Archive Type to ADF Library JAR File , enter DeptFlowModel in the Name field, and click OK . In the Edit ADF Library JAR Deployment Profile Properties dialog box that appears, on the JAR Options page, change the default path and filename to C:\FrameworksMayJun2010\Libs\DeptFlowModel.jar . Click OK once to dismiss this dialog box and OK again to close the Project Properties dialog box.
To create the new library archive, right-click the Model project and choose Deploy -> DeptFlowModel . When the Deploy DeptFlowModel dialog box appears, click Finish to start the process. Click the Deployment tab in the Log window to see the results of the deployment operation. You should see something like “Wrote Archive Module to C:\FrameworksMayJun2010\Libs\DeptFlowModel.jar” in the log. To refresh the list of libraries in the Resource Palette, right-click the Libraries file system connection node and choose Refresh . Note that the new DeptFlowModel.jar now appears in the list. The steps you just performed to create a new Oracle ADF library JAR deployment for the model components are the same as the steps completed ahead of time to create the reusable Entities.jar Oracle ADF library you used earlier.
By default, Oracle JDeveloper configures your ViewController project to depend on the compiled output of the Model project, so that pages can reference your model objects through the Oracle ADF model data-binding layer. When you produce an Oracle ADF library JAR for your model components, you must first add the model components library JAR to the ViewController project’s library list and then update the project’s dependency settings to use the new JAR instead of the compiled output. The first step is to click the ViewController project in the Application Navigator to make it the current project. Then, right-click the DeptFlowModel.jar node in the Resource Palette and choose Add to Project . When the confirmation dialog box appears, click Add Library to complete this task.
To update the project’s dependency settings, double-click the ViewController project to open the Project Properties dialog box and then open the Dependencies page. Select the Model.jpr entry in the Dependent Projects and Archives list, and click the pencil icon to edit it. In the Edit Dependencies dialog box, note that the checkbox next to Build Output is checked. Click the checkbox next to the DeptFlowModel deployment profile. When you do this, an Adjusting Dependencies alert appears to let you know that the two checkboxes are mutually exclusive; click OK . Now the DeptFlowModel deployment profile is checked as a dependency, and the original checkbox is cleared. Click OK to close the Dependencies page.
While you’re here, you can also create the Oracle ADF library deployment profile for the ViewController project. It will contain the task flows you will finish building shortly. On the Deployment page, click New . Select the ADF Library JAR File archive type, provide the name DeptFlow for the profile, and click OK . On the Edit ADF Library JAR Deployment Profile Options dialog box’s JAR Options page, change the default path and filename to C:\FrameworksMayJun2010\Libs\DeptFlow.jar , click OK , and click OK again to close the Project Properties dialog box.
Next, you’ll finish building the pages in the deptflow task flow and then deploy the DeptFlow Oracle ADF library you just created. Expand the ViewController project and the Web Content folder inside it. Double-click the ListDepartments.jspx page name to open the page in the editor. Expand the Data Controls section of the Application Navigator, and expand DeptModuleDataControl . If you don’t see the Departments data collection, click the refresh icon in the Data Controls section title bar. Drag the Departments data collection, and drop it onto the page below the two existing buttons. In the Create menu, choose Table -> ADF Read-only Table . When the Edit Table Columns dialog box appears, check the Row Selection and Sorting checkboxes at the top and click OK . Now double-click EditDepartments.jspx to open it in the editor. Drag the Departments data collection, and drop it onto the page below the two existing buttons. In the Create menu, choose Form -> ADF Form . When the Edit Form Fields dialog box appears, accept the defaults and click OK . Finally, deploy the new DeptFlow Oracle ADF library containing the task flow. Right-click the ViewController project, and choose Deploy -> DeptFlow . When the Deploy DeptFlow dialog box appears, click Finish . To verify that everything has gone as expected, select the Deployment tab of the Log window and scroll to the bottom. You should see a confirmation message like “ Wrote Archive Module to C:\FrameworksMayJun2010\Libs\DeptFlow.jar. ” Right-click the Libraries file system connection in the Resource Palette and choose Refresh to update the list of available libraries.
Using a Task Flow from a Library
With the deptflow task flow library now in place, the last step is to integrate it into the “main menu” page. Start by switching the current workspace back to MainApp, using the list at the top of the Application Navigator. Double-click the Web Content folder’s adfc-config node in the Application Navigator to open it in the editor. Expand the DeptFlow.jar node inside the Libraries file system connection node in the Resource Palette and the ADF Task Flows folder it contains. Drag the deptflow task flow from the Resource Palette, and drop it onto the task flow diagram. Confirm the addition of the Oracle ADF library by clicking Add Library in the alert that appears. Choose View -> Component Palette , and select the Control Flow Case tool in the palette. Click the task flow diagram’s Home activity, and then click the deptflow task flow call activity to connect the two activities with a control flow case. Enter the name ManageDepartments on the line. Double-click the Home activity to open the page in the visual editor. Select the Manage Departments commandLink component on the page, and in the Property Inspector, set its Action property value to ManageDepartments to correspond to the new control flow case you created.
When you use the Resource Palette to add a component from an Oracle ADF library, Oracle JDeveloper automatically adjusts your current project’s library list to include the library JAR file and any JAR files that library depends on. To confirm this, double-click the ViewController project and select the Libraries and Classpath page of the Project Properties dialog box. Scroll to the bottom of the Classpath Entries list, and note that two new libraries have been added to the list. The Oracle ADF library contains the path(s) to the Oracle ADF library JAR file(s) on which the project is directly dependent. The Oracle ADF Library Dependencies library contains the path(s) to the library JAR files that are required by the direct dependencies. If you select the ADF Library entry in the list and click Edit , you will be able to see that this project depends directly on the EmpFlow.jar and DeptFlow.jar libraries that contain the task flows being called by the main menu page.
Click Cancel , select ADF Library Dependencies , and click View . You can see that this application indirectly depends on the DeptFlowModel.jar and EmpFlowModel.jar libraries that contain the task flow-specific model components as well as on the core Entities.jar file that contains the common entity objects used by all task flows. Click Cancel and Cancel again to dismiss the dialog boxes.
Right-click the ViewController project, and choose Run . When the application launches in your browser, you can see that it now enables users to manage both department and employee data.
In this column, we explored using Oracle ADF libraries to reuse common Oracle ADF business components as well as task flow-specific model components and the task flows themselves. You are ready to put these concepts to work to modularize your applications and avoid unnecessary developer contention on frequently updated files such as DataBindings.cpx . For more information on creating and using Oracle ADF libraries, see Chapter 32, “ Reusing Application Components ,” in Fusion Developer’s Guide for Oracle ADF 11g .
Steve Muench is a consulting product manager for Oracle JDeveloper. He has developed, supported, and evangelized Oracle tools and XML technologies since 1990 and blogs at bit.ly/ddyMc7.