|
DEVELOPER: JSF
From ADF UIX to JSF
By Jonas Jacobi
Oracle ADF Faces Components brings a library of reuse to JavaServer Faces.
JavaServer Faces (JSF) is a component-based view framework. Some component-based framework implementations, including Tiles and Oracle's Application Development Framework (ADF) UIX, are currently more mature, but JSF has gained popularity quickly and extensive tool support for JSF is on the way.
As described in "Developing Faces" in the July/August 2004 issue of Oracle Magazine, you can use the current production release of Oracle JDeveloper 10g to build and import JSF applications. An upcoming release of Oracle JDeveloper, however, will contain the full JSF development solution, which includes complete integration with Oracle ADF. A key part of this JSF development solution is Oracle ADF Faces Components.
Oracle ADF Faces Components has been released as an early-access preview, in advance of the new Oracle JDeveloper production release. You can download this component set and use it now with the current Oracle JDeveloper release. Note that Oracle ADF Faces Components is currently available only as the early-access release and is therefore not supported in any type of production environment.
This article illustrates how you can build a JSF application with one master page and one detail page, using Oracle JDeveloper 10g, Oracle ADF Faces Components, and regular Java beans. Note that you won't require any other Oracle products at design time or runtime to use Oracle ADF Faces Components. What Is Oracle ADF Faces Components?
Oracle ADF Faces Components is currently available in the form of Oracle ADF UIX components. Oracle ADF UIX, a user interface framework for building J2EE-compliant Web applications that are component-based and XML-metadata-driven, is one of the view technologies available in Oracle ADF. Oracle ADF Faces Components is an evolution of these components based on the new JSF standard. As a technology, Oracle ADF UIX has been extensively used within Oracle for several years to produce products such as Oracle iLearning, Oracle Enterprise Manager, and Oracle E-Business Suite.
The Benefits of Using Oracle ADF Faces Components
Although the initial release of JSF provides developers with a rich architecture, it has functionality limitations and only a limited number of user interface components is available. However, Oracle ADF Faces Components gives developers a rich set of user interface components, such as data tables, hierarchical tables, and color and date pickers that can be customized and reused. Using ADF Faces to create user interfaces ensures a consistent look and feel, allowing you to focus more on user interface interaction than on look-and-feel compliance.
Oracle ADF Faces Components provides a high level of interactivity at runtime. One common component functionality is partial page rendering (PPR). PPR allows the component to render just a piece of the page instead of the entire page, which is the default in most cases. Perhaps, for example, you would like to scroll through records in a table; this would normally require the entire page to be refreshed, but with PPR only the table will be refreshed. The sample application featured in this article uses the PPR functionality.
Building an Oracle ADF Faces Application with Oracle JDeveloper 10g
To build the Oracle ADF Faces application described in this article, you
- Set up Oracle JDeveloper 10g to work with the early-access release of Oracle ADF Faces Components
- Download and set up the project files that accompany this article
- Build the table view page and add the sorting feature
- Create the detail page form and add validation
Set up Oracle JDeveloper 10g
Before you can build the sample application described in this article, you need to set up Oracle JDeveloper 10g to use ADF Faces Components and the JSF reference implementation. This article doesn't address this setup, so refer to the Oracle ADF Faces Components page, at oracle.com/technology/products/jdev/htdocs/partners/addins/exchange/jsf for more information about how to set up Oracle ADF Faces Components with Oracle JDeveloper 10g. You also need to have access to a database with the Oracle-provided HR sample schema.
Download and Set Up Project Files
A prebuilt workspace for the sample application in this article is available at oracle.com/technology/oramag/oracle/04-nov/o64adfjws.zip. This workspace contains two projects: Model and View. The Model project contains the underlying business services, basically a set of Java beans that calls the HR schema and returns a list of employees. The View project is the placeholder for the pages. This project contains all the configuration files needed to make this application work with JSF and Oracle ADF Faces Components.
To set up the prebuilt workspace for this sample application, do the following:
- Download the sample workspace from oracle.com\technology\oramag\oracle\04-nov\o64adfjws.zip, and extract it. This article refers to the location of the extracted file as [SAMPLE_HOME].
- In Oracle JDeveloper 10g, select File->Open and locate the MyADFFaces.jws file, located in [SAMPLE_HOME]/MyADFFaces.
- Click on Open to open the workspace. The MyADFFaces workspace node appears in the Applications Navigator.
- Expand the MyADFFaces workspace node (click on the + sign).
- In the Model project, locate the DBConnection.java file (under Applications sources->model.db), and open the file in the Code Editor.
- Change the following lines in the DBConnection.java file, to make sure you have the right credentials to access your database:
private static String url = "jdbc:oracle:thin:
@127.0.0.1:1521:ORA92";
private static String usr = "hr";
private static String pwd = "hr";
- Recompile and save.
Build the Table View with Oracle ADF Faces Components
JSF as a framework is by design markup-agnostic—meaning that it is up to the implementer of JSF to decide which markup should be supported—but according to the JSF specification, all JSF implementations need to support at least JavaServer Pages (JSP).
Which JSP syntax to use when building a JSF application is a personal preference, and the good thing is that JSF components do not care which flavor is used. My personal favorite is the JSPX (JSP Document) syntax, so I have decided to use JSPX for this article.
Managing the data. Before you create the application pages, you need to provide access to your data by using managed beans, which are created and populated by JSF when they are needed.
To set up the creation of managed beans for this sample application, do the following:
- Under the MyADFFaces workspace node in the Applications Navigator, locate and expand the ADFFacesView project.
- Locate the faces-config.xml file (in the WEB-INF directory), and open the file in the Code Editor.
- Copy and paste the following content between the <faces-config> and </faces-config> elements in your faces-config.xml file:
<managed-bean>
<managed-bean-name>myEmployees
</managed-bean-name>
<managed-bean-class>
model.beans.Employees
</managed-bean-class>
<managed-bean-scope>request
</managed-bean-scope>
</managed-bean>
This procedure creates a managed bean called myEmployees that can be referenced from within your JSF JSP page.
- Save your work.
Creating an Oracle ADF Faces page. The first page to create is a master page with a table that allows the end user to select an employee and then browse to another page to get detailed information about that employee. The table displays 10 employees at a time.
To create the master page, do this:
- Create a new JSP page, by selecting File->New->Web Tier->JavaServer Pages. In the right panel, select JSP Document and click on OK.
- Enter the name empTable.jspx for the new JSP document.
- Switch the Component palette to the JSF Core page.
- Drag and drop the view component onto the page. The view component is required for all JSF pages.
- If you're not already in code view, click on the Source tab at the bottom of the page to open the page in the Code Editor.
- Make sure that the <f:view> tag is located outside the <html> tag. The <f:view> tag needs to wrap all page content, including the <html> tag and the <body> tag.
- Switch the Component palette to ADF Faces HTML.
- Drag and drop the head component onto the page. Use this component to replace the default <head> tag. This allows the page to pick up the ADF Faces style sheet and images.
- Switch back to the Visual Editor, by clicking on the Design tab at the bottom of the page.
- Switch the Component palette to ADF Faces Core.
- Drag and drop the form component onto the page. The black border denotes containership. If you check the code, you'll see that the <af:form> tag is inside the existing <body> tag.
- In the Visual Editor, drag the table component and drop it inside the form component.
- In the Property Inspector, set the following properties on the table component:
a. Value = #{myEmployees.employees}
b. Var = row
c. Row = 10
- Switch the Component palette to JSF Core.
- Drag the facet component, drop it inside the existing table component, and set the facet name property to selection. Note that a component can contain multiple facets and that each facet can contain only one child component.
- Switch the Component palette to ADF Faces Core.
- Drag the tableSelectOne component, and drop it inside the facet component. Enable single selection on the table, by setting the tableSelectOne component as the selection facet.
|
Evolving Faces
The first generation of Oracle ADF Faces Components begins with the transition from Oracle ADF UIX. Plans for the next generation of Oracle ADF Faces Components include extending the first-generation Oracle ADF Faces Web interface to provide the same functionality as a traditional thick client, such as a Swing-based application.
While menus, for example, implemented in current JavaServer Pages (JSP) applications provide static information, menus planned for the richer, next-generation Oracle ADF Faces Components will behave in the same way as traditional Swing-based components, with live updates in the browser. |
Note: The tableSelectOne component supports the text attribute, which is used to display instructions to the user. The children of this component are usually ActionSource components, which provide the actions available to the user after a row is selected.
- Set the text property on the tableSelectOne component to Select Employee and click...
- From the ADF Faces Core palette, drag the commandButton component and drop it inside the tableSelectOne component. On the commandButton component, set the text property to Show and the action property to showDetails.
- Drag the column component, and drop it inside the table component.
- Inside the column component, add an outputText component and set the value property to #{row.first_name}.
- Repeat steps 20 and 21 to add two more column and outputText components, using the following values for the value property:
#{row.last_name}
#{row.email}
- Now, inside each column component, add a facet component from the JSF Core palette and set the name property to header. This adds column headers to the three columns in the table.
- Next, inside each header facet, add an outputText component from the ADF Faces Core palette and set the value property for the appropriate columns as follows: Firstname, Lastname, and Email.
- Save your work, and run the page by right-clicking on empTable.jspx and selecting Run.
Running the page starts the embedded J2EE container—OC4J—and attempts to launch the page in your default browser. Before the page can run in your browser, however, you must insert the /faces Servlet mapping into the URL in your browser to complete the request by using the Faces Servlet.
- Insert the mapping into the browser's URL, as follows: yourhost:8988/YourJ2EEContextRoot/faces/empTable.jspx. An alternative is to create an empty JSP page with a redirect to the URL.
As you access the page with the proper URL, you should see the page with a table that lists 10 employees at a time, as shown in Figure 1.
 |
|
Figure 1: Creating the first table view
|
Try navigating the table by clicking on the Next and Previous links. You will see that not only is the table component showing the next or previous 10 employees but the table is also refreshing only the table contents and not the entire table or page. This is possible thanks to the PPR built-in component feature.
Making table columns sortable. One table feature that is often requested by application end users is sorting of column data. This feature can be very difficult to implement, and even if you have implemented it, the page still needs to refresh to be updated with data in the new sort order. By replacing the outputText component in the header facet of a column with a sortableHeader component, you can enable the sorting capability of that column in an Oracle ADF Faces table.
Locate the following code for the Lastname column:
<af:column>
<f:facet name="header">
<af:outputText
value="Lastname"/>
</f:facet>
<af:outputText
value="#{row.last_name}"/>
</af:column>
and replace it with the following:
<af:column>
<f:facet name="header">
<af:sortableHeader
text="Lastname"
property="last_name"/>
</f:facet>
<af:outputText
value="#{row.last_name }"/>
</af:column>
- Save your page, and run it. The screen appears as in Figure 2. A UI indicator on the Lastname column header lets you know that the column is sortable.
- Try sorting by clicking on the sortable column header. Once again, only the contents of the Oracle ADF Faces table are refreshed, not the entire table or page.
 |
|
Figure 2: Creating the first sortable table view
|
Making data available. Before you build the detail page, make sure the data the end user selects is available to the detail page. To pass data to a JSP page, use a scope. Three standard scopes are defined in JSF—applicationScope, sessionScope, and requestScope. In addition to the standard JSF scopes, Oracle ADF Faces Components adds a new scope, pageFlowScope. Values added to this scope automatically continue to be available as the user navigates from one page to another. But unlike session scope, these values are visible only in the current "page flow." If the user opens a new window and starts navigating, that series of windows will have its own page flow, and values stored in each window will remain independent. Clicking on the browser's Back button automatically resets the pageFlowScope to its original state.
Note: pageFlowScope is supported for all JSF components, not just Oracle ADF Faces Components.
To set up the pageFlowScope for the detail page, do the following:
- Open the empTable.jspx file in the Code Editor.
- Add the following code to the commandButton component:
<af:commandButton
text="Show"
action="showDetails">
<af:setActionListener
from="#{row}"
to="#{pageFlowScope.employeeDetail}"
/>
</af:commandButton>
The ADF Faces <af:setActionListener> tag has two properties: from and to. The tag simply takes a value from the from property and puts it where the to property value says to put it, without the need to write any Java code.
- Save your file.
Completing the Application
Creating the detail page. To create the detail page, do the following:
- Create a new JSP document, and give it the name details.jspx.
- Switch to the Code Editor.
- Replace the code in the details.jspx page with the code provided in Listing 1.
- Switch to the Visual Editor. From the JSF HTML palette, drag the panelGrid component and drop it inside the form component.
- In the Property Inspector, set the columns property of panelGrid to 2.
- Switch the Component palette to ADF Faces Core.
- Drag the outputText component, drop it inside the panelGrid component, and set the value property to "Firstname:".
- Next, drag the inputText component, drop it inside the panelGrid component, and set the value property to "#{pageFlow Scope.employeeDetail.first_name}".
- Repeat steps 7 and 8, to add four more input fields for last_name, email, salary, and hire_date, respectively. Your code for the panelGrid component should now look like the code in Listing 2.
- Save your work.
Navigating between pages. Before you can test your application, you need to ensure that navigation between your two pages works when the user selects Show. The commandButton component has a property called action. This property can either be mapped to an action method that returns a String value or it can contain a static string value—both representing the action outcome. When the user clicks on the commandButton, it either executes an action method returning the desired outcome or, as you are going to do in your sample application, executes with a static outcome. The outcome is "success," if everything works as planned, or "failure," if there are problems during execution. The outcome can be mapped to navigation rules defined in the faces-config.xml file.
- Locate and open the faces-config.xml file.
- Add the following code snippet between <faces-config> and </faces-config>:
<navigation-rule>
<from-view-id>
/empTable.jspx</from-view-id>
<navigation-case>
<from-outcome>
showDetails</from-outcome>
<to-view-id>
/details.jspx</to-view-id>
</navigation-case>
</navigation-rule>
- Save your work, and run the application. Select an employee, and click on Show to be redirected to the detail page.
 |
|
Figure 3: Detail Page
|
Adding validation. At this point, the detail form lets you type in any values; it does not validate the input values, such as whether the values entered are of the right type or length. Most applications contain several fields that require some validation. For example, using the preceding detail page, Hiredate needs an input in date format and Salary is required to have a value. In this sample, you replace the Hiredate inputText component with a selectInputDate component. The selectInputDate component has a built-in calendar that allows the end user to pick a date. It also provides built-in client-side validation support—that is, it checks for a valid date format.
- Open the details.jspx file in the Code Editor.
- Locate the following code for the Hiredate field:
<af:outputText
value="Hiredate:"/>
<af:inputText
value="#{pageFlowScope
.employeeDetail.hire_date}"/>
- Replace that code with this:
<af:outputText
value="Hiredate:"/>
<af:selectInputDate
value="#{pageFlowScope
.employeeDetail.hire_date}">
<f:convertDateTime
pattern="yyyy-MM-dd"/>
</af:selectInputDate>
The <f:convertDateTime> tag is a JSF standard converter that allows you to define a pattern that determines how the input will be formatted and parsed. This tag, however, is optional and is not needed for the sample to work.
- Save your file, and run the application.
Conclusion
As one of the active members of the JavaServer Faces expert group, Oracle has committed itself to evolve and support JavaServer Faces, as evidenced by this early-access release of Oracle ADF Faces Components.
Jonas Jacobi (jonas.jacobi@oracle.com) is a senior product manager for Application Development Tools at Oracle Corporation and is responsible for the ADF UIX/ADF JavaServer Faces technologies in Oracle JDeveloper.
|
Bookmark
