Add Services with a Smile

Consume enterprise web services from mobile apps via data controls in Oracle Mobile Application Framework.

By Chris Muir

July/August 2015

Get Mobile and Connected” (Oracle Magazine, May/June 2015) showed how Oracle Mobile Application Framework makes it easy to create mobile application pages that access an existing web service. Oracle Mobile Application Framework takes on the burden of working with web services—be they enterprise-scale SOAP services or more-contemporary REST services—freeing you to focus on building the other parts of your app.

The previous column’s exercise hid some of the implementation details of the sample application, a corporate phonebook app. Now you’ll explore those details by extending the phonebook app. Specifically, you’ll learn how to integrate remote web services into your apps without writing code, by using an Oracle Mobile Application Framework abstraction called a data control.

Sample Application Overview

The phonebook app you created in the previous exercise generates a list of employees in a single page, ViewEmployees.amx, via a call to a remote web service. Now you’ll extend the app so that it’s composed of two pages. When an employee is selected in the ViewEmployees.amx page’s list view, the app—via a task flow—navigates to a new second page, EmployeeDetails.amx. The new page shows details about the employee that are fetched by a separate call to another web service. To make the new page more useful, you’ll include a map that shows the employee’s address. Figure 1 shows the app’s two pages.

Figure 1: The extended phonebook app

Getting Ready

Ensure that you’re using the studio edition of Oracle JDeveloper 12c (12.1.3) with the Oracle Mobile Application Framework v2.1.2+ extension, available as a free download on Oracle Technology Network. Follow the setup instructions in the Oracle Mobile Application Framework documentation to configure a Mac with Xcode or a Windows PC with the Android SDK.

Download the sample application, and save the file to a local folder on your computer that does not use spaces in the folder name or path. Unzip the file, and then unzip each of the two extracted files. The local folder contains two subfolders, each containing an Oracle JDeveloper workspace:

  • The HrServicesSubset folder contains a demonstration REST web service that you’ll run on your PC. This web service provides the employee data for your mobile phonebook app to retrieve.
  • The PhonebookStarterApp folder contains a prebuilt Oracle Mobile Application Framework application workspace that starts where the previous column left off.

Follow these steps to get started:

  1. In Oracle JDeveloper, select File -> Open and navigate to the directory containing the unpacked zip file content.
  2. Open the PhonebookStarterApp folder, and select the Phonebook.jws file. Click Open to load the workspace.
  3. Open the HrServicesSubset folder, and load the HrServices.jws workspace. You’ll work with this workspace first, so leave it open in the Application Navigator.
  4. In the Application Navigator, expand RestServices -> Application Sources ->, right-click the file, and select Run.
  5. If you are running Oracle JDeveloper for the first time, you’ll be presented with the Create Default Domain dialog box. Create a password for the default Oracle WebLogic Server domain associated with Oracle JDeveloper, leave the other fields as they are, and click OK. Oracle JDeveloper then creates the default domain and configures it for use.
  6. When the service is up and running, you should see a message like the following in your Oracle JDeveloper log window:
    Target URL—

    Copy the target URL into your browser, and add the /employees/174 suffix:
The browser should show a payload of employee data for employee 174 Ellen Abel, proving that your web service works as expected and is ready to use for this column’s exercise.

Extending Your App with a Task Flow

In Oracle Mobile Application Framework, a task flow enables you to diagrammatically model the navigation flow between pages without hiding the navigation calls in code. To start using a task flow to model the flow in the extended phonebook app, do the following:

  1. In the Application Navigator in Oracle JDeveloper, select the Phonebook workspace.
  2. Expand ViewController -> Application Sources -> META-INF, and open the maf-feature.xml file.

In the maf-feature.xml file, you define all of your application’s logical features—units of functionality—which, in turn, group the various pages of your application. For example, a weather app might have a feature for searching for cities, another feature to show the current observations for a number of cities, and a third feature to show radar images. The phonebook currently has a single employees feature, which you’ll continue to work with.

  1. In the Features section, select the feature named employees and then select the Content tab. In the Content section, click the Type list and change the type from MAF AMX Page to MAF Task Flow. Ignore the error indicator surrounding the File field.
  2. In the Includes section, select the green plus button. In the Insert Include dialog box, enter resources/css/phonebook.css for File and change Type to StyleSheet. Click OK.
  3. Click the File field’s green plus button. In the Create MAF Task Flow dialog box, enter employees-task-flow.xml in the File Name field, as shown in Figure 2, and click OK to open the newly created employees-task-flow.xml file in a separate window.


    Figure 2: The Create MAF Task Flow dialog box
  4. From the Application Navigator, under ViewController -> Application Sources -> Web Content -> oracle.phonebook.employees, drag the previously created ViewEmployees.amx page into the employees-task-flow.xml diagram window. The ViewEmployees icon is the starting point for your task flow.
  5. From the Components section of the Components panel (open the panel with Windows -> Components if it’s not currently visible), drag the View icon into the employees-task-flow.xml diagram to the right of the ViewEmployees icon. Change the name of the resulting icon from view1 to EmployeeDetails.
  6. Return to the Components panel, and double-click the Control Flow Case icon to select it. In the diagram, click the ViewEmployees icon and extend the resulting arrow to the EmployeeDetails icon. Click again once so that the arrow stretches between the two icons. Change the name of the flow from * to goEmployeeDetails, and finalize the work by clicking elsewhere in the diagram.

A control flow case represents a single named navigation rule between two activities in a task flow. For example, if you want the app to follow a particular navigation rule when a button is tapped, you need to refer to the control flow case by name in the Action property of the commandButton and the Oracle Mobile Application Framework runtime will navigate to the correct page.

  1. Select the goEmployeeDetails control flow case in the diagram. In the Properties panel (open it with Window -> Properties if it’s not currently visible), in the Behavior section, change Transition from <default> to slideLeft.
  2. Return to the diagram, an=d double-click the EmployeeDetails view. In the Create MAF AMX Page dialog box, change the directory to include the suffix /oracle.phonebook.employees. Deselect Secondary Action, leaving Header and Primary Action selected, as shown in Figure 3. Click OK.


    Figure 3: Modifying EmployeeDetails.amx

The EmployeeDetails.amx page opens in the editor. You’ll modify this page so that it displays details for the selected employee.

  1. In the editor, change the value of amx:outputText from the default Header to Employee.
  2. Click the toolbar’s Save All icon.

Extending the Data Control

In Oracle Mobile Application Framework, data controls are an abstraction wrapped around the datasources you want your application to interact with, such as remote web services. Because most datasources typically have their own APIs and represent hierarchies of elements and attributes, working with all the different interfaces can be challenging. With Oracle Mobile Application Framework, you can instead declaratively configure a data control to interact with all datasources in a standardized manner—a significant design-time productivity boost, because you can build your app around these services based on standard APIs. For example, you can quickly create pages based on the data control’s attributes rather than write a complex Java routine.

In the previous column, your phonebook app used a prebuilt data control for accessing the external web service to extract a list of employees. That data control was built for you with an easy-to-use wizard. Now you’ll use the same wizard to extend the existing data control so that it also extracts details about a selected employee:

  1. Open the Data Controls panel in the Application Navigator, click the blue twin-arrow refresh button, and notice the preexisting HrServiceDataControl with a getEmployees() child operation. This function represents the existing web service call for retrieving the list of employees for the ViewEmployees.amx page.
  2. Right-click the ViewController project in the Application Navigator, and select New -> From Gallery.
  3. In the New Gallery dialog box, select Business Tier -> Data Controls from the Categories list. Click the Web Service Data Control (SOAP/REST) option in the Items section, and click OK.
  4. In the Create Web Service Data Control dialog box, enter HrServiceDataControl in the Name field and select the REST radio button. This selection defaults the REST data control to use the same HrServiceConn REST service connection already defined in the project. Click Next, and then click Yes in the dialog box called Data Control already exists, as shown in Figure 4.


    Figure 4: Step 1 of creating or modifying a REST web service data control
  5. In the Resources wizard page, select /employees Resource Path.

This path represents the REST resource previously configured for accessing all the employees from the remote HR system. On the right side, you can see that this REST resource uses a GET operation that’s exposed with the name getEmployees to the Oracle Mobile Application Framework application (as you saw in the Data Controls panel in step 19). Now you’ll extend the data control so that you can retrieve a single employee from the HR system’s REST services.

  1. In the Resource Paths list, click the green plus button. Double-click the resulting new line, and replace /path1 with /employees/##empId##. This path represents an entirely different REST resource for selecting an individual employee ID by the variable ##empId##.
  2. Select the GET checkbox, and change Method Display Name for GET to getEmployee, as shown in Figure 5. Click Next.


    Figure 5: Step 2 of the Create Web Service Data Control wizard
  3. On the Method Details wizard page, under Resource Methods, select getEmployee.

To work with an external REST resource, Oracle JDeveloper needs a description of the payload schema file. Alternatively, at design time, you can use the Create Web Service Data Control wizard you’re working in now to issue one query with a valid empId, and the wizard will conveniently work out the structure for you.

  1. In the URL Parameters table’s Default value field for empId, enter 174, as shown in Figure 6, and click Next.


    Figure 6: Step 3 of the Create Web Service Data Control wizard
  2. On the final wizard page, click the Test REST Connection button and look for two “REST Connection Successful” messages. Click Finish.
  3. In the Application Navigator, open the Data Controls panel and click the Refresh button. Expand HrServiceDataControl, and notice the two functions: the preexisting getEmployees() function (for retrieving all employees used by the ViewEmployees.amx page) and the new getEmployee(String) function, which fetches a specific employee’s details from the remote web service when given an employee ID. You’ll use this new function on the EmployeeDetails.amx page in a moment.

Extending the ViewEmployees Page

The next step is to determine which employee ID to pass to the getEmployee(String) method. That value is determined by the employee row the user selects on the ViewEmployees page. You need to add code that, when the user selects an individual row, captures that employee ID and then navigates to the EmployeeDetails.amx page.

  1. Return to the employees-task-flow.xml file, and double-click the ViewEmployees page in the diagram editor.
  2. From the Components panel’s Operations section, drag a Set Property Listener into the ViewEmployees.amx page code, after the closing </amx:tableLayout> tag and before the closing </amx:listItem> tag.
  3. With the <amx:setPropertyListener> tag selected, in the Properties panel’s Common section, change the From value to #{row.EmployeeId}, the To value to #{pageFlowScope.empId}, and the Type field to action.

The <setPropertyListener> tag retrieves the current EmployeeId for the selected row and writes it to a dynamic variable empId in a reserved memory scope, called pageFlowScope, for the task flow.

  1. Select the opening <amx:listItem> tag, and in the Properties panel’s Common section, set Action to goEmployeeDetails.

The goEmployeeDetails action represents the control flow case you specified in the task flow between the ViewEmployees and EmployeeDetails pages (in steps 14 and 15). Now, when the user selects a specific employee in the ViewEmployees list view, the employee ID to use on the getEmployee(String) method on the EmployeeDetails page is recorded via the setPropertyListener and the application navigates to that page to show the employee details associated with that ID.

Building the EmployeeDetails Page
  1. Return to the EmployeeDetails page, by double-clicking its icon in the employees-task-flow.xml diagram editor.
  2. Locate the <amx:facet name=”primary”> tag, and select its child <amx:commandButton> button. In the Properties panel, change the commandButton’s Text property to Back and select the __back value from the Action properties list.
  3. In the Application Navigator, expand the Data Controls -> getEmployee(String) -> Return node and drag the child Employee node onto your EmployeeDetails.amx page immediately after the last closing </amx:facet> tag and before the closing </amx:panelPage> tag.
  4. In the Create dialog box, select the Form -> MAF Read-only Form option. In the Edit Form Fields dialog box, delete everything but the EmployeeId, FirstName, LastName, Address, and Department.DepartmentName fields, as shown in Figure 7, and click OK.


    Figure 7: The Edit Form Fields dialog box

(The fields used here are arbitrary; you can pick any fields that are relevant to your needs.) The Edit Action Binding dialog box requests a value for the getEmployee() java.lang.String parameter empId, which, as you recall, is captured via the <setProperty Listener> tag on the ViewEmployees page.

  1. In the Value column, enter the expression language (EL) expression #{pageFlowScope.empId} and click OK.
  2. Select the Bindings tab at the bottom of the EmployeeDetails.amx page. On the Bindings page, select the getEmployeeIterator option from the Executables list. In the Properties panel’s Advanced section, change the Refresh property from deferred to always. This selection ensures that the page will make a fresh call to getEmployees(String) each time this page is visited with a new employee ID—rather than caching the previous results for speed, which would incorrectly show old data.

Adding a Map

Now finish your app by adding a map to the EmployeeDetails.amx page that shows the selected employee’s address:

  1. With the EmployeeDetails.amx page still open, select the Source tab at the bottom. From the Components window, select MAF AMX Data Visualizations from the MAF AMX list. From the Common section’s Map category, drag the Geographic Map component to between the closing </amx:panelFormLayout> tag and the closing </amx:panelPage> tag.
  2. Replace the newly added geographicMap code block with the following code, which displays the employee’s address:
    <dvtm:geographicMap id="geomp1" mapType="ROADMAP">
      <dvtm:pointDataLayer id="pdl1">
        <dvtm:pointLocation id="pl1" type="address"
  3. Now that you’re showing the address on the map, you can remove the address from the text. Locate the <amx:outputText> tag whose value is #{bindings.Address.inputValue}. Delete that outputText component and the surrounding parent <amx:panelLabelAndMessage> opening and closing tags.

Run the App

Deploy the finished app to iOS Simulator 36 if you’re on a Mac or to the Android emulator if you’re on Windows.

  1. Mac users only:
    1. Select Run -> Choose Active Run Configurations -> Manage Run Configurations -> Edit Shared Settings -> iOS Simulator -> Edit -> Mobile Run Configuration, and change the Simulator option to iPhone 5S if it’s not the default option.
    2. Close all the dialog boxes by clicking OK.
    3. In the Application Navigator, right-click the ViewController project and select Run.
  1. Android users only:
    1. In the Application Navigator in Oracle JDeveloper, select Application Resources -> Connections -> REST, right-click the HrServiceConn connection, and select Properties.
    2. In the Edit REST Connection dialog box, replace in the URL Endpoint field with (This value enables the Android emulator to access the web service running on your PC—a change that’s not required for iOS Simulator.)
    3. Select Run -> Choose Active Run Configuration -> Android Emulator.
    4. In the Application Navigator, right-click the ViewController project and select Debug.
  1. After the application starts, select an employee in the list to see that person’s details.

If you encounter any issues, refer to the Oracle Mobile Application Framework installation documentation. You can also search or post to the Oracle Mobile Application Framework forum, at


This column introduced you to some of the productivity boosters available through Oracle Mobile Application Framework, including easy creation of data controls wrapped around remote web services. Data controls abstract away the low-level implementation details and leave you to focus on your mobile app’s content.

Next Steps

 DOWNLOAD the sample application for this article

 READ more about Oracle Mobile Application Framework

 WATCH Oracle Mobile Application Framework YouTube training channel

 JOIN the Oracle Mobile Application Framework Google+ community


Photography by Tatiana Nino, Unsplash