Share information among features in Oracle Mobile Application Framework.

November/December 2014

Oracle Mobile Application Framework is the successor framework to Oracle Application Development Framework Mobile (Oracle ADF Mobile) for building on-device applications for iOS and Android platforms. This article steps you through one way to perform a common developer task in Oracle Mobile Application Framework: sharing information among Application Mobile XML (AMX) features.

A feature in Oracle Mobile Application Framework is a unit of work—a single piece of application functionality that users can access from the mobile application springboard. An example of a feature is a product catalog in which users can query and select items to buy. AMX is one of three technologies that you can use to develop features in Oracle Mobile Application Framework.

Oracle Mobile Application Framework mobile applications can be developed in Oracle JDeveloper with the Oracle Mobile Application Framework extension, or in Eclipse with Oracle Enterprise Pack for Eclipse. In this article’s hands-on exercise, you’ll use Oracle JDeveloper and Oracle Mobile Application Framework to implement a customers feature that shares information about the selected customer with an orders feature.

Figure 1 shows a simplified architecture diagram for Oracle Mobile Application Framework. A mobile application built with Oracle Mobile Application Framework is compiled into a platform-specific container that is then deployed to a mobile device. From the perspective of the device, the container makes the application appear to be written in the device’s native OS language (Objective-C for iOS or Java for Android).

Figure 1: Oracle Mobile Application Framework architecture

Within the native container, Oracle Mobile Application Framework executes HTML5, CSS, and JavaScript to render the mobile UI and client behavior within web view containers. Each web view in Oracle Mobile Application Framework is a feature—a piece of reusable mobile functionality—built by using local HTML5 documents, remote HTML5 documents queried from a remote server, or the Oracle Mobile Application Framework–specific AMX technology.

AMX is a subframework in Oracle Mobile Application Framework that developers can use to build data-bound mobile UIs and page flows visually and declaratively most of the time. To define the mobile UI, you use predefined UI components that execute as HTML5, CSS, and JavaScript at runtime. Page navigation in AMX is visually defined in task flows, a controller that is comparable to the controller in Oracle Application Development Framework (Oracle ADF), and Java ServerFaces. All UI component data access in AMX is achieved through data controls that bind to local datasources such as a SQLite database or remote sources such as web services.

Where Oracle Mobile Application Framework developers don’t use visual and declarative programming in AMX, they use Java—for example, to code the application’s client logic. A lightweight Java Virtual Machine (JVM) is provided within the device-native container. Optionally, data queried from remote web services can then be written to and read from a local SQLite database via the JDBC driver in Oracle Mobile Application Framework to support offline mobile use cases.

A key concept of the AMX controller in Oracle Mobile Application Framework is managed beans. The lifecycle of these Java objects—the instantiation and release of object instances—is handled by the AMX framework.

By design, each feature in Oracle Mobile Application Framework that runs Java runs it in the feature’s own Java class loader to isolate client logic and data from code executed in other features. Features that are developed with local HTML5 or remote HTML pages can also access and execute Java objects by using Oracle Mobile Application Framework JavaScript APIs.

Class-loader isolation adds to the stability of Oracle Mobile Application Framework applications, but it doesn’t allow data objects to be shared implicitly. Yet the following three use cases require AMX features in Oracle Mobile Application Framework to share information:

Global user settings. Enterprise application users use web browsers, smartphones, and tablets interchangeably (a multichannel approach). User preferences can be queried from a remote web service to ensure that user settings are identical across devices and technologies. For Oracle Mobile Application Framework applications, the query should happen only once and then be made available to all AMX features in a mobile application.

Mobile application interaction. Oracle Mobile Application Framework applications that are installed on the same device can call one another and exchange data. This information might need to be accessible to multiple features in an Oracle Mobile Application Framework application.

Feature communication. Features in Oracle Mobile Application Framework not only promote reuse in mobile application development; they also enable the partitioning of mobile application development by application functionality. For example, a storefront mobile application might be implemented in two features: an account-management feature and an order-entry feature that need to exchange data.

In Oracle Mobile Application Framework, developers have two options for sharing information among AMX features:

SQLite database. The SQLite database in Oracle Mobile Application Framework is not restricted to a single feature but can be accessed from anywhere in an Oracle Mobile Application Framework application. Use cases such as global user preferences are best implemented by using the local database so that the preferences are available even without a network connection. A static Java class can be used to provide access to the database to read the shared information. The SQLite database also is the option to choose if non-AMX features also must have access to shared data information.

Managed bean in application scope. If the information sharing is between AMX features and there’s no need for the shared content to survive an application restart, a managed bean configured in application scope can be used. For example, a managed bean could be used to handle the second and third use cases described in the preceding list.

The hands-on exercise in this article steps you through implementation of the managed bean solution for AMX features.

The sample application implements the use case of a customers feature that shares information about the selected customer with an orders feature. The orders feature then displays orders for that customer only. Figure 2 outlines the application architecture.

Figure 2: Sample application architecture

You’ll build two features that both use a bounded task flow as the feature content. Each bounded task flow has a single AMX page to display the UI. Managed beans are used to look up the shared managed bean that is configured in the adfc-mobile.xml configuration of the unbounded task flow in Oracle Mobile Application Framework for read and write access. Because the shared managed bean is configured in application scope, it is visible to both of the managed beans defined in the features. To read information from and write information to the shared managed bean instance, the feature-defined managed beans use expression language (EL) invoked from the AdfmfJavaUtilities Oracle Mobile Application Framework framework class.

Alternatively, the global managed bean could be accessed directly from an AMX page. However, that approach makes the code hard to read and document, and it makes the features difficult to reuse because access to the shared context is widely dispersed. Accessing shared information from managed beans in bounded task flows is a much cleaner approach.

Download the sample application, and unzip the o64maf-2292495.zip file to a local folder on your computer. Do not use spaces in the folder name. 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 extension. You also need either the Android emulator or the iOS simulator, configured for deploying and testing Oracle Mobile Application Framework from Oracle JDeveloper.

The oramag11214 folder contains two subfolders. The Completed folder contains the completed sample application. For the hands-on exercise, you’ll use an Oracle JDeveloper 12.1.3 workspace that’s in the Starter folder:

1. In Oracle JDeveloper, select File -> Open and navigate to the directory containing the unpacked zip file content.
2. Open the oramag11214 -> Starter folder and select the MAFPojoSummit.jws file. Click Open to load the workspace.

The starter workspace contains two AMX features—customers and orders—and a set of Java objects that provide local data records. (Using local data simplifies the exercise by eliminating the need to consider dependencies on remote services.)

When building Oracle Mobile Application Framework AMX features, you have a choice between using a single AMX page or an Oracle Mobile Application Framework task flow to represent the feature content. The starter workspace contains two bounded task flows with a single page each: one for displaying customer data and one for displaying customer orders. Two of the application’s three managed beans are predefined to save you some typing.

AMX supports the exposure of remote and local data to the model layer—the Oracle Mobile Application Framework binding layer—through data controls. You must create two data controls, one for customers and one for orders, so that the application can share data between the two features:

3. Expand the ViewController project of the MAFPojoSummit starter application.
4. Expand the Application Sources folder and its oramag.eleven.twelve.fourteen Java package structure.
5. Expand the data package and then the dc package node.
6. Right-click CustomersDC.java and choose Create Data Control from the menu.
7. Accept the default settings and click Next and then Finish.
8. Repeat steps 6 and 7 for the OrdersDC.java entry.
9. Save your work.
10. Close the DataControls.dcx tab.

What you just did: Oracle Mobile Application Framework supports different types of data controls to expose remote and local data for declarative UI binding and data binding. You configured JavaBean data controls for the customers and orders data.

Recall that one option for sharing data among features is to define a managed bean in a global scope, which in Oracle Mobile Application Framework is the application scope. Managed beans in application scope are accessible throughout an Oracle Mobile Application Framework application.

11. In Oracle JDeveloper, right-click the Application Sources folder and choose New -> Java Class.
12. In the Create Java Class dialog box, provide the following configuration information and accept the default settings for all of the others: Name: GlobalBean
    Package: oramag.eleven.twelve .fourteen.beans
    
13. Click OK to create the Java class.
14. In the Java source editor, which automatically opens for the new Java class, add the following code immediately below the public class GlobalBean { line:

    private Integer sharedCustomerId = 
    new Integer(0);

15. Place the cursor in a row below the Java constructor method, right-click, and choose Generate Accessors.
16. In the Generate Accessors dialog box, select all checkboxes and click OK to create a pair of setter/getter methods for the sharedCustomerId property.
17. Save your work and close the GlobalBean.java tab.
18. Expand the View Controller -> Web Content folder and double-click the adfc-mobile-config.xml file.
19. In the opened (empty) diagrammer, select the Overview tab at the bottom.
20. Select Managed Beans from the menu on the left and then click the green plus icon in the Managed Beans dialog box.
21. Provide the following information in the configuration fields: Name: globalBean
    Class: oramag.eleven.twelve .fourteen.beans.GlobalBean
    Scope: application
    
22. Save your work and close the adfc-mobile-config.xml tab.

What you just did: adfc-mobile-config.xml is the configuration file for the unbounded task flow in AMX. You added a new managed-bean definition with the name globalBean and a reference to the GlobalBean class that you created earlier. The application scope setting ensures that the bean is accessible from EL throughout the application.

The Oracle Mobile Application Framework AMX features are defined as task flows in the starter application. The client logic of the features is saved in managed beans defined in the task flows. The Java classes for the managed beans are predefined for this exercise, so you only need to configure them.

23. Expand the View Controller -> Web Content -> oramag.eleven.twelve.fourteen.Customers node and double-click the CustomersTF.xml file to open the bounded task flow diagram view. Note: The long folder names for task flows (automatically generated by Oracle JDeveloper) associate the task flow’s location with the ID of the Oracle Mobile Application Framework feature in which it is used.
24. Select the Overview tab at the bottom of the diagram editor.
25. Select Managed Beans from the menu on the left and then click the green plus icon in the dialog box.
26. Enter the following information in the configuration fields: Name: customersBean
    Class: oramag.eleven.twelve .fourteen.beans.CustomersBean
    Scope: pageFlow
    
27. Save your work.
28. Repeat steps 23 through 27 for the OrdersTF.xml file, located in the oramag.eleven.twelve.fourteen.Orders folder in the Web Contents folder, providing the following values in the managed bean configuration dialog box: Name: ordersBean
    Class: oramag.eleven.twelve .fourteen.beans.OrdersBean
    Scope: pageFlow

What you just did: You configured two managed beans to hold the client logic used in the bounded task flows. Both managed beans are configured for pageFlow scope, which makes them available throughout the bounded task flow so they can be used to share data between mobile pages.

The Customers page is the mobile view exposed in the Oracle Mobile Application Framework customers feature. It enables users to browse customer names and to select a customer for whom they want to display order details in the orders feature. The page itself is precreated in the starter workspace, so the task left for you is to add its content and the logic to save the selected customer ID in the globally shared managed bean.

29. In Oracle JDeveloper, select the CustomersTF.xml tab (which should still be open) and click the Diagram tab at the bottom.
30. Double-click the Customers view activity in the diagram to switch to the Customers.amx page view in the source editor.
31. Add a blank line above

    </amx:panelPage>.

32. Expand the Data Controls panel in the Applications tab.
33. Click the Refresh icon (the icon with two arrows on it) in the Data Controls panel toolbar to refresh the data control content. Now you can see the CustomersDC and OrdersDC data controls that you created earlier (among others).
34. Expand the CustomersDC data control and drag the customers collection into the blank line that you created in step 31.
35. Choose MAF List View from the menu and click OK in the opened dialog box.
36. In the Edit List View dialog box, select name as the value of the Value Binding field.
37. Set the value of the Divider Attribute selection to name and the Divider Mode field to First Letter.
38. Click OK to create the list view in the customers page.
39. Back in the source editor, click the Bindings tab at the bottom.
40. In the bindings dialog box, select customers in the Bindings section and click the pencil icon in the toolbar to edit the binding configuration.
41. In the Edit Tree Binding dialog box, shuttle the id property from the Available Attributes list to the Display Attributes list. This configuration makes the customer id property value available for access through EL when a customer is selected in the list view. Click OK and then click the Source tab at the bottom of the page.
42. In the page source editor, choose Window -> Components from the Oracle JDeveloper menu to open the Components window.
43. In the Components window, expand the Operations category and drag the Set Property Listener element into the page on top of the <amx:listItem> tag in the source editor.
44. Open the Property Inspector by selecting Window -> Properties from the Oracle JDeveloper menu.
45. Ensure that the amx:setPropertyListener tag is selected, and provide the following configuration information in the Property Inspector: from: #{row.id}
    to: #{pageFlowScope.customersBean .selectedCustomerId}
    type: action

Hint: Instead of typing the EL into the property fields, you can use the EL builder to compose the EL declaratively. To do so, click in a property field and then click the cogwheel icon located to the right of the property fields.

46. Save your work.

What you just did: You created a customer list that saves the id property of the selected customer in the customerBean managed bean that you configured for the CustomersTF task flow. The managed bean holds the client logic for the customers feature. The bean writes the selected customer to the global managed bean (GlobalBean) and refreshes the orders feature at runtime.

The last task is to implement the Orders page that is displayed when the user switches to the orders feature.

47. In Oracle JDeveloper, select the OrdersTF.xml tab (which should still be open) and click the Diagram tab at the bottom.
48. Double-click the Orders view activity in the diagram to switch to the Customers.amx page view in the source editor.
49. Add a blank line above

    </amx:panelPage>. 

50. Expand the Data Controls panel in the Applications panel. Expand the OrdersDC and findOrdersForCustomer(Integer) nodes.
51. Select Order, located in the findOrdersForCustomer(Integer) node, and drag it onto the blank line you created in step 49.
52. Choose MAF Iterator from the menu.
53. In the Edit Action Binding dialog box, double-click the Value field for the custId parameter and add #{pageFlowScope.ordersBean.customerId}. Click OK twice to close all dialog boxes.
54. Select Window -> Structure in the Oracle JDeveloper menu to open the Structure panel.
55. In the Structure panel, expand the Iterator node.
56. Select all iterator child nodes by selecting the first child node, pressing the Shift key, and then clicking the last node.
57. Still holding down the Shift key, right-click and select Surround With from the menu.
58. Select Panel Form Layout and click OK.
59. Save your work.

What you just did: The OrdersDC data control exposes a method that queries orders for a provided customer ID. The method returns a collection that you dropped on the page as an iterator. You wrapped the contents of the iterator in a panel form layout so that the label and values are nicely aligned. The #{pageFlowScope.ordersBean.customerId} expression that you provided as the argument to the custId parameter accesses the managed bean defined in the OrdersTF task flow. The bean then accesses the shared managed bean in application scope to read the selected customer ID.

You are now ready to deploy and run the application. Select Application -> Deploy from the Oracle JDeveloper menu. Choose either the iOS1 or Android1 deployment profile; then choose among deploying to the iOS simulator, the Android emulator, or a physical device. Deployment to a physical device requires a USB connection from the PC to the device. For iOS devices, you must also deploy the application to iTunes and then drag the app to the device from there.

Click the MAFPojoSummit in the simulator or device springboard to start the application. Figure 3 shows the initial sample application screen as it appears on the iOS simulator.

Figure 3: Oracle Mobile Application Framework customers screen

Not all customers have orders in the provided sample data. Click the Beisbol Sil! customer entry. Now you can see the Oracle Mobile Application Framework navigation bar (not shown in Figure 3). Use the navigation bar to switch to the orders feature to see the orders for the selected customer. Switch back to the customers feature by using the navigation bar, and select Baxter Bike. Selecting the orders feature should now show a changed set of orders.

The communication between the AMX page in the task flows and the shared global managed bean is contained in the CustomersBean and OrdersBean Java classes. Because both classes were precreated in the starter workspace, examine the code to understand how the two classes work.

60. In the ViewController project, expand the View Controller -> Application Source node and then expand the oramag.eleven.twelve.fourteen package nodes. In there you find the beans node that hosts the two Java classes.
61. Double-click the CustomersBean.java file to open it in the source code editor.

AdfmfJavaUtilities.setELValue(
        "#{globalBean.sharedCustomerId}",
         selectedCustomerId);

The set method then refreshes the orders feature to ensure that when the user clicks the Orders entry in the navigation bar, the orders for the selected customer are shown. Note that by default features always resume from the state in which they were left. To change this behavior, you must reset the feature:

AdfmfContainerUtilities.resetFeature(
            "oramag.eleven.twelve
             .fourteen.Orders", false);

In this call, the arguments are the feature ID as you find it in the maf-feature.xml file and a Boolean value that determines if the reset should lead to navigation to the orders feature. Setting the Boolean value to false requires manual feature navigation such as using the navigation bar.

The OrdersBean.java class works similarly but only reads from the global managed bean.

The customers-orders example in this article can also be implemented by using a single AMX feature with a bounded task flow. Using two separate features for implementing the use case is more expensive than using task flows, because features stay in memory even if they are not displayed.

Use separate features if

• The dependent functionality is intended for reuse in other Oracle Mobile Application Framework applications or is used standalone.
• You need the dependent view to resume at the page where you left it—for example, navigating to another feature.
• The functionality should be displayed as a separate icon on the mobile springboard and navigation bar.

Use a bounded task flow if

• The dependent functionality always requires the same parent to select a master record and to trigger navigation to the detail view.
• The dependent functionality is not meant to be used standalone or to be reused in other Oracle Mobile Application Framework applications.

Photography by Unsplash