Subscribe

Share

Mobile

Get Mobile and Connected

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

By Chris Muir

May/June 2015

Oracle introduced Oracle Mobile Application Framework in early 2014, with the goal of making the mobile development experience as simple as possible. As you start creating applications for enterprise users with Oracle Mobile Application Framework, small development projects can help you quickly build up your skills while supplying immediate value to those users.

For example, mobile workers might need to contact a fellow employee urgently when traveling but not have that colleague’s information on their smartphone’s contact list. In this column’s hands-on exercise, you’ll solve that problem by using the Oracle Mobile Application Framework extension in Oracle JDeveloper to build a corporate phone book app for users of iOS or Android devices. The app taps into an existing HR employee web service to retrieve employee contact data and populate the phone book.

With the basic skills and Oracle Mobile Application Framework features you learn from this exercise, you’ll be well equipped to start building more-sophisticated apps that can help on-the-go workers be more productive.


Getting Started

Ensure that you’re using the studio edition of Oracle JDeveloper 12c (12.1.3)—available as a free download on Oracle Technology Network—with the Oracle Mobile Application Framework v2.1 extension. You also need either Apple Xcode 6.1 or the Google Android SDK with API 21, configured for deploying and testing Oracle Mobile Application Framework from Oracle JDeveloper. Apple Xcode is available for Macs only; the Android SDK is available for both Mac and Windows PCs. The Oracle Mobile Application Framework documentation provides relevant setup instructions at bit.ly/mafinst.

Download the sample application at bit.ly/omagmaf1, and save the o35maf-2432441.zip file to a local folder on your computer. (Do not use spaces in the folder name.) Unzip the o35maf-2432441.zip file, and then unzip each of the two extracted files. The local folder now contains two subfolders, each containing an Oracle JDeveloper workspace:

  • The HrServicesSubset folder contains a demonstration REST HR web service that you’ll run on your PC. (For a real-world application, the web service would be deployed from your corporate infrastructure, not on your local PC, and would be reachable behind the company firewall.) The web service will provide the employee data for your mobile phone book application to retrieve.
  • The PhonebookStarterApp folder contains a prebuilt Oracle Mobile Application Framework application workspace that is partially configured to save you time. Items such as the application name, icons, and a hook to the web service—a data control—are prebuilt for you.

Data controls are a major productivity booster for developers that you’ll learn about in detail in a future column.

  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 open 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 -> oracle.hr.rest, right-click the RestService.java 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.
  6. When the service is up and running, you should see a message like the following in your Oracle JDeveloper log window:
    Target URL -- http://127.0.0.1:7101/HrRestServices/

    Copy the target URL into your browser, and add the /employees suffix:

    http://127.0.0.1:7101/HrRestServices/employees

The page should return a payload of employee data, proving that your web service works as expected.

Next, ensure that your environment is set up correctly for mobile development:

  1. In Oracle JDeveloper, switch to the Phonebook workspace.
  2. For iOS development only

    a. 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.
    b. Close all the dialog boxes by clicking OK.
    c. In the Application Navigator, expand ViewController project -> Web Content -> oracle.phonebook.employees, right-click the ViewEmployees.amx page, and select Run.

The app is now deployed to the iOS Simulator, where it has a heading of Employees and a message that makes it clear that you still have work to do, as shown in Figure 1.
o35maf-f1



Figure 1: ViewEmployees.amx page and the initial state of the phone book app in the iOS Simulator

  1. For Android development only:

    a. Set up and start the Android emulator, by following the instructions in the Oracle Mobile Application Framework documentation, at docs.oracle.com/middleware/maf210/mobile/install/mafig_setup.htm#MAFIG164.
    b. Select Run -> Choose Active Run Configuration -> Android Emulator.
    c. In the Application Navigator, expand ViewController project -> Web Content -> oracle.phonebook.employees, right-click the ViewEmployees.amx page, and select Debug.
    d. Start the app, and look for the Employees blank page.
    e. In the Application Navigator in Oracle JDeveloper, select Application Resources -> Connections -> REST, right-click the HrServiceConn connection, and select Properties.
    f. In the Edit REST Connection dialog box, replace 127.0.0.1 in the URL Endpoint field with 10.0.2.2. (This value enables the Android emulator to access the web service running on your PC—a change that isn’t required for the iOS Simulator.)

If you encounter any issues, again refer to the Oracle Mobile Application Framework installation documentation. You can also search or post to the Oracle Mobile Application Framework forum, at community.oracle.com/community/oracle-mobile/oraclemaf.


Building the Phone Book App

The app’s Employees page is where you’ll build a vertical list of employee names and contact details derived from the external HR web service:

  1. If the Employees page isn’t open already, reopen it, by first expanding the ViewController -> Web Content -> oracle.phonebook.employees nodes.
  2. Double-click the ViewEmployees.amx file, which contains the source code for the Employees page, to open its editor.

Each AMX file is a page (or a view) in your Oracle Mobile Application Framework application, made up of UI components represented by XML tags at design time. At the moment, the Employees page is made up of a parent-level amx:view tag and then an amx:panelPage tag with an amx:facet header (a named placeholder of the panelPage tag) displaying the “Employees” text as an amx:outputText tag. (Note that the tag names themselves describe the behavior of each component fairly well to help flatten the developer learning curve.)

To meet the requirement to display employee data in the app, you could take a code-centric approach by working in the editor—adding XML tags to represent the list of employee details—and then somehow wire the components to the external web service. But Oracle Mobile Application Framework data controls give you a quicker way to construct pages based on data, whether the data is from an external datasource such as a web service, plain old Java objects (POJOs), or other datasources:

  1. On the ViewEmployees.amx page, delete the amx:outputText tag with the value This page intentionally left blank.
  2. In the Application Navigator, expand the Data Controls panel and then HrServiceDataControl.
  3. Note the getEmployees() method, which represents the external HR REST web service. Expand the method to see the Return object and then the employees resource. Expand employees to see that the method returns individual Employee objects, as shown in Figure 2.

    o35maf-f2
    Figure 2: Drilling down into a data control
  4. Drag the Employee object into the ViewEmployees.amx source code, dropping the object immediately after the closing </amx:facet> tag and before the closing </amx:panelPage> tag. The resulting menu—a good indicator of the productivity boost that data controls provide—lists all UI layouts and components to which you can wire the web service datasource.
  5. Select MAF List View to open the ListView Gallery, shown in Figure 3, where you can choose among several predefined list layouts. Leave the default Simple option selected in the List Formats section. In the Variations section, select the second option from the left, in which the list items are grouped by dividers. Click OK to open the Edit List View dialog box.

    o35maf-f3
    Figure 3: ListView Gallery selections
  6. The Edit List View dialog box determines which data to show in the list and configures the dividers. For the first (and only) element under List Item Content, change Value Binding from EmployeeId to LastName. Then change Divider Attribute from EmployeeId to LastName, and set Divider Mode to First Letter. These selections cause employees to be displayed alphabetically by last name.
  7. Click OK, and then select File -> Save All.

Note the new XML tags added to your page, including amx:listView, amx:listItem, and amx:outputText, representing the list of employee last names to display. Each tag has its own properties representing what the tag should do at runtime. Among the properties, you can see code such as

#{bindings.Employee.collectionModel} 

This is an expression that binds back to the web service data control that was created for you in the initial application. Data controls and the expression language eliminate the need for you to wire up the components to the data yourself, helping you avoid having to write repetitive, error-prone boilerplate code.

You’re now ready to rerun the app to see the results in the iOS Simulator or the Android emulator:

  1. For iOS, right-click the ViewEmployees.amx page and select Run. For Android, right-click the ViewEmployees.amx page and select Debug.
  2. Note the employee names, the alphabetical dividers, and the alphabetical selectors down the right side. Try flicking the list up and down to watch how the list view works at runtime, including how the index on the right builds itself as more rows are fetched and displayed.

Adding First Names

Your app now contains a list of employees fetched from the remote web service, but because it displays only last names, employees with the same surname are indistinguishable from one another.

Modify the list to include the employees’ first names, too:

  1. With the ViewEmployees.amx page open, select the Bindings tab at the bottom of the editor. The bindings page reveals the app’s plumbing—the bindings that connect the UI components with the data objects read from the web service. Note the getEmployees() method you used earlier and the Employee object that was returned as a result.
  2. Select the Employee object and then the pencil icon to open the Edit Tree Binding dialog box. At the bottom of the dialog box are the attributes of the Employee object that are available for your page to use. Currently only LastName is on the Displayed Attributes list. Shuttle FirstName, Email, PhoneNumber, and ImageBase64 from the Available Attributes list to the Displayed Attributes list, in any order. Click OK.
  3. Return to the editor, and select the Source tab at the bottom.

In the code, note that the amx:outputText component has the value property whose value is the #{row.LastName} expression. Looking at the parent amx:listView and its value property, note that, via the expression, listView works with a collection of employees, stamping out its child tags for every element in the employees collection—in this case, the amx:outputText component. You can think of the listView components as a UI “for loop.” To reference each element, amx:listView defines var="row"—which you see is used in the amx:outputText value for the current row.

  1. Change the expression for the value property to
    value="#{row.FirstName + 
    ' ' + row.LastName}"
  2. Save all your changes, and run your app again—remembering to select Run for iOS and Debug for Android—to check the changes.

Putting Faces to the Names

Remember that a few steps back, in the Bindings tab of the ViewEmployees.amx page, one of the attributes from the web service you added was ImageBase64. In the external web service, this Base64-encoded string contains an image of each employee. Because you’ve already made this attribute available to the page, it’s trivial to add an image component to the app:

  1. On the ViewEmployees.amx page, change the amx:listItem tag so that it now also includes an amx:image tag, as shown in Listing 1.


    Code Listing 1:
    amx:image tag added to amx:listItem

    <amx:listItem id="li1"><amx:image id="im1" styleClass="Avatar"
    source="data:image/png;base64,#{row.ImageBase64}"/>
    <amx:outputText id="ot2"
    value="#{row.FirstName + ' ' + row.LastName}" id="ot2"/>
    </amx:listItem>
  2. Save everything and then run your app (Run for iOS, Debug for Android). Now you can see the (mostly) smiling faces of your colleagues.

“You Never Write, You Never Call”

A phone book application on a mobile device isn’t of much use unless its users can call or send e-mail to contacts through the app. So now you’ll add buttons to invoke the device’s native phone and e-mail apps via the phone book.

  1. Along with the ImageBase64 attribute, you also made the PhoneNumber and Email attributes of the remote web service available to the page. To hook them into the page, add the two amx:goLink tags as children to the amx:listItem tag after the amx:outputText component, as shown in Listing 2.


    Code Listing 2:
    amx:goLink tags added to amx:listItem

    <amx:listItem id="li1">
    <amx:image id="im1"
    source="data:image/png;base64,#{row.ImageBase64}"/>
    <amx:outputText id="ot2"
    value="#{row.FirstName + ' ' + row.LastName}" id="ot2"/><amx:goLink id="gl1" url="tel:#{row.PhoneNumber}"><amx:image id="im2" styleClass="Icons"source="/images/phone.png" /></amx:goLink><amx:goLink id="gl2" url="mailto:#{row.Email}"><amx:image id="im3" styleClass="Icons"source="/images/email.png" /></amx:goLink>
    </amx:listItem>

Note that the amx:goLink components use a URL with the tel: and mailto: prefixes. On mobile devices, these URL schemes enable one application to call another and pass values for the other app to use. In this case, you invoke the phone and mail apps on your mobile device, passing in the phone number and e-mail address, respectively. (Your apps can use the same mechanism to call other apps, such as Twitter or LinkedIn, with their respective URL schemes.)

Now make a few final changes to the layout so that all the information for each employee is on a single line in the phone book, as shown in Figure 4.
o35maf-f4

Figure 4: Employee phone book app layout

  1. Add amx:tableLayout, amx:rowLayout, and amx:cellFormat tags, as shown in Listing 3.


    Code Listing 3:
    Three tags added to amx:listItem

    <amx:listItem id="li1"><amx:tableLayout id="tl" width="100%">;<amx:rowLayout id="rl1"><amx:cellFormat id="cf1" width="20%"
    halign="start" valign="middle">;
    <amx:image id="im1" styleClass="Avatar"
    source="data:image/png;base64,#{row.ImageBase64}"/></amx:cellFormat><amx:cellFormat id="cf2" width="55%"
    halign="start" valign="middle">;
    <amx:outputText id="ot2"
    value="#{row.FirstName + ' ' + row.LastName}" /></amx:cellFormat>;<amx:cellFormat id="cf3" width="12%"
    halign="start" valign="middle">
    <amx:goLink id="gl1" url="tel:#{row.PhoneNumber}">
    <amx:image id="im2" styleClass="Icons"
    source="/images/phone.png"/>
    </amx:goLink></amx:cellFormat><amx:cellFormat id="cf4" width="12%" halign="end" valign="middle">
    <amx:goLink id="gl2" url="mailto:#{row.Email}">
    <amx:image id="im3" styleClass="Icons"
    source="/images/email.png"/>
    </amx:goLink></amx:cellFormat></amx:rowLayout></amx:tableLayout>
    </amx:listItem>
  2. Run (use Debug for Android) your app one more time, and view the results.
  3. If you’re using the Android emulator, select one of the contacts and then the phone or mail icon for that contact to see the results. (The iOS Simulator doesn’t emulate invoking either the phone or e-mail app from your Mac.)

In the Android emulator, the phone and e-mail apps open with the preseeded contact details. (Ensure that you’ve set up an e-mail account on the e-mail app beforehand, so that the e-mail app doesn’t fail with a nonaccount error.)


Conclusion

This column introduced you to some of the basic concepts and features in Oracle Mobile Application Framework: AMX pages, web service consumption through data controls, arranging components on a page, and more. You are now on the path to building mobile applications to help others do their everyday jobs without being tied to their desks.

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 William Iven, Unsplash