Fusion Middleware Documentation
Advanced Search


Send Feedback | Print | PDF | ePub | Mobi
Developing Mobile Applications with Oracle Mobile Application Framework
Close Window

Table of Contents

Show All | Collapse

2 Setting Up the Development Environment

This chapter provides information on setting up and configuring the Mobile Application Framework (MAF) environment for application development and deployment.

This chapter includes the following sections:

2.1 Introduction to the MAF Environment

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

To set up a typical MAF development environment that consists of an IDE, mobile platform-specific tools, and, possibly, a mobile device, follow steps described in Section 2.2, "Prerequisites for Developing MAF Applications."

2.2 Prerequisites for Developing MAF Applications

Prerequisites for developing an application vary depending on your target platform and the type of work you are planning to do:

You do not need to install any additional tools for creating specific types of MAF application content (HTML, remote URL, or MAF AMX).

2.2.1 What You Need to Develop an Application for iOS Platform

Before you start creating a MAF application for iOS, ensure that you have the following available:

Before you start deploying your application to a development environment (see Chapter 3, "Getting Started with Mobile Application Development"), decide whether you would like to use a mobile device or its simulator: if you are to use a simulator, see Section 2.4.3, "How to Set Up an iPhone or iPad Simulator"; if your goal is to deploy to a mobile device, ensure that, in addition to the components included in the preceding list, you have the following available:

2.2.2 What You Need to Develop an Application for Android Platform

Before you start creating a MAF application for Android, ensure that you have the following available:

Before you start deploying your application to a development environment (see Chapter 3, "Getting Started with Mobile Application Development"), decide whether you would like to use a mobile device or its emulator: if you are to use an emulator, see Section 2.5.3, "How to Set Up an Android Emulator"; if your goal is to deploy to a mobile device, ensure that, in addition to the components included in the preceding list, you have the following available:

2.2.3 What You May Need to Know About Supported IDEs

It is possible to use IDEs other than JDeveloper for MAF application development. One of these IDEs is Eclipse (see https://www.eclipse.org/downloads), and to use it you would need to install Oracle Enterprise Pack for Eclipse (OEPE) extension (see http://www.oracle.com/technetwork/developer-tools/eclipse/overview/index.html).

2.2.4 What You May Need to Know About Migrating Plug-Ins

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.

2.3 Setting Up JDeveloper

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

Before you begin:

Consult the Certification and Support Matrix on the MAF documentation page at http://www.oracle.com/technetwork/developer-tools/maf/documentation/ to determine which release of Oracle JDeveloper is compatible with software listed in Section 2.2, "Prerequisites for Developing MAF Applications" for your target platform.

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

Consult the following documentation:

To download and install the MAF extension:

  1. In JDeveloper, choose Help > Check for Updates.

    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 Select update source page that Figure 2-1 shows, select Official Oracle Extensions and Updates under the Search Update Centers, and then click Next.

    Figure 2-1 Checking for Updates in JDeveloper

    This image is described in the surrounding text

  3. In the Select updates to install dialog, select the Mobile Application Framework update.

  4. In the License Agreements page, shown in Figure 2-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 Mobile Application Framework Program available at http://www.oracle.com/technetwork/indexes/downloads/index.html.

  5. Click I Agree.

    Figure 2-2 Licensing Agreements for Oracle Mobile Application Framework Program

    This image is described in the surrounding text

  6. Click Next, and then click Finish.

  7. Restart JDeveloper.

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

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

    • In the Categories tree on the left, expand the Client Tier node and make sure it contains Mobile Application Framework (see Figure 2-3).

    Figure 2-3 Verifying MAF Installation

    This image is described in the surrounding text

    In addition, verify that you installed the correct version of MAF. 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 searching for Mobile Application Framework, as Figure 2-4 shows.

    Figure 2-4 Verifying MAF Version

    This image is described in the surrounding text

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

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

Before you start developing and deploying a MAF application, you may need to configure JDeveloper Preferences for appropriate platforms (see Section 2.3.1.2, "Configuring the Environment for Target Platforms") and form factors (see Section 2.3.1.1, "Configuring the Environment for Form Factors").

2.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.

Since form factors defined in preferences are used in the MAF AMX page Preview tab (see Section 5.3.2.2, "Using the Preview"), you may choose to perform this configuration if you are planning to include a MAF AMX application feature as part of your MAF application and you do not want to accept the default settings. During development, you can select or switch between various form factors to see how a MAF AMX page is rendered. You can also see multiple form factors applied to the same page using the split screen view.

For more information, see Section 4.12.1, "About the maf-config.xml File."

Before you begin:

Download and install JDeveloper and the MAF extension, as described in Section 2.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 2-5 shows, select Mobile Application Framework from the tree on the left.

    Figure 2-5 Defining Form Factors

    This image is described in the surrounding text

    The Mobile Application Framework page is populated with available form factors and the default is set to Android Low.

    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 the green plus sign (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 MAF 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.

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

    • 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, MAF 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.

2.3.1.2 Configuring the Environment for Target Platforms

For successful packaging and deployment of your application to target platforms supported by MAF, JDeveloper must be provided 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. For convenience, MAF prepopulates JDeveloper Preferences with these settings. Depending on several factors related to the application signing, you may need to edit some of the fields.

Before you begin:

Download and install JDeveloper and the MAF extension, as described in Section 2.3, "Setting Up JDeveloper."

Depending on your target platform, download and configure either the Android SDK (see Section 2.5.1, "How to Install the Android SDK") or iOS SDK and Xcode (see Section 2.4.1, "How to Install Xcode and iOS SDK").

To configure your environment for target platforms:

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

  2. In the Preferences dialog that Figure 2-5 shows, select either Mobile Application Framework > Android Platform or Mobile Application Framework > iOS Platform from the tree to open a page that contains the path and configuration parameters for the supported platforms, as Figure 2-6 and Figure 2-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 MAF needs to compile and deploy either Android or iOS projects:

    • For Android platform, 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 2-6).

      Figure 2-6 Configuring Platform Preferences for Android

      This image is described in the surrounding text

    • For iOS platform (see Figure 2-7), specify the following:

      Figure 2-7 Configuring Platform Preferences for iOS

      This image is described in the surrounding text

2.4 Setting Up Development Tools for iOS Platform

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

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

2.4.1 How to Install Xcode and iOS SDK

You download Xcode from http://developer.apple.com/xcode/. This download includes the iOS SDK.

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 and 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.

2.4.2 How to Set Up an iPhone or iPad

In your MAF application development and deployment, you can use either the iPhone, iPad, or their simulators (see Section 2.4.3, "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 22.2, "Testing MAF 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 19, "Deploying 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.

2.4.3 How to Set Up an iPhone or iPad Simulator

In your MAF application development and deployment, you can use either the iOS-powered device itself (see Section 2.4.2, "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 Section 8.7, "Configuring the Browser Proxy Information."

2.5 Setting Up Development Tools for Android Platform

In addition to the general-purpose tools listed in Section 2.2, "Prerequisites for Developing MAF Applications," you might want to set up an Android-powered device when getting ready for development of a MAF application for the Android platform (see Section 2.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 (see Section 2.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.

2.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 MAF supports Android 4.0 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 and Linux requirements are not applicable to the MAF development environment; Eclipse might be applicable depending on your IDE of choice.

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.

    Note:

    If you are not planning to use Eclipse, skip step 3 in the Android SDK installation instructions.

2.5.2 How to Set Up an Android-Powered Device

In your MAF application development and deployment, you can use either the Android device itself, which is preferable for testing (see Section 22.2, "Testing MAF Applications"), or an emulator (see Section 2.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 22, "Testing and Debugging MAF 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.

2.5.3 How to Set Up an Android Emulator

In your MAF application development and deployment, you can use either the Android device itself (see Section 2.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. When creating an AVD through the Create New Android Virtual Device dialog (see "Managing AVDs with AVD Manager" at http://developer.android.com/tools/devices/managing-avds.html), review all the settings to ensure that configuration matches what you are planning to emulate. In particular, you should verify the following

  • The Target field should define the desired Android platform level for proper emulation.

  • The CPU/ABI field should reflect the Intel Atom system image (see Section 2.5.3.2.1, "Configuring AVD for Intel HAXM").

  • The SD card field should be defined based on whether the application uploads files or files install themselves to the SD card.

  • Default settings for the Hardware field (see the "Hardware Options" table at http://developer.android.com/tools/devices/managing-avds.html#hardwareopts) should be acceptable for a typical MAF application. For additional hardware capabilities you may want to use in your application, such as cameras or geolocation services, create new properties.

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.

2.5.3.1 Configuring the Android Emulator

After the basic Android emulator setup is complete, you may choose to perform the following configurations:

2.5.3.1.1 Saving the Emulator State

You can reduce the emulator's load time by saving the emulator state or reusing 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 use the command line to run relevant commands, such as, for example, -snapshot-list, -no-snapstorage, and so on. You can access these commands through emulator -help command.

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.

2.5.3.1.2 Creating, Saving, and Reusing the SD Card

The "SD Card Emulation" section of the Android Developers website at http://developer.android.com/tools/devices/emulator.html#sdcard lists reasons for creating, saving, and reusing the SD card. You can perform these operations by executing the following commands:

  • 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:    AndroidEmulator1
Device:  Nexus S (Google)
Path:    C:\Users\username\.android\avd\AndroidEmulator1.avd
Target:  Android 4.2.2 (API level 17)
Tag/ABI: default/x86
Skin:    480x800
------------
Name:    AndroidEmulator2
Device:  Nexus S (Google)
Path:    C:\Users\username\.android\avd\AndroidEmulator2.avd
Target:  Android 4.2.2 (API level 17)
Tag/ABI: default/armeabi-v7a
Skin:    480x800
Sdcard:  500M

  • To start the AndroidEmulator2 with the SD card that has just been created:

    C:\Android\android sdk directory\tools>emulator -avd AndroidEmulator2 -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)

For more information, see the Android Tools Help at http://developer.android.com/tools/help/index.html.

2.5.3.1.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.

2.5.3.1.4 Configuring the Network Proxy

If your development computer is behind a corporate firewall, you might need to configure a proxy by using one of the following technics:

  1. Execute this command to start the emulator and initiate its connection with the browser:

    emulator -avd myavd -http-proxy myproxy

  2. Start the emulator and then use its Settings utility as follows:

    1. Select Wireless & Networks

    2. Select Mobile Networks > Access Point Names

    3. Select the appropriate internet option

    4. Set the proxy, port, username, and password using the Edit access point list

2.5.3.1.5 Enabling Native Scrolling

To increase the responsiveness of a List View MAF AMX UI component (see Section 6.3.15, "How to Use List View and List Item Components"), you can enable native scrolling as follows:

  1. Add the android.hardwareAccelerated property to the adf-config.xml file, and then set this property to true, as Example 2-1 shows.

    Example 2-1 Enabling Native Scrolling

    <adf-config>
   ...
   <adf:adf-properties-child
                       xmlns="http://xmlns.oracle.com/adf/config/properties">
      <adf-property name="android.hardwareAccelerated" value="true"/>
   </adf:adf-properties-child>
   ...
</adf-config>

  2. In the MAF for Android Deployment Profile Properties editor, use the Android Options page (see Section 19.2.3.1, "Setting the Options for the Application Details") to set the following:

    • Set the Minimum SDK API Level field to 11 or greater.

    • Set the Target SDK API Level field to 9.

  3. Open Preferences from the main menu in JDeveloper, select Mobile Application Framework > Android Platform, and then point the Android Platform Location field to the android-11 folder or greater.

Note:

On iOS platform, the native scrolling is enabled by default.

2.5.3.2 Speeding Up the Android Emulator

The Intel Hardware Accelerated Execution Manager (Intel HAXM) is designed to accelerate the Android-powered device emulator by making use of Intel drivers.

The Intel HAXM is available for computers running Microsoft Windows, Mac OS X, and a separate kernel-based virtual machine option (KRM) for Linux. See http://software.intel.com/en-us/android/articles/intel-hardware-accelerated-execution-manager to access installation guides and detailed descriptions of system requirements for each operating system.

Regardless of which operating system your development computer is running on, it must have the following:

  • Version 17 or later of the Android SDK installed (see Section 2.5.1, "How to Install the Android SDK").

  • Intel processor with support for Intel VT-x, EM64T and Execute Disable (XD) Bit functionality at the BIOS level.

  • At least 1 GB of available RAM.

To download the Intel HAXM, either use the Android SDK Manager (see Speeding Up the Android Emulator on Intel Architecture) or use the following Intel locations:

To install the Intel HAXM, follow steps described in the "Speeding Up the Android Emulator on Intel Architecture" article available at http://software.intel.com/en-us/android/articles/speeding-up-the-android-emulator-on-intel-architecture. Particularly important is to configure AVD (see Section 2.5.3.2.1, "Configuring AVD for Intel HAXM").

If your development computer is running either Microsoft Windows 8.n or later, or Mac OS X 10.9.n or later, you have to apply a Hotfix provided by Intel before using emulator with the Intel HAXM.

Note:

If you do not apply the Hotfix, your computer will freeze and you will loose your work.

To download the Hotfix, use the following locations:

For more information, see the following:

2.5.3.2.1 Configuring AVD for Intel HAXM

When enabling the Intel HAXM, ensure that you download the Intel system image for the Android API level using the Android SDK Manager (see Figure 2-8). As described in Speeding Up the Android Emulator on Intel Architecture:

  • After you have installed the Android SDK, open the SDK Manager and then find the Intel HAXM in the extras section.

  • Select Intel x86 Emulator Accelerator (HAXM) and click Install packages.

    Once you have installed the package, the status changes to Installed, which is not accurate: the SDK only copies the Intel HAXM executable on your computer; you have to manually install the executable.

    Figure 2-8 Downloading Intel System Image in Android SDK Manager

    This image is described in the surrounding text

  • To install the Intel HAXM executable, depending on your development platform search your hard drive for one of the following:

    • On Windows, search for IntelHaxm.exe

    • On Mac OS X, search for IntelHaxm.dmg

    If you accepted default settings, the executable should be located at C:\Program Files\Android\android-sdk\extras\Intel\Hardware_Accelerated_Execution_Manager\IntelHaxm.exe on Windows.

The Intel HAXM only functions in combination with one of the Intel Atom processor x86 system images, which are available for Android 2.3.3 (API 10), 4.0.3 (API 15), 4.1.2 (API 16), 4.2.2 (API 17). These system images can be installed exactly like the ARM-based images through the Android SDK Manager.

Figure 2-9 Installing Intel Atom System Image

This image is described in the surrounding text

To complete the process, use the AVD Manager to create a new virtual device that has hardware-accelerated emulation by selecting Intel Atom (x86) as the CPU/ABI, (see Figure 2-10).

Note:

This option appears in the list only if you have the Intel x86 system image installed.

Figure 2-10 Creating Accelerated AVD

Surrounding text describes Figure 2-10 .

2.6 Testing the Environment Setup

You can test your environment setup as follows:

  1. In JDeveloper, open the HelloWorld sample application by selecting the HelloWorld.jws file (see Appendix F, "Mobile Application Framework Sample Applications").

  2. Select Application > Deploy from the main menu.

    For more information, see Chapter 19, "Deploying Mobile Applications."

  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 2-11 shows.

      Figure 2-11 Selecting Deployment Action for iOS

      This image is described in the surrounding text

    • For Android, select Deploy application to emulator, as Figure 2-12 shows. Ensure that the emulator is running before you start the deployment.

      Figure 2-12 Selecting Deployment Action for Android

      This image is described in the surrounding text

  5. Click Next on the Deploy dialog to verify the Summary page, and then click Finish.

    For more information, see one of the following:

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

After a successful deployment (which might take a few minutes), your iOS-powered device simulator or Android-powered device emulator will display the HelloWorld application icon that you have to activate to launch the application.