As Published In
Oracle Magazine
May/June 2008

DEVELOPER: Frameworks

Enlightened Development

By Steve Muench Oracle ACE

Simplifying common navigation and coding tasks

In this column, we exercise several new features in the upcoming Oracle JDeveloper/Oracle Application Development Framework (Oracle ADF) 11g release that improve developer productivity. We'll see firsthand how they simplify working with your Oracle ADF application's components and pages.

To continue, download the starter workspace and ensure that you're using the Oracle JDeveloper Technology Preview 3 release, available as a free download on Oracle Technology Network. Start by extracting the contents of the file and opening the FrameworksMayJun2008.jws workspace in Oracle JDeveloper. Note that the Model project in the starter workspace defines a familiar Emp entity object, an EmpView view object, and an HRModule application module. The ViewController project defines SearchEmployees.jspx and EditEmployee.jspx pages that allow searching for employees and editing a given employee's data, respectively. Before proceeding, adjust the properties of the scott connection 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, use the provided CreateDeptEmpTables.sql.

As the last step in this column, we fix a bug in the sample application, so we won't run it until the end.

Exploring Component Relationships

We've seen enough examples in previous columns to know that Oracle ADF empowers us to build sophisticated, cleanly layered business solutions that rely on a metadata-driven implementation of all the typical application functionality. However, understanding how all of the different components are related isn't always straightforward. Oracle JDeveloper 11g includes new design time features to simplify the task of understanding and navigating the relationships between components. To observe these features in action, let's start with a Web page and see how easily we can follow the links from a particular component on the user interface back through the Oracle ADF Model layer to the view object that queries the data and the entity object that handles its transactional behavior and validation. We'll start with the EditEmployees.jspx page and navigate to the related entity object to see its validation rules.

With the sample workspace, FrameworksMayJun2008.jws, open in the Application Navigator, first select the ViewController project. To quickly navigate to the EditEmployee.jspx Web page, select Navigate -> Go to File from the main menu. When the Go to File dialog box appears, type the letter e to display a subset list of files including only those whose names start with that letter. Continue by typing the letter d , and note that the EditEmployee.jspx page and its page definition are now the only entries in the list. Select EditEmployee.jspx from the list, and press the Enter key; the page opens in the visual editor. (In a large application, this Go to File feature will save you time, so note its key accelerator: Ctrl-Alt-[-].)

With the Design tab selected, right-click the Sal.inputValue text field UI component in the visual editor and select Goto Binding . This changes the active tab of the visual editor to the new Bindings tab, which shows a visual representation of the page definition for the current page, with the Sal binding related to the text field you clicked selected. Connector lines indicate that the Sal attribute comes from the EmployeesIterator binding, which binds to the Employees data collection in the HRModuleDataControl data control. (In the Technology Preview 3 release, you may have to select a different binding such as Hiredate from the list and then select the Sal binding again so the connector lines show correctly.) Armed with this information, expand the Data Controls section of the Application Navigator and the HRModuleDataControl node inside it. Right-click the Employees data collection and select Edit Definition to open the overview editor for the view object related to that data collection. Click the Entity Objects tab of the editor, and select the Emp entity usage from the Selected list. Note the Definition hyperlink that appears below the list. This is the name of the entity object that participates in this view object. Click that oramag.model.Emp link to open the overview editor for the Emp entity object. Click the Attributes tab of the editor, and click the Sal attribute in the table. Expand the Validation Rules section to see Sal Range(1,5000). So in a few clicks, we have navigated from the user interface component to its binding, to the related view object and entity object.

Finding Usages

Next, let's navigate in the other direction. We'll start with the Sal attribute in the Emp entity object and see how to discover which view objects reference that entity attribute and, in turn, which page definitions reference that view object attribute. With the Emp entity object open in the overview editor, click the Attributes tab, right-click the Sal attribute in the table, and select Find Usages . A new tab called Emp.Sal appears in the log window, showing all the usages of this entity attribute. We can see that the EmpView view object references the Emp.Sal attribute. Next, click the line in the Emp.Sal log window that reads EntityAttrName="Sal" (it is indented beneath the EmpView.xml node). This brings you to the XML Source tab of the EmpView view object editor, to the line that references the Sal entity object attribute. Click the Overview tab to switch to the overview editor, and click the Attributes tab. Right-click the Sal attribute, and again select Find Usages . An EmpView.Sal log window tab appears, showing the two page definitions that reference this Sal view object attribute: EditEmployeePageDef and SearchEmployeesPageDef. So again we've seen that it's easy to find which components are using other components to do impact analysis or just to better understand how the application components are related. The Find Usages feature we used on Oracle ADF components here works with Java classes as well.

Navigating Around Code

Although you can use the Go to File feature to find any Java source file in your application, Oracle JDeveloper offers a specific feature to find any Java class in your workspace, in the core Java Developers Kit (JDK) library, or in any other library your project uses. For example, to quickly find the source file of the java.util.ArrayList class, choose Navigate -> Go to Java Class from the main menu or press the Ctrl-[-] key accelerator. When the Go to Java Class dialog box appears, type the initial characters of the class name ArrayList until the list reduces enough for you to select ArrayList (java.util) by using the arrow keys and pressing the Enter key. Note that you did not have to remember the package name and that you can use combinations of uppercase and lowercase letters to more quickly reduce the list. For example, if you were to type ArLi, you would find any classes in any packages whose name contains "Ar" followed by "Li," including ArrayList. You can also use the asterisk as a wildcard character. For example, typing the name *Listener*Impl would match any class whose name contained "Listener" and ended with "Impl." Also note, in the Go to Java Class dialog box, that the Go to radio group enables you to select either Source or Javadoc . By setting this option appropriately, you can also quickly jump to the Javadoc API reference documentation for any class.

In the Go to Java Class dialog box (open it with Navigate -> Go to Java Class from the main menu, or press the Ctrl-[-] key accelerator), find the CustomPageController class in the workspace. Once you have the source of any Java class in the code editor, you can use several additional code navigation tools to further explore related classes. Note that the Structure window shows you an outline of the methods in the current class as well as the name of the class it extends (PageController).

Let's use the Structure window to quickly navigate to a method in a class by name. Click in the Structure window (or press Ctrl-Shift-S), begin typing the method name prepare, and see the search find the first matching method, prepareModel . You can either continue typing to make the method name unique or use the arrow keys to select the prepareRender method. When you press the Enter key, the cursor moves in the code editor to the selected method. Note that the Structure window shows only the methods in the current class.

To quickly navigate to any method in a class, including those inherited from superclasses, use Quick Outline instead. From the code editor, select Navigate -> Quick Outline (or press Ctrl-Shift-`). When the Quick Outline window appears over the code editor, note that by default it presents methods sorted by class. (Using the toggle button on the far right, you can change the way the methods are sorted.) Begin typing val, and note that the list is narrowed to include methods that contain "val," such as validateModelUpdates from the PageController superclass; however, because you won't have the source code for this base Oracle ADF framework class, you can't navigate to it. Press the Backspace key to widen the list of methods again, and use Quick Outline to navigate to the prepareRender method by selecting it in the narrowed method list and pressing the Enter key. (To further simplify your debugging, when the production release of Oracle ADF 11g becomes available, you can request the full Oracle ADF source code by opening an Oracle MetaLink service request.)

The last two code navigation features we'll explore are the quick peek and the tasks window. Notice the colored bands in the overview margin on the far right edge of the code editor for the CustomPageController class. If you hold your cursor over any band, a floating window will appear, offering a quick peek at the relevant source code lines, along with a heading explaining why the band is there. For example, holding the cursor over the first, peach-colored band, you'll see the onRemoveWithKey method and a heading that says, "Parameter ctx not used." (You can double-click the band to navigate to it.) You can access a similar quick peek feature from the Structure window by holding the Ctrl key down while hovering over a method name. (Again, you can double-click the method name to navigate to it.)

Next Steps

 READ more Frameworks

READ more about Oracle JDeveloper and Oracle ADF
Oracle ADF Developer's Guide

Oracle JDeveloper 11g Technology Preview
Starter workspace for this column

Next, choose View -> Tasks from the main menu to show the Tasks tab and window. The tab lists all the places in your code where you have left TODO comments as a reminder that some work is left to be done. For example, there is a "Fix this code" task for the CustomPageController class. Double-click the task to navigate to the relevant line. In the next section, we'll fix this code with the help of one more productivity feature.

Using Code Assist Suggestions

In the file, find the onRemoveRowWithKey() method, an event handler that will trigger whenever an end user interacts with a page that uses the built-in RemoveRowWithKey operation to delete a row. This custom code augments the default row-delete processing by immediately causing the transaction to commit as well.

We've left a TODO comment in the code to remind ourselves to fix a problem on the line that reads " JUCtrlActionBinding oper = null. " Replace the null on that line with ctx , the name of the PageLifecycleContext parameter, followed immediately by a dot (.). This causes a list of available methods to appear. Begin typing the first few letters of the getEventActionBinding() method name to quickly reduce the list, and then choose that method by pressing the Enter key.

At this point, a red, wavy line appears below the method call, indicating a compilation error. Hold your cursor over ctx.getEventActionBinding() to see a tool tip that explains that there is a missing cast because getEventActionBinding() is returning an interface; we want to use the concrete class instead. Also notice the Code Assist lightbulb that appears in the left margin. Click that icon to display the menu of Code Assist suggestions for correcting the problem. Select the first option in the list: Cast To . . . JUCtrlActionBinding . This fixes the problem automatically. (By using the Ctrl-Alt-Enter key combination, you can apply Code Assist suggestions without using the mouse as well.) At this point, you can test the application by right-clicking the SearchEmployees.jspx page in the Application Navigator and selecting Run.

I hope this quick overview of Oracle JDeveloper 11g's code and component navigation features will prove useful to you as you continue to check out the new features in the upcoming production release. For more information, see the draft of the Fusion Developer's Guide for Oracle Application Development Framework , available with the Oracle JDeveloper 11g Technology Preview 3 release.


Steve Muench is a consulting product manager for Oracle JDeveloper and an Oracle ACE. Since 1990 he has developed and supported Oracle tools and XML technologies and continues to evangelize them. Muench coauthored the Oracle ADF Developer's Guide for Forms/4GL Developers (Oracle, 2006) and shares tips and tricks on OTN and in his Dive into ADF blog.

Send us your comments