Skip Headers
Oracle® Fusion Middleware Mobile Developer's Guide for Oracle Application Development Framework
11g Release 2 (11.1.2.4.0)

Part Number E24475-03
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

3 Setting Up the ADF Mobile Environment

This chapter provides information on setting up the ADF Mobile environment for application development and deployment.

This chapter includes the following sections:

3.1 Introduction to the ADF Mobile Environment

Before developing an ADF Mobile application, you must set up your development environment by downloading, installing, and configuring various software components.

To set up your development environment, follow steps described in Section 3.2, "Prerequisites for Developing ADF Mobile Applications", and then prepare a mobile device or its simulator.

3.2 Prerequisites for Developing ADF Mobile Applications

Prerequisites for developing an ADF Mobile application vary depending on the type of work you are planning to do, as well as your target platform:

3.2.1 What You Need to Create an Application

Before you start creating an ADF Mobile application for iOS, ensure that you have the following available:

For more information, see Section 3.4, "Setting Up Development Tools for iOS Platform."

If Android is your target platform, the following is required:

For more information, see Section 3.5, "Setting Up Development Tools for Android Platform."

You do not need to install any additional tools for creating specific types of ADF Mobile application content (HTML, remote URL,or ADF Mobile AMX). For more information, see Section 5.10, "Defining the Content Types for an Application Feature."

Note:

Since PhoneGap was absorbed by Apache Cordova, if you have any PhoneGap plug-ins installed, you need to perform the migration to Cordova 2.2 versions of those plug-ins.

3.2.2 What You Need to Deploy an Application to a Development Environment

Before you deploy your ADF Mobile application (see Chapter 4, "Getting Started with ADF Mobile Application Development"), ensure that you have the following available:

3.3 Setting Up JDeveloper

Oracle JDeveloper and its ADF Mobile extension are essential tools used in developing ADF Mobile applications.

Before you begin:

Consult the Certification and Support Matrix for Oracle JDeveloper and ADF to find out which release of Oracle JDeveloper is compatible with software listed in Section 3.2.1, "What You Need to Create an Application" for your target platform.

Download and install the appropriate release of Oracle JDeveloper. Select the Studio Developer (All Features) role when prompted.

For more information, see the following:

To download and install the ADF Mobile extension:

  1. In JDeveloper, choose Help, then Check for Updates, and then click Next.

    Note:

    You might need to configure proxy settings by selecting Tools > Preferences from the main menu, and then Web Browser and Proxy from the tree on the left of the Preferences dialog.

  2. In the Source page that Figure 3-1 shows, select Official Oracle Extensions and Updates under the Search Update Centers, and then click Next.

    Figure 3-1 Checking for Updates in JDeveloper

    Check for updates dialog

    Alternatively, if the network access is not available, you can select the Install From Local File option. In this case, you need to point to the ADF Mobile extension file that you already downloaded to a directory on your development computer.

  3. In the Updates dialog, select the ADF Mobile update.

  4. In the License Agreements page, shown in Figure 3-2, review The Oracle Technology Network License Terms for Oracle Mobile.

    Note:

    You must comply with all of the license terms and conditions with respect to the Oracle ADF Mobile Program available at http://www.oracle.com/technetwork/indexes/downloads/index.html.

  5. Click I Agree.

    Figure 3-2 Licensing Agreements for the Oracle ADF Mobile Program

    Agree and comply with the Mobile Program licensing.
  6. Click Next, and then click Finish.

  7. Restart JDeveloper.

  8. Check whether or not ADF Mobile was successfully added to JDeveloper:

    • Select File > New from the main menu to open the New Gallery.

    • Select the All Features tab.

    • In the Categories pane, expand the Client Tier node and make sure it contains ADF Mobile (see Figure 3-3).

    Figure 3-3 Verifying ADF Mobile Installation

    Verifying ADF Mobile Installation

    In addition, verify that you installed the correct version of ADF Mobile. To do so, select Help > About from the main menu, then select the Extensions tab on the About Oracle JDeveloper dialog, and then examine the extension list entries by scrolling down to ADF Mobile, as Figure 3-4 shows.

    Figure 3-4 Verifying ADF Mobile Version

    Check extension

In addition to the preceding steps, your development environment must be configured for target platforms and form factors. For more information, see Section 3.3.1, "How to Configure the Development Environment for Platforms and Form Factors"

3.3.1 How to Configure the Development Environment for Platforms and Form Factors

Before you start developing an ADF Mobile application, you must configure JDeveloper Preferences for appropriate platforms (see Section 3.3.1.2, "Configuring the Environment for Target Platforms") and form factors (see Section 3.3.1.1, "Configuring the Environment for Form Factors").

3.3.1.1 Configuring the Environment for Form Factors

A form factor is a specific device configuration. Each form factor is identified by a name that you specify for it and contains information on the specified resolution denoted by pixel width and pixel height.

Form factors defined in preferences are used in the ADF Mobile AMX page Preview tab (see Section 6.3.2.2, "Using the Preview"). You can select or switch between various form factors to see how an ADF Mobile AMX page is rendered in various form factors. You can also see multiple form factors applied to the same page using the split screen view.

For more information, see Section 5.12.1, "About the adfmf-config.xml File."

Before you begin:

Download and install JDeveloper and the ADF Mobile extension, as described in Section 3.3, "Setting Up JDeveloper."

To configure the form factors:

  1. Open Preferences by selecting Tools > Preferences from the main menu in JDeveloper.

  2. In the Preferences dialog that Figure 3-5 shows, select ADF Mobile from the tree on the left.

    Figure 3-5 Defining Form Factors

    Setting JDeveloper preferences

    The ADF Mobile page is populated with default settings.

    This preference page allows you to create and manage a set of named form factors that combine a screen resolution size and platform.

  3. To create a new form factor, click New, and then set the following:

    • Name: a meaningful string that is used to identify the form factor.

    • Platform: the platform of the mobile device.

    • Model: the type of the mobile device.

    • Default Orientation: the default device orientation used in the ADF Mobile AMX page Preview tab. It might be Portrait or Landscape. Select this setting from the drop-down list of values. The default value is Portrait and it is prepopulated during creation of the new form factor.

    • Resolution Width: width, in pixels. This value must be a positive integer, and its input is validated.

    • Resolution Height: height, in pixels. This value must be a positive integer, and its input is validated.

    • Scale Factor: the display scale factor. This value must be either one of 1.0, 2.0, or 3.0.

    Note:

    If you do not set the name and resolution for your form, ADF Mobile will display an error message.

  4. If you need to revert to default settings, click More Actions > Restore Defaults.

  5. Click OK to finalize your settings.

3.3.1.2 Configuring the Environment for Target Platforms

To start developing for one of the platforms supported by ADF Mobile, you need to provide JDeveloper with such information as the name of the platform and directories on your development computer that are to house the platform-specific tools and data.

Before you begin:

Download and install JDeveloper and the ADF Mobile extension, as described in Section 3.3, "Setting Up JDeveloper."

To configure your development environment for the target platforms:

  1. Select Tools > Preferences from JDeveloper's main menu to open Preferences.

  2. In the Preferences dialog that Figure 3-5 shows, select ADF Mobile from the tree. The ADF Mobile page that opens is populated with default form factor settings.

  3. Select Platforms from the tree to open the ADF Mobile: Platforms page that contains the path and configuration parameters for the supported platforms, as Figure 3-6 and Figure 3-7 show.

    Each platform-specific page hosts the preferences for the platform SDK (Android or iOS), collecting any necessary information such as the path that ADF Mobile needs to compile and deploy either Android or iOS projects:

    • If you select Android from the list of supported platforms, specify the Android SDK location on your computer, the local directory of your target Android platform, and provide information on the signing credentials (see Figure 3-6).

      Figure 3-6 Configuring Platform Preferences for Android

      Configuring Platform Preferences for Android
    • If you select iOS from the list of supported platforms (see Figure 3-7), specify the following:

      Figure 3-7 Configuring Platform Preferences for iOS

      Configuring Platform Preferences for iOS

3.4 Setting Up Development Tools for iOS Platform

In addition to general-purpose tools listed in Section 3.2, "Prerequisites for Developing ADF Mobile Applications," you might want to set up an iPhone or iPad when getting ready for development of an ADF Mobile application for the iOS platform (see Section 3.4.3, "How to Set Up an iPhone or iPad").

Since iPhone and iPad simulators are included in the iOS SDK installation, you do not need to separately install them. For more information, see Section 3.4.4, "How to Set Up an iPhone or iPad Simulator."

3.4.1 How to Install Xcode

You download Xcode from http://developer.apple.com/xcode/.

After installing Xcode, you have to run it at least once and complete the Apple licensing and setup dialogs. If these steps are not performed, any build and deploy cycle from JDeveloper to Xcode or device simulator will fail with a "Return code 69" error.

Note:

Since older versions of Xcode are not available from the Mac App Store, in order to download them you must obtain an Apple ID from http://appleid.apple.com, and then register this Apple ID with the Apple Developer Program to gain access to the Apple developer site at http://developer.apple.com.

3.4.2 How to Install iOS SDK

You download iOS SDK from the iOS Dev Center at http://developer.apple.com/devcenter/ios/.

Note:

Since older versions of iOS SDK are not available from the Mac App Store, in order to download them you must obtain an Apple ID from http://appleid.apple.com, and then register this Apple ID with the Apple Developer Program to gain access to the Apple developer site at http://developer.apple.com.

3.4.3 How to Set Up an iPhone or iPad

In your ADF Mobile application development and deployment, you can use either the iPhone, iPad, or their simulators (see Section 3.4.4, "How to Set Up an iPhone or iPad Simulator"). If you are planning to use an actual iPhone or iPad, which is preferable for testing (see Section 19.2, "Testing ADF Mobile Applications"), you need to connect it to your computer to establish a link between the two devices.

To deploy to an iOS-powered device, you need to have an iOS-powered device with a valid license, certificates, and distribution profiles. For more information, see Chapter 17, "Deploying ADF Mobile Applications."

Note:

Since Apple's licensing terms and conditions may change, ensure that you understand them, comply with them, and stay up to date with any changes.

3.4.4 How to Set Up an iPhone or iPad Simulator

In your ADF Mobile application development and deployment, you can use either the iOS-powered device itself (see Section 3.4.3, "How to Set Up an iPhone or iPad") or its simulator. Deploying to a simulator is usually much faster than deploying to a device, and it also means that you do not have to sign the application first.

A simulator can be invoked automatically, without any additional setup.

Note:

Before attempting to deploy your application from JDeveloper to a device simulator, you must first run the simulator.

If you are planning to use web services in your application and you are behind a corporate firewall, you might need to configure the external network access. You do so by modifying the network settings in the System Preferences on your development computer. For more information, see the "Setting Browser Proxy Information" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

3.5 Setting Up Development Tools for Android Platform

In addition to the general-purpose tools listed in Section 3.2, "Prerequisites for Developing ADF Mobile Applications," you might want to set up an Android-powered device when getting ready for development of an ADF Mobile application for the Android platform (see Section 3.5.2, "How to Set Up an Android-Powered Device").

Since emulators are included in the Android SDK installation, you do not need to separately install them. However, you cannot use an emulator until you create its configuration. For more information, see Section 3.5.3, "How to Set Up an Android Emulator."

To develop for the Android platform, you can use any operating system that is supported by both JDeveloper and Android.

For more information, see the "Developer Tools" section of the Android Developers website at http://developer.android.com/tools/index.html.

3.5.1 How to Install the Android SDK

Android SDK includes development tools that you need to build applications for Android-powered devices. Since the Android SDK is modular, it allows you to download components separately depending on your target Android platform and your application requirements.

When choosing the platform, keep in mind that ADF Mobile supports Android 2.3 or later.

Before you begin:

Ensure that your environment meets the operating system, JDK version, and hardware requirements listed in the "Get the Android SDK" section of the Android Developers website at http://developer.android.com/sdk/index.html.

Note:

Ant, Eclipse, and Linux requirements are not applicable to the ADF Mobile development environment.

To install the Android SDK:

  1. Download the Android SDK starter package from http://developer.android.com/sdk/index.html.

  2. Complete the installation by following the instructions provided in the "Setting Up an Existing IDE" section of the Android Developers website at http://developer.android.com/sdk/installing.html. Skip step 3 in the Android SDK installation instructions, as configuring Eclipse is not required for the ADF Mobile application development.

3.5.2 How to Set Up an Android-Powered Device

In your ADF Mobile application development and deployment, you can use either the Android device itself, which is preferable for testing (see Section 19.2, "Testing ADF Mobile Applications"), or an emulator (see Section 3.5.3, "How to Set Up an Android Emulator").

For information on how to set up the Android-powered device, follow the instructions from the "Using Hardware Devices" section of the Android Developers website at http://developer.android.com/tools/device.html.

Note:

You might experience issues when using USB connectivity for the device-based debugging. For more information, see Section 19, "Testing and Debugging ADF Mobile Applications."

Your target Android-powered device might not be listed in the USB device driver's.inf file, resulting in the failure to install the Android Debug Bridge (ADB). You can eliminate this issue as follows:

  1. Find the correct values for your device.

  2. Update the [Google.NXx86] and [Google.NTamd64] sections of the android_winusb.inf file.

For more information, see the "Google USB Driver" section of the Android Developers website at http://developer.android.com/sdk/win-usb.html.

3.5.3 How to Set Up an Android Emulator

In your ADF Mobile application development and deployment, you can use either the Android device itself (see Section 3.5.2, "How to Set Up an Android-Powered Device") or its emulator. Deploying to an emulator is usually much faster than deploying to a device, and it also means that you do not have to sign the application first.

For information on how to create an emulator configuration called Android Virtual Device (AVD), follow the instructions from the "Managing Virtual Devices" section of the Android Developers website at http://developer.android.com/tools/devices/index.html.

You need to create an AVD for each Android platform on which you are planning to test your application.

For information on how to use the emulator, see the "Using the Android Emulator" section in the Android Developers website at http://developer.android.com/tools/devices/emulator.html.

You might want to do the following when using the emulator:

3.5.3.1 Saving the Emulator State

You may find it useful to be able to save the emulator state or reuse the saved state. To do so, you manipulate the avd files or folders that are located in the C:\Users\username\.android\avd directory (on a Windows computer). Each avd folder contains several files, such as userdata.img, userdata.qemu.img, and cache.img. You can copy the cache.img file to another emulator's avd folder to use that state with another emulator. Alternatively, you can run commands listed in Table 3-1 from the command line.

Table 3-1 Commands for Saving the Android Emulator State

Command Description

-snapstorage <file>

File that contains all the emulator state snapshots.

Default value: datadir/snapshots.img

-no-snapstorage

Disables all of the emulator state snapshot functionality by preventing a snapshot storage file from being mounted.

-snapshot <name>

Name of the emulator state snapshot within the storage file for the autostart and autosave.

Default value: default-boot

-no-snapshot

Performs a full boot without performing autosave; vmload and vmsave operate on snapstorage.

-no-snapshot-save

Does not autosave to snapshot on exit; abandons the changed state.

-snapshot-list

Shows a list of available snapshots.

-no-snapshot-update-time

Does not try to correct the snapshot time on restore.

-wipe-data

Resets the use data image by copying it from initdata.


For example, to use the saved state from the testsnap snapshot and auto-save back to it on exit, the following command should be executed from C:\Android\android sdk directory\tools>:

emulator -avd Android_2.2_1 -snapshot testsnap

Caution:

When using this utility, keep in mind that in the process of loading, all contents of the system, including the user data and SD card images, will be overwritten with the contents they held when the snapshot was made. Unless saved in a different snapshot, any changes will be lost.

3.5.3.2 Creating, Saving, and Reusing the SD Card

Execute the following commands to create, save, and reuse the SD card:

  • To create an SD card:

    C:\android sdk directory\tools>mksdcard -l SD500M 500M C:\Android\sd500m.img
    
  • To list existing AVDs:

    C:\android sdk directory\tools>android list avd
    

    This produces a listing similar to the following:

    Name: Android_2.2_1
    Path: C:\Users\username\.android\avd\Android_2.2_1.avd
    Target: Android 2.2 (API level 8)
    Skin: WVGA800
    Sdcard: 200M
    ------------
    Name: Android_2.3.1
    Path: C:\Users\username\.android\avd\Android_2.3.1.avd
    Target: Android 2.3.1 (API level 9)
    Skin: WVGA800
    ------------
    Name: Android_2.3.3
    Path: C:\Users\username\.android\avd\Android_2.3.3.avd
    Target: Android 2.3.3 (API level 10)
    Skin: WVGA800
    ------------
    Name: Android_3.0
    Path: C:\Users\username\.android\avd\Android_3.0.avd
    Target: Android 3.0 (API level 11)
    Skin: WXGA
    
  • To start the Android_2.2_1 with the SD card that has just been created:

    C:\Android\android sdk directory\tools>emulator -avd Android_2.2_1 -sdcard C:\Android\sd500m.img
    
  • To list the running Android emulator instances:

    C:\Android\android sdk directory\platform-tools>adb devices
    
  • To copy a test image to the SD card (this requires the emulator to restart):

    C:\Android\sdk\platform-tools>adb push test.png sdcard/Pictures
    85 KB/s (1494 bytes in 0.017s)
    

3.5.3.3 Configuring the Network

From the Android emulator, you can access your host computer through the 10.0.2.2 IP. To connect to the emulator from the host computer, you have to execute the adb command from a command line on your development computer or from a script to set up the port forwarding.

To forward socket connections, execute

adb forward local remote

using the following forward specifications:

  • tcp:port

  • localabstract:unix domain socket name

  • localreserved:unix domain socket name

  • localfilesystem:unix domain socket name

  • dev:character device name

  • jdwp:process pid (remote only)

For example, an arbitrary client can request connection to a server running on the emulator at port 55000 as follows:

adb -e forward tcp:8555 tcp:55000

In this example, from the host computer, the client would connect to localhost:8555 and communicate through that socket.

For more information, see the "Android Debug Bridge" section in the Android Developers website at http://developer.android.com/tools/help/adb.html.

3.5.3.4 Configuring the Network Proxy

If your development computer is behind a corporate firewall, you might need to execute the following command to start the emulator and initiate its connection with the browser:

emulator -avd myavd -http-proxy myproxy

3.6 Testing the Environment Setup

You can test your environment setup as follows:

  1. In JDeveloper, open the HelloWorld sample application. For more information, see Section 2.7, "Sample Applications" and Appendix F, "ADF Mobile Sample Applications."

  2. Select Application > Deploy from the main menu.

  3. From the drop-down menu, select the deployment profile for the platform to which you wish to deploy the application.

  4. Since for the environment setup testing purposes testing on an iOS-powered device simulator or Android-powered device emulator is preferable because it does not require signing of the application, you should select one of the following deployment actions using the Deploy dialog:

    • For iOS, select Deploy application to simulator, as Figure 3-8 shows.

      Figure 3-8 Selecting Deployment Action for iOS

      Selecting Deployment Action for iOS
    • For Android, select Deploy application to emulator, as Figure 3-9 shows. Ensure that the emulator is running before you start the deployment.

      Figure 3-9 Selecting Deployment Action for Android

      Selecting Deployment Action for Android
  5. Click Next on the Deploy dialog to verify the Summary page, and then click Finish.

For more information on deployment, see Chapter 17, "Deploying ADF Mobile Applications."