Developing an On-Device Mobile Application Using ADF Mobile Client

Purpose

In this tutorial, you learn how to create an on-device, disconnect-capable mobile application using Oracle JDeveloper. Using the ADF Mobile Client extension, you create an application to be deployed in a mobile environment. Using a BlackBerry simulator, you test run your pages on the device.

Time to Complete

40 minutes

Topics

The tutorial covers the following topics:

	Overview
	Scenario
	Prerequisites
	Create the Mobile Application
	Create the Model Components for the Mobile Application
	Enhance the Model Components
	Create a Page Flow Diagram
	Create a Browse Page for Mobile
	Create an Edit Page for Mobile
	Set the Environment for Running the Mobile Application
	Run the Application on the Mobile Device
	Summary

Viewing Screenshots

Place the cursor over this icon to load and view all the screenshots for this tutorial. (Caution: This action loads all screenshots simultaneously, so response time may be slow depending on your Internet connection.)

Note: Alternatively, you can place the cursor over an individual icon in the following steps to load and view only the screenshot associated with that step. You can hide an individual screenshot by clicking it.

Overview

This tutorial shows you how to create JSF pages for mobile. Using JDeveloper 11g you create mobile page definitions that can be deployed on mobile devices.

Back to Topic List

Scenario

First, you deploy an existing application to serve as a .jar library, which is then used for developing a mobile application. The example illustrates the use of a BlackBerry device.

You use the .jar file as the library reference and upon it, you then develop pages for a mobile device. You create a browse page as Master/Detail and create an Edit page allowing update of the Order information. You also add a List of Values (LOV) for use on a mobile device.

Back to Topic List

Prerequisites

Before starting any section of the tutorial, you should:

Download the Required Components and Start JDeveloper

Install the Server Database Schema

Export the Starter Application as an ADF Library

Back to Topic Lis t

Downloading the Required Components and Start JDeveloper

In the following steps, you download JDeveloper 11g and other files required for this tutorial.

1.	Have access to or have installed Oracle JDeveloper 11g Version 11.1.1.3.0. You can download it from Oracle Technology Network.
2.	Have access to or have installed Oracle Database 11g or 10g Version . For this tutorial, you can use either Oracle Database XE or Enterprise/Standard edition. However, if you intend to set up data synchronization, then you will download the Enterprise/Standard edition of the Oracle Database. You can download it from Oracle Technology Network.
3.	Download the FOD schema zip file from OTN and choose Save Link As... from context to download the FusionOrderDemo_R1PS2.zip file on a local directory of your choice.
4.	Unzip the FusionOrderDemo_R1PS2.zip file on a local directory of your choice (i.e. Temp)
5.	Download and extract Sample Client Database files for BlackBerry sample. The file contains the content of a simulated SD Card, which has a copy of the client SQLite database. This allows you to get started without having to do synchronization with the server database.
6.	Start JDeveloper by selecting Start > All Programs > Oracle Fusion Middleware 11.1.1.3.0 > JDeveloper Studio 11.1.1.3.0 If the Migrate User Settings dialog box opens, click NO. If prompted for a User Role, choose Default. Close the Tip of the Day window.
7.	The JDeveloper IDE should now be displayed.
8.	Install the ADF Mobile Client Extension. Select Help \| Check for Updates to download the ADF Mobile Client extension from the Update Center .
9.	In the Check for Updates wizard, select Next on the Welcome page. Then, selecting the Search Update Centers, and the Official Oracle Extensions and Updates checkbox, click Next.
10.	Look for the ADF Mobile Client extension and select it. Please note the version number may differ from the screen shot below, as new versions of the extensions are released. Click Next.
11.	Accept the Licence Agreement. Then Next and Finish. When prompted, restart JDeveloper.

Back to Topic

Back to Topic Lis t

Installing the Database Schema

In this part, you use a JDeveloper Application to install the schema for your server database and populate the FOD schema with the corresponding data. This is used during the development of the ADF Mobile Client application only, and is not used either on the mobile device nor as part of the data synchronization. However, if data synchronization is configured, you can use this FOD schema to provide data from your server or "Base ADF" application.

Click the Open Application link or from the tool menu, choose File | Open.

Locate the workspace infrastructure.jws where you've unzipped the FusionOrderDemo_R1PS2.zip file. i.e.: d:\Temp\FusionOrderDemo_R1PS2\Infrastructure.

Click Open. If you are prompted to migrate the project, follow the steps of the migration wizard to proceed.

In the Application Navigator, expand the MasterBuildScript | Resources nodes and double-click build.properties to open it in the editor.

Set the appropriate values in the build.properties file (jdeveloper.home, and all the jdbc.* and db.* settings). The relevant settings are:

jdeveloper.home	Location where you have installed JDeveloper, i.e. c:/middleware/jdeveloper
jdbc.urlBase	Base URI for your database, i.e., jdbc:oracle:thin:@localhost
jdbc.port	Port number for your database, i.e. , 1521
jdbc.sid	Database instance name, i.e. orcl
db.adminUser	Database user with admin privileges, i.e., system.
db.demoUser	Name of database user and schema to be created, i.e. , fod
db.demoUser.password	Password for database user to be created, i.e., fusion
db.demoUser.tablespace	Name of the user tablespace, i.e., USERS
db.demoUser.tempTablespace	Name of the temporary tablespace, i.e., TEMP

In the MasterBuildScript project, right click the build.xml file and select Run Ant Target > buildAll from context. .

When prompted enter the database system user password.

Click Continue.

Verify that the log window doesn't report any major error. It should look like this:

Next to the Infrastructure application name, click the down arrow and select Close Application.

Back to Topic

Back to Topic Lis t

Exporting the Starter Application as an ADF Library.

Before you create any component, you must first open the startup application and deploy it as a jar file. To do this, perform the following steps:

1.	From the Application Navigator, click the Open Application link.
2.	Locate the workspace d:\Temp\FusionOrderDemo_R1PS2\StoreFrontModule.jws. Click Open. If you are prompted to migrate the project, click Yes to confirm.
3.	The Application is loaded up in JDeveloper.
4.	We want to extend the FODModule to run locally on a mobile device. So we need to export the ADFBC components from the FODModule as an ADF Library. So let’s create a deployment profile. Right click the StoreFrontService node and select New from context.
5.	In the New Gallery, open the General node and selecting Deployment Profiles, select ADF Library JAR File as the item. Click OK.
6.	In the Create Deployment Profile, type BaseFODADFApplication as the deployment profile name. Click OK.
7.	Click OK and OK again to create the deployment profile.
8.	Click Save All icon on the JDeveloper menu bar, or select File \| Save All from the menu.
9.	Now we need to deploy the application. Right click the StoreFrontService node and select Deploy > BaseFODApplication from context.
10.	In the Deploy dialog, click Next to accept the creation of the JAR file. Click Finish.
11.	Wait for the deployment to proceed.
12.	All the needed components from the mobile application are now created. We can start working on a new application for the Mobile purpose. Close the application.

Back to Topic

Back to Topic Lis t

Creating the Mobile Application

To create the mobile application, perform the following steps:

1.
Click the New Application link.

2.
In the Create Application dialog, type MobileFOD as the Application name oracle as the package name and select Mobile Client Application (ADF) from the Application Template.

Click Next.

3.
Leave the default name for your project (Model). ADF Mobile Client Model is already pre-selected.

Click Next, and Next again.

4.
In the Project 2 Name, leave MobileClient as the default name. ADF Mobile Client UI should already be in the selected pane.

Click Next, then Finish.

5.
Click Save All icon on the JDeveloper menu bar, or select File | Save All from the menu.

6.
The Application Navigator should now look like the following:

Back to Topic List

Creating the Model Components for the Mobile Application

In this section, you are going to import the JAR file to build your Model components. To create the model, perform the following steps:

1.
Right click the Model node and select New from context.

2.
In the New Gallery, click the Current Project Technologies tab. Expand the Business Tier node, and select ADF Mobile Client Business Components from Entity Objects.

Click OK.

3.
In the Create ADF Mobile Client Business Components from ADF Library, click the Browse button next to the ADF Library Path.

4.
Locate the BaseFODApplication.jar file created earlier. It should be into \Temp\FusionOrderDemo\StoreFrontModule\StoreFrontService\deploy\

Click Open.

5.
Back in the Create ADF Mobile Client Business Components from ADF Library dialog, click the Import button. Once the Available pane is populated, shuttle into the Selected pane the followings objects:

PersonEO

ProductBaseEO

OrderEO

OrderItemEO

Click Next.

Before being able to specify the attributes for the selected objects, JDeveloper requires a database connection.

6.
In the Initialize Business Components Project dialog, click the Add button next to the Connection field.

7.
Enter a name for the connection, select the connection type, and enter the username and password. This is a database connection to your server application, and is used during development to develop the ADF Business Components for a ADF Mobile Client application. This is not used by the Mobile Client application on the mobile device, which uses a local client database. To follow along with this example, use:

FOD for the connection name

fod for the username

fusion for the password

specify your database SID

8.
Click Test Connection to confirm that you can connect.

Click OK if the connection was successful to initialize the connection to the database.

9.
Back in the Create Business Components dialog, in the select entity attributes step, select the OrderEO entity object. Notice that some attributes are in the Available pane. The reason is that they are calculated fields and don't have any mapping in the database table definition.

10.
Select the ProductBaseEO entity object and shuttle in the Available pane all attributes having a name starting with 'attribute', also including attributeCategory.

Click Next.

11.
In the Updatable View Objects, shuttle all the available as selected components. Selecting each name, in the Object Name field, remove EO from all the names.

Click Next.

12.
Leave the default application module name.

Click Next. Then Finish.

13.
The Application Navigator should now look like the following:

14.
Click Save All icon on the JDeveloper menu bar, or select File | Save All from the menu.

Back to Topic List

Enhancing the Model Components

In this section, you are going to add attributes to the OrderItem view and create a static list of values. To enhance the model, perform the following steps:

Double click the OrderItemView.xml in the model package of the Application Navigator.

Click the Entity Objects tab and in the Available pane, move ProductBaseEO in the Selected.

Click the Attribute tab, select Add Attribute from entity option from the drop down list next to the Add icon.

From the Attributes list scroll down and from the ProductBaseEO select ProductName and shuttle it in the Selected pane.

Notice that the ProductId attribute has automatically been added too. Click OK.

Click Save All icon on the JDeveloper menu bar, or select File | Save All from the menu.

Right click the Model project in the Application Navigator and select New.

In the New Gallery, select the Business Tier | ADF Mobile Client Business Components and then choose View Object as the item.

Click OK.

In the Create View Object wizard, type StatusCode as the name and check the Rows Populated at design time option.

Click Next.

In the Attributes step, click the New button.

In the New View Object Attribute, type OrderStatus as the Name and check the Key Attribute property.

Click OK.

10.

Back in the Attribute step, click New again to create a second attribute. In the New View Object Attribute, type Description as the Name.

Click OK, then Next.

11.

In the Attribute Settings step, click Next. In the Static List step, click the Add button 7 times to prepare the creation of the needed list of values.

12.

In the LOV values, enter the following values:

OrderStatus	Description
PENDING	Order submitted
SHIP	Order being shipped
PICK	Order being picked
COMPLETE	Order completed
CANCEL	Order cancelled
STOCK	Waiting for stock
CART	Order in cart

Click Next.

13.

Select the Application Module check box and leave the default values.

Click Next then Finish.

14.

In the Application Navigator, double click the OrderView to open it in the editor.

15.

In the Overview tab, click the View Accessors tab and click the Add button.

16.

In the View Accessors dialog, select StatusCode from the Available list and shuttle it in the View Accessors pane.

Click OK.

17.

Click the Attributes tab and select the OrderStatusCode attribute. Scroll down to the List of Values node and click the Add button.

18.

In the Create List of Values dialog, choose StatusCode1 as the List Data Source and OrderStatus as the List Attribute.

19.

Click the UI Hints tab and shuttle Description from Available to Selected. Uncheck the Include “No Selection” Item.

Click OK.

20.

The List of Value is now added to the OrderView definition.

21.

Click Save All icon on the JDeveloper menu bar, or select File | Save All from the menu.

Back to Topic

Back to Topic List

Creating a Page Flow Diagram

To create the page flow for the client project, perform the following steps:

1.	Expand the Mobile Client node and in the Application Sources double click the Mobile-Client-task-flow.xml to open the task flow diagram and define your pages.
2.	From the Component palette, drag and drop the view icon onto the diagram, and name it browse.
3.	Drag and drop a second view next to the browse one and rename it edit.
4.	Select the control flow icon and from the browse page, draw a line up to the edit view. Name it edit.
5.	Draw a second control flow going from edit to browse. Name it browse.
6.	Add a Task Flow Return on the diagram and rename it exit. Task Flow Return in an ADF Mobile Client application represents the activity that terminates the client application.
7.	Add a Wildcard Control Flow on the diagram.
8.	Draw a Control flow Case from the Wildcard Control flow to the Task Flow Return. Name it exit.
9.	Click Save All icon on the JDeveloper menu bar, or select File \| Save All from the menu to save the diagram.

Back to Topic

Back to Topic List

Creating a Browse Page for Mobile

In the following steps, you create the browse page for mobile.

1.	Double click the browse page icon to create the page.
2.	In the Create ADF Mobile Client Page, click OK to accept the file name.
3.	The page opens in the editor with a Preview tab.
4.	Notice the 3 lists at the top of the preview for specifying the Mobile type, the screen size and a Menu option.
5.	Unlike with regular JSP or JSPX pages, you cannot drop any component in the Preview, you can only use the structure pane or the Source tab to construct your page. The Preview displays the corresponding rendering of the page. In the Structure pane, expand View \| Form nodes.
6.	From the Component Palette, In the ADF Mobile Client select the Output Text item and drop it onto the Panel Group Layout.
7.	In the Property Inspector set the following properties: Value Browse fontFamily arial fontSize 16 fontWeight bold
8.	Examine the Preview, and using the drop down list, experiment another device preview.
9.	Return to the BlackBerry preview. Experiment changing the screen resolution. Try other values. Please note that the most common screen resolution for BlackBerry is 480X320.
10.	From the Data Controls pane, expand the AppModuleDataControl \| OrderView1 and drop it onto the PanelGroup Layout. Then select Forms > Read-only Form.
11.	In the Edit Form Fields, delete all attributes except the following ones: OrderId OrderDate OrderShippedDate OrderStatusCode OrderTotal Select the Include Navigation Controls option Click OK.
12.	The Preview should look like the following:
13.	In the Data Controls expand the OrderView1 node and select OrderItemView2 and drop it onto the Panel Group Layout as a Read Only table.
14.	In Edit Table Columns dialog, delete all columns except Quantity, UnitPrice and ProductName. Select the Sorting and Filtering options. Click OK.
15.	In the property Inspector, set the width field for the table to 100%. Set the width field for the Quantity, UnitPrice and ProductName columns to 25%, 25%, and 50%, respectively.
16.	From the Component Palette, select the Button component and drop it onto the second Panel Group Layout so that is is added next to the existing Navigation buttons.
17.	In the Property Inspector, for the text field type Edit and select edit from the action list. This will open the Edit page.
18.	Expand the Menu \| Menu Group \| Menu Item which is the default menu item, and in the Property Inspector, type Exit as the label and select exit in the action list.
19.	The Preview should look like the following:
20.	Click Save All icon on the JDeveloper menu bar, or select File \| Save All from the menu.

Back to Topic

Back to Topic List

Create the Edit Page for Mobile

To create the Edit page, perform the following steps:

1.	Click the MobileClient-task-flow.xml tab to open the diagram.
2.	Double click the edit icon to create the page.
3.	In the Create ADF Mobile Client Page dialog, click OK to accept defaults.
4.	Select the ADF Mobile Client component palette and selecting the OutputText, drop it in the Structure pane onto the Panel Group Layout.
5.	In the Property Inspector set the following properties: Value Edit fontFamily Arial fontSize 16 fontWeight bold
6.	From the Data Controls pane, select OrderView1 and drop it onto the Panel Group Layout, and select Forms > Form from context.
7.	In the Edit Form Fields dialog, change the Component to Use for the OrderId column and change it to Output Text to make the value non updatable. Click OK.
8.	In the Structure Pane, expand the Panel Form Layout node and select the Output Text for the OrderId attribute.
9.	In the Property Inspector, set the focusable property to true to allow user to move the cursor on the ID field to cut and paste the value.
10.	Select a Panel Group Layout from the Component palette and drop it above the Panel Form Layout.
11.	In the Data Controls pane, open the Operations node at the bottom of the navigator and select the Commit to drop onto the Panel Group Layout. Create as a Command Button.
12.	Repeat the operation for the Rollback button.
13.	Select the Commit button and change the following properties: Text : Save Action: browse Disabled: false
14.	Repeat the last step for the Rollback button but set the Text value to Undo
15.	Click the Panel Group Layout in the Structure pane and set the layout property to horizontal, so that way both buttons are next to each other.
16.	Because there is a lot of information to display on the page, select the top Panel Group Layout and set the verticalScroll property to true.
17.	The Preview should look like the following:
18.	At the bottom of the Structure pane, select the Menu \| Menu Group \| Menu Item component and in the Property Inspector, type Exit as the label and using the drop down list, set the action to exit.
19.	Click the Bindings tab in the editor and under the Bindings list, delete OrderStatusCode.
20.	Click the Preview tab and in the Structure pane, select the Input Text for the OrderStatusCode and delete it.
21.	Back in the Data Controls pane expand the OrderView1 node. Drag and drop OrderStatusCode back to its previous place in the page (below OrderTotal) and from context, select Single Selections > Select One Choice.
22.	Click the Bindings tab and selecting OrderStatusCode, move it up underneath OrderTotal.
23.	Click Save All icon on the JDeveloper menu bar, or select File \| Save All from the menu.

Back to Topic List

Setting the Environment for Running the Mobile Application

To create a Deployment profile to deploy the application toward the Mobile simulator, perform the following steps:

1.	Right click the MobileClient node in the Application Navigator and select New from context.
2.	In the New Gallery, select Deployment Profiles from General and choose ADF Mobile Client for BlackBerry. Click OK.
3.	In the Create Deployment profile dialog, enter MOBILEFOD as the deployment profile name. Click OK.
4.	In the ADF Mobile Client for BlackBerry Deployment Profile Properties, select the Application Data Publication node. In a production environment, you’d change the Database Connection field to refer to the Oracle Lite Mobile Server repository database, which is where Oracle Lite Mobile Servers stores all its synchronization rules. For testing, you don't need to. Set the Synchronization Username and the Synchronization Password to the same value SYNCUSER. Set the Device Database Name to MOBILEFOD (uppercase). This database refers to the client database file name, and is part of the client database file downloaded earlier. In the Deployment dialog, click OK.
5.	Now we need to set the location of the BlackBerry tool. From the main Menu, select Tools \| Preferences.
7.	Select the Mobile Client node and click the Browse button next to the BlackBerry JDE directory field. For the BlackBerry JDE locations, specify the place where you installed the software components. Default location is c:\Program Files\Research In Motion\BlackBerry JDE 5.0.0. Notice that selecting the JDE directory populates the simulator directory. Click OK.
8.	Click Save All icon on the JDeveloper menu bar, or select File \| Save All from the menu.
9.	Right click the MobileClient project in the Application Navigator and select Deploy > MOBILEFOD from context.
10.	In the Deploy MOBILEFOD dialog, select Deploy Application to Device. Click Next then Finish.
11.	The application starts being deployed. Wait for the Deployment Finished message in the Log window. This deploys the application to the device simulator.
12.	From main menu, select Tools \| Deploy ADF Mobile Client Runtime > to BlackBerry. This deploys the ADF Mobile Client runtime libraries to the device simulator. Check that no errors are returned in the log window.

Back to Topic List

Running the Application on the Mobile Device

To download and run the application on the mobile device, perform the following steps:

1.	Open the windows explorer and locate the BlackBerry JDE 5.0.0 folder. Open the Simulator folder and notice the files with the cod extension. These files are Blackberry specific types and are generated by the deployment action.
2.	Double click the 9700.bat file to start the simulator.
3.	Please wait until the simulator start up is complete.
4.	You may need to reduce the size of the device display. Select View \| Zoom and pick a value.
5.	Once totally loaded up click on the Simulate \| Change SD Card of the Simulator.
6.	In the SD Card dialog, click the Add Directory button.
7.	Refer to the location where you unzipped the BlackBerrySDCard file. Click OK.
8.	You're now ready to upload the application.
9.	Select the Download folder icon in the BlackBerry Simulator (use the arrow keys on your keyboard) and click the OK (Enter) button on the mobile simulator. If you do not see the folder, click the menu button to bring up complete list of icons.
10.	First check to see you can see at least two icons in the Download folder. One is titled Oracle Mobile Sync Client, and the other titled MOBILEFOD. If Oracle Mobile Sync Client is missing, click File \| Load Java Program, and select osync_rim.cod file in the simulator directory, then click Open to load the program. Repeat for mSync.cod file. You should now see both icons. Lastly, click on the MOBILEFOD icon to start the ADF Mobile Client application you have just created..
11.	The application is loading up.
12.	You can see the Browse page with MasterDetail information.
13.	Try the navigation buttons to browse through records.
14.	Select the Edit button to display the Edit page for the corresponding Order.
15.	The Edit page displays showing details of the order.
16.	Move to the OrderStatusCode field to popup the list of values. Select a different value from the list. Move to the Save button to validate the change.
17.	Back in the Browse page, the new Status appears.
18.	You can close the simulator window and JDeveloper. You've successfully completed this OBE.

Back to Topic List

Summary

In this tutorial, you've seen how to create ADF Rich Client JSF Pages for a mobile and use some advanced features like:

	Creating the Mobile Application
	Creating the Model Components for the Mobile Application
	Enhancing the Model Components
	Creating a Page Flow
	Creating a Browse Page
	Creating the Edit Page
	Setting the Environment for Running the Application
	Running the Application on the Mobile Device

Back to Topic List

	Download the Required Components and Start JDeveloper
	Install the Server Database Schema
	Export the Starter Application as an ADF Library

1.	Click the New Application link.
2.	In the Create Application dialog, type MobileFOD as the Application name oracle as the package name and select Mobile Client Application (ADF) from the Application Template. Click Next.
3.	Leave the default name for your project (Model). ADF Mobile Client Model is already pre-selected. Click Next, and Next again.
4.	In the Project 2 Name, leave MobileClient as the default name. ADF Mobile Client UI should already be in the selected pane. Click Next, then Finish.
5.	Click Save All icon on the JDeveloper menu bar, or select File \| Save All from the menu.
6.	The Application Navigator should now look like the following:

1.	Right click the Model node and select New from context.
2.	In the New Gallery, click the Current Project Technologies tab. Expand the Business Tier node, and select ADF Mobile Client Business Components from Entity Objects. Click OK.
3.	In the Create ADF Mobile Client Business Components from ADF Library, click the Browse button next to the ADF Library Path.
4.	Locate the BaseFODApplication.jar file created earlier. It should be into \Temp\FusionOrderDemo\StoreFrontModule\StoreFrontService\deploy\ Click Open.
5.	Back in the Create ADF Mobile Client Business Components from ADF Library dialog, click the Import button. Once the Available pane is populated, shuttle into the Selected pane the followings objects: PersonEO ProductBaseEO OrderEO OrderItemEO Click Next. Before being able to specify the attributes for the selected objects, JDeveloper requires a database connection.
6.	In the Initialize Business Components Project dialog, click the Add button next to the Connection field.
7.	Enter a name for the connection, select the connection type, and enter the username and password. This is a database connection to your server application, and is used during development to develop the ADF Business Components for a ADF Mobile Client application. This is not used by the Mobile Client application on the mobile device, which uses a local client database. To follow along with this example, use: FOD for the connection name fod for the username fusion for the password specify your database SID
8.	Click Test Connection to confirm that you can connect. Click OK if the connection was successful to initialize the connection to the database.
9.	Back in the Create Business Components dialog, in the select entity attributes step, select the OrderEO entity object. Notice that some attributes are in the Available pane. The reason is that they are calculated fields and don't have any mapping in the database table definition.
10.	Select the ProductBaseEO entity object and shuttle in the Available pane all attributes having a name starting with 'attribute', also including attributeCategory. Click Next.
11.	In the Updatable View Objects, shuttle all the available as selected components. Selecting each name, in the Object Name field, remove EO from all the names. Click Next.
12.	Leave the default application module name. Click Next. Then Finish.
13.	The Application Navigator should now look like the following:
14.	Click Save All icon on the JDeveloper menu bar, or select File \| Save All from the menu.