Introduction to Oracle ADF Development

Purpose

This tutorial shows you how to build a rich Web application that interacts with a database. You'll be using Oracle JDeveloper 12c Version 12.2.1 and the Oracle ADF framework to build the application, and in the process you'll work with Oracle ADF Business Components, Oracle ADF Faces Rich Client Components and Oracle ADF Task Flows.

The tutorial takes you through a simple scenario of building a Web application that provides a user interface to access database tables. You use Oracle JDeveloper 12c Version 12.2.1 and Oracle ADF to create a complete application including business services, user interface and page flows. The focus of the tutorial is to illustrate the visual and declarative approach that Oracle ADF provides for Java EE application development. While working through the tutorial notice how ADF saves you from writing low level code and speeds up your development process.

What Do You Need

To complete this tutorial you must:

1: Have access to or have installed Oracle JDeveloper 12.2.1. You can download it from Oracle Technology Network. Install it into a directory of your choice, which, in this tutorial is referred to as JDEVELOPER_HOME.

2: Have access to, or have installed an Oracle database, including the HR schema. (Note that the schema may be locked for security purposes. If this is the case you will need to log in to SQLPlus using the system user, and unlock it). The image below shows you an example of the page you'll create..

Required Files

Download Files

The application that you create displays information about departments and employees. You create several JSF pages that enable you to query and update the data in the database. You also create a page that is used as a display container for several task flows. To see the completed application, click the Download button to download a zip of the completed application, and then unzip it in your JDeveloper mywork folder.

When you work in JDeveloper, you organize your work in projects within an application. JDeveloper provides several template applications that you can use when creating an application and projects. The template applications are pre-configured with a basic set of technologies that are needed for developing the various types of applications. You create your working environment by selecting the template that best fits your needs and then configure it to add any additional technologies you plan to use.

In the first part of this tutorial you are going to create a new Fusion Web application and build reusable business components that will access the database. You'll be using Oracle ADF Business Components to map Java objects to existing tables in your database.

1. Start JDeveloper by selecting Start > Programs > JDEVELOPER_HOME > OracleHome > Oracle JDeveloper Studio > Oracle JDeveloper Studio.

   If a dialog box opens asking if you would like to import preferences from a previous JDeveloper installation, click No.

2. In the Select Role dialog, select Studio Developer (All Features) and click OK.

   

   Shaping, which is based on the role of the user, allows the JDeveloper environment to tailor itself. It does this by removing unneeded items from the menus, preferences, new gallery, and even individual fields on dialogs.

   Shaping can even control the default values for fields on dialogs within the tool. When you first start JDeveloper, you are prompted to choose a role that describes how you are going to use JDeveloper. If you choose a role of "Java Developer" versus "Database Developer " versus "Customization Developer " you will get a totally different experience!

3. If a dialog box opens asking if you would like to import preferences from a previous JDeveloper installation, click No.

   

4. In the Track Usage popup, click OK.

   

5. Once loaded, the JDeveloper IDE appears. The very first time you open JDeveloper, the Start Page displays. You can re-invoke the Start Page later by choosing Help > Start Page.

   Notice the various options available to help you learn about JDeveloper. After exploring some of these options, close the Start Page by clicking the X on its tab (the X appears when you mouse over the tab).

   

6. Click the New Application link in the Applications window.

   

7. In the New Gallery, select ADF Fusion Web Application and click OK.

   

8. JDeveloper loads the required features for a Fusion Web application and the Create Fusion Web Application (ADF) wizard launches. In the Name your application page of the wizard, type HRSystem as the name. If required, you can change the directory path to create your files in another location.

   In the Application Package Prefix field set the value to be demo and click Next.

   

9. In the Name your project page ensure that the project name is Model (the default). Notice that ADF Business Components and Java are listed as the project features of a Fusion Web application.

   Then click Next

   

10. The Configure Java settings page allows you to define a default package, a Java source path and an output directory. Click Next to accept the default values.

    

11. In the second Name your project page, ensure that the Project Name is ViewController. Scroll through the list of project features to see the types of technologies that can be used with a Fusion Web application.

    Click Next.

    

12. In the Configure Java settings page accept the defaults and click Finish to create your Fusion Web application and projects.

    

13. The HRSystem application and the two projects are displayed in the Applications window on the left of the screen. Save your work.

    Notice too, the Checklist on the right side of the screen. This checklist is displayed by default when a Fusion Web application is created. It is designed as a guide to lead you through the tasks involved in building this type of application. The next steps show you how the checklist might be used while developing an application.

    

In this section, connect to a database and build simple backend business components that access HR schema tables.

1. In the CheckList Overview, click the Connect to a Database step.

   

2. The step expands showing useful information such as prerequisites required for performing the task and detailed instructions on how to perform the task. Click the Create a Database Connection button.

   

3. Specify the properties for connecting to your HR schema.

   Enter the appropriate Oracle JDBC Settings to point to the right host, port and SID for your database. Click the Test Connection button to verify that you can connect successfully.

   Click OK to continue.

   

4. Click the down arrow to shrink the Connect to a Database step.

   Then, in the Checklist, set the status of the Connect to a Database step to Done.

   

5. Click the Build Business Services step to expand it, then click the Go to Substeps button.

   

6. In the list of substeps, click the Create Entity Objects and Associations sub step.

   

7. In the Select Project for Action dialog, select the Model project and click OK.

   

8. The Create Business Components from Tables wizard launches. In the Entity Objects page, click the Query button to examine the data dictionary and see available tables.

   

9. Select the EMPLOYEES, JOBS and DEPARTMENTS tables in the Available list, and click the right arrow to move your selections to the Selected list. This step creates updatable entity objects based on the tables selected.

   Then, click Next.

   

10. In the Entity-based View Objects page of the wizard, move DepartmentsView (Departments), JobsView (Jobs) and EmployeesView (Employees) to the Selected list. This step creates matching view objects DepartmentsView, JobsView and EmployeesView for performing queries on the entity objects you just created.

    Then, click Next and then Next again.

    

11. In the Application Module page, click Finish to create the business components in the Model project.

    

12. In the Checklist, set the status of the Create Entity Objects and Associations step to Done.

    

13. Click the Close Step 3 button..

    

14. Set the status of the Build Business Services step to Done

    Save all your work

    

15. In the Applications window right-click AppModule and select Run to invoke the application module tester. This starts a small Swing-based application that allows you to test the ADF Business Components you have just created.

    

16. In the Oracle ADF Model Tester window, double-click the EmpDeptFkLink1 node to show the department and employees data. Navigate between the records using the Next button and notice the automatic master-detail synchronization.

    

    

17. Click the Specify View Criteria (binocular icon) button in the master toolbar, to enter search criteria for your data.

    

    Specify 1700 in the LocationId field and click the Find button to execute the query.

    

18. The form now only shows departments in this location. Use the Next button to scroll through the departments at Location 1700, including Purchasing.

    

    You need to remove the parameter value of the search criteria to access all departments again.

Close the Oracle ADF Model Tester window, and back in JDeveloper, click the Save All icon on JDeveloper main toolbar. icon on the JDeveloper menu bar, or select File > Save All from the menu.

JavaServer Faces (JSF) is a standard Java EE technology that simplifies Web development. In this part of the tutorial you create a JSF page to access the business components that you created in the previous part.

You create a form that can be used to display and modify data. You use a master-detail relationship to display information about employees in a department. To build the page you'll use Oracle ADF Faces Rich Client components. These components allow you to build an Ajax-based rich Web UI without writing low-level HTML and Javascript code.

In this step, develop a page

1. Right-click the ViewController project node in the Applications window, and select New > Page...

   

   The Web part of the application is developed in a separate project called the ViewController project, which you created in the previous part of this tutorial when you created the Fusion Web application.

   Maintaining a separation between the Model layer and the user interface by developing them in separate projects, makes the business services layer more reusable.

2. In the Create JSF Page pane, set the File Name to HR.jsf and ensure the Document Type is set to Facelets.

   Then to start building the page with a temple, select the Reference ADF Page Template radio button.

   In the Templates column, select the Tablet First Template and then click OK.

   

3. By default, the center of the IDE displays the page in a visual editor.

   On the lower left, the page is displayed in a structured format.

   The properties for any selected item can be modified in the lower right.

   

4. In the Structure window, expand the f:view > af:document - HR,jsf > af:form and select the af:pageTemplate.

   In the Properties window, set the endWidth to 0px.

   

5. Use the Data Controls window to add data to the page.

   If you expand the Data Controls window, you can see the business services that are available while developing the page.

   Notice the names match those from the view components you created in the Model project.

   

   If you expand a node you see the collections, attributes and operations.

   

6. In the Structure window, select expand the Template facets node. This is where the data will be displayed on the page. The Data Controls allow you to consume the model components and bind them to the page.

   Then, from the Data Controls window, select the DepartmentsView1 node. Drag it onto the Structure window and drop it on the start facet.

   From the popup menu, select Table/ListView > ADF List View...

   

7. For the layout, select the second option: Panel Grid Layout. Then, click Next.

   

8. Set the grid layout to use two columns and one row. As you change the value on the left, the image on the right reflects how the page will look.

   Click Next.

   

9. Set Column 1 to use 20% of the space and Column 2 to use 80%. Then click Next.

   

10. Set the first column to display DepartmentId and the second to display DepartmentName.

    Then click Finish and save your work.

    

11. In the Structure window expand the nodes from the screen shot below to see the list view, the grid layout, the two columns (20% & 80%) and the Id and Name.

    

12. Select the af:listView in the Structure window and then in the Properties window, set the Selection to single.

    

13. Then, expand the Behavior node and place the cursor in the SelectionListener property.

    A blue gear icon will appear at the end of the line. If you hover above it with the mouse a Property Menu tool-tip will display

    Here you can select from a list of built-in operations to work with the data controls.

    

    Click the blue gear icon and from the menu,select Method Expression Builder...

    

14. In the Method Expression Builder, expand the ADF Bindings > bindings > DepartmentsView1 > treeModel nodes and select makeCurrent.

    Then click OK and then save all your work.

    

In this section, you test the page as currently exists. If this is the first time you are running a page from inside JDeveloper, you must first let the integrated WebLogic Server install.

1. This first step is to install the integrated WLS. If it is already installed, then you may go to step 3.

   From the Run Menu, select Start Server Instance.

   

2. In the Create Default Domain popup, enter a value for the password and then confirm it.

   Then click OK.

   

   The Log window will show you when WLS has been installed and started.

   

3. Next, deploy the page to WLS

   Right click in the visual editor and from the menu, select Run.

   

   The Log window will show you the target URL when deployed.

   

4. Your browser will display the page and the two columns - Id and Name. Also notice any of the data records can be selected. Nothing will happen when the record is selected. We'll take care of that in the next section.

   Keep the browser window open. Do not close it.

   

In this section, you modify the page by adding some components to determine the layout of the page. First you add a dashboard to set the general layout of the page. Then you add components which will display synchronized data

1. Go back to JDeveloper and in the Structure window, select the f:facet - center.

   

2. Modify the layout of the header. In the Components Window, expand the Layout node and in the Interactive Containers and Headers section, notice the Panel Dashboard.

   

   Drag it and drop it onto the f:facetCenter in the Structure window.

   

3. Next in the Components window, find another layout component, a Panel Box.

   

   Drag and drop it, in the Structure window, on the af:panelDashboard component your just added.

   

4. Add another 3 Panel Boxes to the af:panelDashboard so that you have four in total.

   

5. Set a property for all the panel boxes. In the Structure window, select all the af:panelBoxes.

   Then in the Properties window, set the Appearance > ShowDisclosure to false.

   Save your work

   

6. Back in the Structure window, select the af:panelDashboard.

   Then set the Columns to 2 and RowHeight to 350px.

   Save All your work

   

7. Go back to your browser and reload the page to see the panel boxes.

   

In this part of the tutorial, you enhance the user interface by adding a table of employees and including the ability to do column selection, by reordering the fields in one of the panels, and by binding the business components to a chart . You do this with simple drag and drop operations - behind the scenes the ADF Model layer handles the data binding for you.

1. Back in the Structure window of JDeveloper, select the af:panelBox - PanelBox1.

   Set the Text property to Employees. Save your work.

   

2. Next, add some data from the Data Controls window.

   Expand the AppModuleDataControl > DepartmentView1 nodes to expose EmployeesView4. Note that these are the "detail" employees for the "master" departments - they are linked and therefore at runtime, the employees you see in this view object are the ones who belong to the selected (or viewable) department.

   Drag the EmployeesView4 onto the Structure window and drop it on the af:panelBox - Employees node. In the popup menu, select Table/List View > ADF Table.

   

3. In the Create Table pane, allow for Single Row selection.

   Enable Sorting, Filtering and set the table to be Read-Only.

   Delete all the columns except FirstName, LastName and Email. Then click OK.

   

4. Save all your work

   Since you've added new data to the page, it must be deployed again. Right click on the page and select Run. This will compile your project, build it, and launch the integrated WebLogic Server to run it. The default web browser opens to display the page. You can follow the progress of these steps in the Log window in JDeveloper.

   

5. Now you see employee records in the first panel.

   By default the first department's (Administration) employees populate the panel.

   

   Click an different department and the employee records automatically update.

   

6. Select the Shipping department.

   Then, move the mouse over the FirstName heading to reveal two sorting icons. Move the mouse over the upward triangle and a Sort Ascending tool-tip displays.

   You may sort on any item by selecting the ascending or descending icons.

   

7. Click and hold the LastName column prompt. Then, drag it to the left and reposition it before the FirstName column.

   

   

8. Place the cursor in the field above the LastName column. Then, type "M" and press the Enter key to filer only those employees who's last name begins with "M"

   

9. Back in JDeveloper, lets work on the second panel box.

   Select the second panel box and set the Text property to Details.

   

10. From the Data Control window, drag the same EmployeesView4 collection, as you did earlier, and drop it on the Details panel box.

    In the popup menu, select ADF Form.

    

11. In the Create Form pane, keep the FirstName, LastName, Email, PhoneNumber, HireDate, JobId and Salary and remove the rest of the fields.

    Then click OK and Save your work.

    

12. You can click the recompile button, just below the menu bar of JDeveloper, to move these changes forward .

    

    Then, reload the browser page to see the second panel contains detail data of the selected employee.

    

13. Select a different employee and notice how the detail refresh with new values for the selected employee.

    

14. If you input an invalid value for the date filed, you automatically receive an error.

    

    You also get a calendar icon, to the right of the field, to pick the correct date.

    

15. Next let's work on the third box. Select it and set the Text property to Salaries.

    

16. From the Data Controls, drag the EmployeesView4 to the Structure window and drop it on the Salaries panel box.

    In the popup menu, select Chart....

    

17. When creating a chart, the same data control can be used to make a variety of different charts.

    For our purposes, select the Bar category, ensure the Chart Type is set to Bar and use the second Quick Start Layout.

    Then click OK.

    

18. Once you decide on a chart, you then you determine the bars and X axis fields to use.

    From the Available column, drag the Salary to the Bars field and drop it. Then, drag the LastName to the X Axis and drop it.

    Then click OK.

    

19. Like earlier, Save your work, recompile and reload the browser to see the changes.

    

    Now the Salaries panel shows all the employees in a department and their salaries.

    

20. If you remove the filter in the Employees panel box, then the bar chart updates to include all the shipping employees salaries.

    

21. Next, modify the chart.

    Select the dvt:barChart and then in the Properties, put the cursor next to the magnifying glass and enter Zoom. This allows you to filter and find properties easier

    The ZoomAndScroll property should be shown. Change the value to live.

    Save your work.

    

22. Recompile the application and then reload the browser.

    In the Shipping department, with no filter on the Employees, there are many salaries to show and you are not able to see all the names.

    Place the cursor over the X axis and you get a cross hair cursor. Drag the cursor to highlight a portion of the chart (The highlighted portion is a lighter shade). Then release the cursor.

    

    When you release the mouse, the selected records zoom to fill the whole panel box and you have a scrolling bar on the bottom to see all the other records that are hidden from view.

    

    Scroll the bar to the left to see the other employee salaries.

    

In this part of the tutorial, you refine the employee business components, add validation and modify how the UI displays.

1. In the Applications window, expand the Model > Application Sources > demo.model and double-click the Employees entity node.

   The full definition opens in the editor area. Select the Attributes tab to see all the employee attributes.

   

2. Select the Salary attribute then click the Validation tab below.

   To the right-click the green plus sign to add a new validation rule.

   

3. Set the Name to SalaryRange, the Type to Range, the Minimum Value to 0 and the Maximum Value to 50000.

   There are many operator you could you to implement your validations including, compare, length, restrictive list and others.

   

4. Click the Failure Handling tab and then set the error message text.

   Set the Message Text property to The Salary is out of range (must be between 0-50k).

   

5. Save All your work.

6. Next, refine the display properties of the HireDate.

   Select the HireDate attribute and then click the UI Hints tab.

   Set the Label to Hired On, the Format Type to Simple Format, and then select a Format you like.

   

7. Save all your work and then click the x in the Employees.xml tab.

   

8. Next, in the Applications window, double-click the EmployeesView component.

   In the editor, select the Attribute tab, and then the JobId.

   Click the List of Values tab and then click the green plus sign.

   

9. In the Create List of Values pane, set the Name to JobsLOV.

   Then in the List Data Source, click the green plus sign and select the JobsView.

   Click Ok to return.

   

   Back in the LOV pane, set the List Attribute to JobId .

   

10. Now set the UI Hints for the LOV.

    Click the UI Hints tab and shuttle the JobTitle to the Selected side to display it in the LOV.

    At the bottom of the pane, you can set a limit for the number of records to retrieve. Deselect the Query Limit to remove that restriction.

    Then click OK to complete the LOV.

    Save all your work

    

11. Now update the page to reflect the newly added JobId LOV.

    Go back to the HR.jsf page and in the Structure window, expand the af:panelBox - Details > af:panelFormLayout.

    Select and delete the af:inputText - JobId.

    

12. Now using the Data Controls, add the JobId back to the page (which will bring along the LOV). The key thing to remember is the attribute you add must come from the same data control as it did originally (in our case EmployeesView4).

    Open the Data Controls window and expand the AppModuleDataControl > DepartmentView1 > EmployeesView4 and select the JobId.

    Drag and drop it between the HireDate and Salary.

    In the popup menu select List of Values > ADF LOV Choice List.

    

    If the af:inputComboboxListOfValues is not positioned correctly, drag it to the correct place.

    Save all your work.

    

13. The last thing we need to do is add commit and rollback functionality.

    In the Data Controls, expand the AppModuleDataControl > Operations nodes.

    Drag the Commit operation to the Structure window and drop it on the f:facet - appNav node.

    In the popup menu select ADF Link.

    

    Then, using the same gestures, add a Rollback right below it

    

    To finish this step add a Spacer (from the Components window) between the two links. Use the search area at the top of the window to find the Spacer component.

    

14. Save your work and compile the changes. Since we added new validation, right-click in the HR.jsf page and select Run.

    When the browser opens, navigate to the Details panel box, click the widget next to the JobId and notice the drop down displaying all the job names. Change the job to a different value.

    Also notice the label and format for the HireDate field match what we set earlier.

    

Web applications usually have more than one page in them. In this part of the tutorial you two pages - a Job Search page, and an Edit page - to your application and use the ADF Task Flow Diagrammer to define the navigation rules between the two pages. You then use features of the ADF Faces Framework to add extra functionality to the pages. Finally you add the task flow to one of the panels on the page.

In this section, you work with the ViewController project and include task flows to determine business processes. You create a new task flow, add view components and control flows and then consume the task flow in the HR page.

1. In the Applications window, right-click the ViewController and select New > ADF Task Flow....

   

2. In the Create Task Flow pane, set the File Name to JobSearch.xml. The remaining values should be fine, confirm the Create as Bounded Task Flow and Create with Page Fragments checkboxes are selected.

   Then click OK.

   

3. The task flow opens in the editor. Notice the Components window now shows activities and control flows you may add. You may call a method or another task flow, invoke routers or return to called task flows. We'll keep it simple and add a couple of pages, with a control flow between them.

   From the Components window, drag a View activity onto the editor and drop it. Set the name to search. The green circle surrounding the view signifies it is the entry point to the task flow.

   

   Add another View activity, to the right, and name it edit.

   

4. Next, from the Components window, drag a Control Flow Case and drop it on the search view activity as the starting point. Then click on the edit view activity as the ending point.

   Name the flow edit.

   

   Add another flow starting with the edit going back to search. Name it back.

   Save all your work

   

5. Next, define the search page. This page will let you search for jobs and then move on to update properties about the job

   Double click the search view to create the page.

   The name is carried over to the Create a new ADF Page Fragment pane. Make sure the Create Blank Page radio button is selected and then click OK.

   

6. Expand the Data Controls > AppModuleDataControl > JobView1 > Named Criteria and select the All Queryable Attributes.

   Drag the All Queryable Attributes onto the editor and drop it near the top left of the page. A the popup menu will appear. Select Quick Query > ADF Quick Query Table...

   

7. In the Create Table pane, set the Row Selection to Single Row and select both Enable Sorting and Enable Filtering check boxes.

   Then click OK.

   

   The Structure pane and editor area should look like the following image.

   

   Save all your work

8. Make a change to the JobId and convert it to a different component.

   In the editor, right-click the JobId outputText and from the menu, select Convert To...

   

   In the Convert Output Text pane, scroll down and select Link. Then click OK.

   

   In Confirm Convert pane, ensure Value is selected and then click OK.

   

9. Next, set a couple of properties for the link.

   In the Structure window or in the editor, select the link. Then in the Properties window, set the Text property to Select and then, using the dropdown, set the Action property to edit.

   Save your work.

   

10. Next, create the edit page.

    Go back to the JobSearch task flow and double-click the edit view.

    

    The values in the create page should be fine. Check that yours look like the image below. Then click OK.

    

11. From the Data Controls window, drag the JobView1 collection and drop it on the edit page.

    In the popup menu, select ADF Form.

    

12. In the Create Form pane, select the Submit check box.

    Then click OK.

    

    The Structure window and editor should look like the image below.

    

13. Next, modify some properties to commit changes.

    First find and select the Submit button. Change the Text property to Save and Action to back.

    

14. Next, add the commit functionality.

    In the Data Controls window, expand the Operations node. Select the Commit operation and drag, then drop it on the Save button.

    

    In the popup pane, select properties that should remain at their current values. The unselected properties will be updated to new values.

    Select the text, disabled and action properties.

    Then click OK and Save all your work.

    

15. Now, lets work on the final panel box in the HR page.

    Open the HR page in the editor and select the af:panelBox - PanelBox4.

    Set the Text property to Job Search.

    

16. In the Applications window, expand the ViewController > Web Content > Page Flows nodes and select the JobSearch task flow.

    Drag the JobSearch page flow onto the HR page and drop it on the Job Search panel box.

    In the popup menu, select Region.

    

    The Structure window should display the region, nested in the Job Search panel box. If it is not, move so it is.

    

17. Save your work

    Then, right-click the HR page and select Run.

    

18. When the page opens, move the cursor to the Job Search panel box.

    Set the Search property to JobTitle and then enter M in the search box. Then press Enter.

    All the job titles that begin with M are displayed.

    

19. Next, test the edit page. Click the Select text for one of the jobs .

    

    This link will use the edit flow and navigate you to the edit page.

    

20. Set the Min Salary to 10000 and click Save.

    

    You will return to the search page, with the new minimum salary displayed.

    

21. As a final task, .

    In the Component window, expand the Operations node and scroll down to the Drag and Drop section.

    Select the Component Drag Source. Then drag it to the Structure window and drop it on the Employees panel box.

    

    Repeat the same process and add Component Drag Source components to each of the remaining panel boxes. Each of the four panel boxes should have their own drag component.

    

22. Save your work.

    Then, right-click the HR page and select Run.

    

23. In the running page, notice the handle icon at the top and center of the panel box.

    

    With your mouse, select and hold one of the handles. Then move it to a different place on the page and release.

    

    The new location of the panel box remains until the page is reloaded.