As Published In
Oracle Magazine
July/August 2006

DEVELOPER: Frameworks


A New Face on the Block

By Steve Muench Oracle Employee ACE

Oracle ADF offers new JSF support and enhanced, visual, declarative development.

Oracle JDeveloper 10g Release 3 (10.1.3) improves the J2EE development experience from every point of view. Released in February 2006, it provides slick new refactoring features that make iterative code improvements a snap. It also offers new teamwork support that simplifies collaborative development, and it provides all-around enhancements for visual, declarative development that make it easier than ever to build enterprise Web and desktop applications. This column highlights some of the main new Oracle Application Development Framework (ADF) Release 3 (10.1.3) features, by building a set of Web search pages using the JavaServer Faces (JSF) standard.

JDev and JSF

In the past, J2EE developers had to choose among several competing approaches to build Web user interfaces (UIs). In 2005, however, JSF emerged to become the standard approach for Web user interface development with the J2EE platform. JSF simplifies the process of building Web UIs, by introducing Web UI components that have attributes, events, and a consistent runtime API. Instead of wading knee-deep through tags and scripts, with JSF you assemble Web pages by using a growing set of libraries that contain off-the-shelf, data-aware components that adhere to this new standard.

The original designers of JSF incorporated several declarative development techniques to simplify the Web development process. They included the use of a standard expression language to bind components to data, automatically managed JavaBeans that can hold event-handling code, and automatic page request handling and page navigation. If you use Oracle JDeveloper 10g Release 2 (10.1.2) for Web applications, you'll find these concepts quite familiar.

Oracle JDeveloper 10g Release 3 (10.1.3) introduces many new features that enhance JSF development. The visual page flow diagram lets you design how end users navigate between pages in your application. The visual page designer lets you drag-and-drop components from a palette, rearrange them on-screen, set the properties that control their look and behavior, and bind them to data.

The ADF Faces component library provides about 100 enterprise-grade JSF components to use in your pages, and the Data Control Palette makes it easy to drop data-bound controls, input forms, tables, trees, and master/detail combinations using these components. Oracle ADF has been enhanced to directly support JSF, so the process of building JSF pages that display and modify data is the same code-free experience you've come to expect from previous releases.

The simplest way to get acquainted with JSF and Oracle ADF in Oracle JDeveloper 10g Release 3 is to create some simple pages that you may have built before with previous releases. I'll construct two kinds of search pages to show the productivity improvements you'll find when using the current version, compared to Oracle JDeveloper 10g Release 2. In particular, you'll find that tasks that used to require code to accomplish are now 100 percent declarative.

Creating a Search Page and Using Bind Variables

Let's start by creating a new application by selecting File->New from the main menu and then selecting General->Application and clicking OK in the New Gallery dialog box. In the Create Application dialog box, enter an application name, select the Web Application [JSF, ADF BC] application template, and click OK . Oracle JDeveloper will create a new application workspace with a Model project for the business components, along with a ViewController project for the JSF pages that comprise the Web user interface. Next, right-click the Model project; select New ; and under Business Tier->ADF Business Components , start the Business Components from Tables wizard that you've seen in previous columns to create a default ADF entity object, view object, and application module for working with data from the EMP table in the SCOTT schema. When creating these components, give them the names Emp (EO), EmpView (VO), and DemoModule (AM), respectively.

Next, let's look at a new Oracle JDeveloper 10g Release 3 (10.1.3) feature that lets you add named bind variables to view objects. Double-click the EmpView view object to open the editor, select Bind Variables , and click New to define a bind variable named EmployeeName of type String. You could enter a default value for the bind variable, but for now leave it blank and it will default to NULL. Next, select the Control Hints tab for this variable, enter Name Starts With as the Label Text hint, and click OK . Add a second bind variable named MinSal of type Number with a default value of zero (0). Enter Salary Greater Than as its Label Text control hint, and click OK . Next, visit the SQL Statement panel to reference these bind variables in the view object's WHERE clause. In the Query Clauses section, enter ENAME LIKE UPPER(:EmployeeName)||'%' AND SAL > :MinSal in the Where field, and click OK .

At this point, I've enhanced the EmpView view object to accept two named bind variables. Now I'll show how easy it is to leverage these named bind variables in a JSF search form.

To create a new JSF page, right-click the ViewController project and select New to open the New Gallery dialog box. Under Web Tier->JSF , launch the new JSF JSP page wizard. On step 1 of the wizard, for File Name enter the name SearchUsingBindVars .jsp and click Finish . The visual page designer opens, and the Data Control Palette should appear. If you don't see it, select the View->Data Control Palette menu item. Expanding the tree display in the Data Control Palette, find the EmpView1 view object instance and, nested inside it, an Operations folder. Expand that folder to see the new ExecuteWithParams built-in action for executing a view object with named bind variables. Drag the ExecuteWithParams action and drop it onto the empty page in the visual designer. In the Create menu that appears, select ADF Parameter Form in the Parameters category. In the Edit Form Fields dialog box that appears, click OK to create a parameter form with all of the bind variables in the EmpView1 view object.

You should now see two labeled text fields on your page, along with an ExecuteWithParams button. This parameter form allows the end user to enter a value for either or both of the view object's named bind variables. When the user clicks the button, the values will be assigned to their respective variables and the view object's query will be executed.

Next, add a table that shows the results of the query. To do this, select EmpView1 in the Data Control Palette and drop it onto the page below the parameter form. In the Create menu that appears, select ADF Read-only Table in the Tables category. In the Edit Table Columns dialog box that appears, select all EmpView1 attributes to be shown in the table, select both the Enable selection and Enable sorting check boxes, and click OK .

Believe it or not, you've just finished building your first JSF page with full search functionality. Run the page by selecting Run from the right-mouse context menu, and experiment with it by entering values for the two search form fields. It doesn't get much easier than this.

This approach of using named bind variables and a parameter form based on the ExecuteWithParams built-in action is perfect in cases where you're always searching on the same fixed set of parameters. If, however, you need to let the end user mix and match any set of query-by-example criteria, you should build the search using find mode. I'll walk through those steps next.

Creating a Search Page Using Find Mode

Create a second JSF page, named SearchingUsingFindMode.jsp. To create the search area on the page, drag EmpView1 from the Data Control Palette and drop it onto the page as an ADF Search Form (in the Forms category). By default, Oracle JDeveloper creates a search form field for each attribute. Looking in the Structure Window, you can see that it creates the UI controls inside a container control called an af:panelForm. Select that panel form control, go to the Property Inspector panel, and enter 3 as the value of its Rows property to lay out the fields in the panel form in three rows. Next, drag EmpView1 in the Data Control Palette and drop it on the page below the search form as an ADF read-only table (in the Tables category). As before, keep all the attributes and enable selecting and sorting.

If you were to run the form now, you would have a page with a form that allows both searching and editing, along with a table that displays the results. Most Web users, however, expect search fields at the top of the screen always to function as search fields, rather than as a toggle between search and edit modes. You can make this change by performing just a few additional steps.

In order to have some UI controls display the results of the search while others stay fixed in find mode, you need to introduce a second iterator binding for the same EmpView1 view object. With two iterators, you can force one to stay in find mode while the other remains in regular "display results" mode. To add a second iterator, open the page's page definition by right-clicking on an empty area of the page and selecting Go To Page Definition from the context menu. This step opens the SearchUsingFindMode.xml page definition file in the code editor and shows its structure in the Structure Window.

Notice that the page definition file contains an executables section as well as a bindings section. The executables section lists all of the iterators related to data that your page displays. The bindings section lists the binding objects that connect your page's UI controls to attributes of the underlying data collections. To add a new iterator, right-click the executables node in the Structure Window and select Insert inside executables > iterator . In the Iterator Binding Editor dialog box that appears, expand the data control to show your EmpView1 view object instance and select it. In the Iterator Id field, change the name of the iterator to EmpView1ResultsIterator , to reflect the fact that it will be used to show the results of the query, and click OK . Next, go to the bindings section of the page definition, and edit the table binding named EmpView1 by right-clicking it and selecting Properties . In the Select an Iterator list at the bottom, change the table binding to be bound to the new EmpView1ResultsIterator , and shuttle all of the attributes from the Available list into the Display Attributes list. Click OK .

The last step requires forcing the original EmpView1Iterator to always stay in find mode. With Oracle JDeveloper 10g Release 2 this step required writing code, but in the 10.1.3 release it is declarative. In the Structure Window for the page definition, right-click EmpView1Iterator in the executables section, and select Insert before EmpView1Iterator > invoke Action . In the Insert invokeAction dialog box that appears, give the binding a name by setting the id property to ForceFindMode and select the Find action binding from the Binds list. The invokeAction is a declarative facility in the page definition to invoke an action binding during page processing.

On the Advanced Properties tab, create a Boolean expression for the RefreshCondition property that indicates when the invokeAction should invoke its action binding. Since invoking the built-in Find action will toggle the iterator in and out of find mode, it should be invoked only when the user is not in find mode. To enter the correct Expression Language (EL) expression for this condition, you can use the new EL expression builder in Oracle JDeveloper 10g Release 3. To do so, click the (...) button next to the RefreshCondition field. In the EL expression builder dialog box that appears, expand the ADF Bindings folder, the bindings node beneath it, and the EmpView1Iterator node to see its properties. Select its findMode property and click the (>) button to insert the appropriate EL expression that represents that iterator property. The expression ${bindings.EmpView1Iterator.findMode} appears in the Expression field. With the cursor just inside the closing curly brace, click the (==) button in the Logical Operators section and type the word false to end up with the expression ${bindings.EmpView1Iterator.findMode == false} . Click OK , and then click OK again to dismiss the Insert invokeAction dialog box.

This last step completes the declarative configuration of the second search form. This involved changing the table binding to display the results using this results iterator and forcing the initial iterator to always stay in find mode. As a final touch, you can flip back to the visual editor and delete the Find button and af:outputText control that mentions "Find Mode" since you won't be needing them. Just select each one and use the delete key to remove them. You can now run your SearchingUsingFindMode.jsp and experiment with the search fields at the top. Although this search page required a few more steps, it still didn't require writing a line of code.

Fine-Tuning the Result

To further improve the search page you've just built, you can take advantage of a few more declarative features of the Oracle ADF/JSF combination. One common feature of search pages is to avoid displaying any initial results until the end user has a chance to enter some search criteria. You can easily accomplish this in Oracle ADF Release 3 by just setting one additional configuration parameter on the page definition.

Visit the page definition again for the SearchingUsingFindMode.jsp page, and select EmpView1ResultsIterator in the executables section of the Structure Window. Go to the Property Inspector, click in the RefreshCondition property, and click the (...) button. In the EL expression builder dialog box that appears, expand the JSF Managed Beans folder and the adfFacesContext node beneath it, and select its postback property. Click the (>) button to insert the EL expression that represents that property. The expression ${adfFacesContext.postback} appears in the Expression field. With the cursor just inside the closing curly brace, click the (==) button in the Logical Operators section, type the word true to end up with the expression ${adfFacesContext.postback == true} , and click OK . This postback property on the ADF Faces context object evaluates to false when a page first displays. When the user interacts with a UI control on the page, a postback event is sent to the

Next Steps



READ more about Oracle JDeveloper 10g and Oracle ADF
oracle.com/technetwork/products/jdev
oracle.com/technetwork/products/jdev/tips/muench/designpatterns

DOWNLOAD
Oracle JDeveloper 10g

server to be processed, and the postback property changes to true. By referencing this postback expression as the value of the RefreshCondition property of the iterator binding, the iterator remains unbound for the current page request when postback evaluates to false. As a result, when you now run the SearchingUsingFindMode.jsp page, it will not initially display any data.

When you run the page, you should notice that the data doesn't initially appear, but an empty table appears showing the words "No rows yet." As a final touch, configure the table not to display at all when the page initially renders. To do this, select the table in the visual editor. At any point, you can tell exactly what component is selected by looking at the Structure Window or in the "tag strip" at the bottom of the visual editor window. If you don't initially select the table, you can use these other two mechanisms to quickly select the containing element that you want. With the table selected, go to the Property Inspector to change the value of its Rendered property. With that property selected, click the Bind to data button in the Property Inspector toolbar to bring up the EL expression builder. Use the same steps you just used, above, to enter the expression #{adfFacesContext.postback == true} , and click OK . Since this expression evaluates to true only when the user clicks a button in the form, the Rendered property of the table will evaluate to false when the page initially displays, and the table will disappear from view.

With just a few steps, you've built two styles of search pages using JSF and Oracle ADF. For a more in-depth introduction to the new features in Oracle ADF and Oracle JDeveloper for JSF development, I recommend reading the ADF Developer's Guide for Forms/4GL Developers on OTN. I also recommend visiting the Oracle JDeveloper page on OTN, where you'll find links to a number of interesting tutorials. 


Steve Muench is a consulting product manager for Oracle JDeveloper. In his more than 16 years at Oracle, he has supported and developed Oracle tools and XML technologies and continues to evangelize them. He authored Building Oracle XML Applications (O'Reilly & Associates, 2000) and shares tips and tricks on OTN and his Dive into BC4J and ADF blog.


Send us your comments