2 Setting Up the Development Environment

This chapter provides information on setting up and configuring the MAF environment for application development and deployment.

This chapter includes the following sections:

2.1 Introduction to the MAF Development Environment

The development environment for MAF applications requires that you install JDeveloper and the MAF extension, configure form factors, and install and configure third-party tools to package and deploy the applications to supported platforms.

After you install JDeveloper and the MAF extension, as described in Installing Mobile Application Framework with JDeveloper , configure the development environment for the platforms to which you want your MAF application deployed. Configure form factors if you want to test or deploy applications on a particular mobile device. Install and configure third-party tools if you want to package and deploy your MAF application on supported platforms.

For the complete list of supported versions of development and runtime tools, see Certification Information in Oracle Mobile Application Framework Documentation on Oracle Technology Network at: http://www.oracle.com/technetwork/developer-tools/maf/documentation/index.html.

2.2 Configuring the Development Environment for Target Platforms

Configure the platform-specific settings to package and deploy applications to the Android, iOS, or Windows platforms.

To package and deploy applications to the platforms supported by MAF, JDeveloper needs the name of the platform and the names of the directories containing platform-specific tools and data. For convenience, MAF populates JDeveloper Preferences with these settings. Each platform-specific page hosts the preferences for the platform SDK (Android, iOS, or Windows), collecting information such as the path that MAF needs to compile and deploy Android, iOS, or Windows projects. Depending on several factors related to application signing, you may need to edit some of the fields.

To configure your environment for target platforms:

  1. In JDeveloper, click Tools , and then click Preferences to open Preferences.
  2. In the Preferences dialog, click Mobile Application Framework , and then click the platform you want to configure (Android, iOS, or Windows) to open a page that contains the path and configuration parameters for the supported platforms. For example, the figure shows the page where you configure the platform preferences for Android platform.

    • For the Android platform, specify the following:

      • The Android SDK location on your computer

      • The Android build tools location on your computer

      • Information on the signing credentials

      Figure 2-1 Configuring Platform Preferences for Android

      Description of Figure 2-1 follows
      Description of "Figure 2-1 Configuring Platform Preferences for Android"

    • For the iOS platform, specify the following:

      • Location of the iTunes media files, including the mobile applications that are synchronized to the iOS-powered device

      • The iOS-powered device signing information (See Setting the Device Signing Options in Developing Mobile Applications with Oracle Mobile Application Framework.)

  3. For the Windows platform, specify the following:
    1. In Windows SDK Location, specify the path to the location of MSBuild version 15.0.
    2. Select Debug or Release, and specify the certificate location and password (specified while creating the PFX file).

2.3 Configuring the Development 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 that are defined in preferences are used in the MAF AMX page Preview tab (see Using the Preview in Developing Mobile Applications with Oracle Mobile Application Framework), 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.

See About the maf-config.xml File in Developing Mobile Applications with Oracle Mobile Application Framework.

Before you begin:

Download and install JDeveloper and the MAF extension, as described in Installing Mobile Application Framework with JDeveloper .

To configure the form factors:

  1. From the main menu in JDeveloper, click Tools, and then click Preferences .
  2. In the Preferences dialog, select Mobile Application Framework from the tree on the left.

    Figure 2-2 Defining Form Factors

    Description of Figure 2-2 follows
    Description of "Figure 2-2 Defining Form Factors"

    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 pre-populated during the 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 fail to set the name and resolution for your form, MAF displays an error message.

  4. If you need to revert to the default settings, click More Actions, and then click Restore Defaults.
  5. Click OK to commit your configuration.

2.4 Setting Up Development Tools for the iOS Platform

Set up the iOS devices or install XCode containing iOS SDK with simulators to equip the environment for the deployment of applications to the iOS platform.

In addition to the general-purpose tools listed in Introduction to Installing the MAF Extension with JDeveloper, you might want to set up an iPhone or iPad when getting ready for the development of a MAF application for the iOS platform (see 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 the Xcode installation, you need not install them separately. See How to Set Up an iPhone or iPad Simulator.

2.4.1 How to Install Xcode and iOS SDK

Follow the instructions to download Xcode, which includes the 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 followed, the build and deploy cycle from JDeveloper to Xcode or a device simulator fails 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 access the Apple developer site at http://developer.apple.com.

2.4.2 How to Set Up an iPhone or iPad

Connect an iOS-powered device, with a valid license, certificates, and distribution profile, to your computer to deploy an application to the device.

In your MAF application development and deployment, you can use either the iPhone, iPad, or their simulators (see How to Set Up an iPhone or iPad Simulator). If you plan to use an iPhone or iPad, which is preferable for testing (see Testing MAF Applications in Developing Mobile Applications with Oracle Mobile Application Framework), connect the device 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. See Deploying Mobile Applications in Developing Mobile Applications with Oracle Mobile Application Framework.

Note:

Since the Apple 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

Configure external network access to use iOS simulators, included in XCode downloads, to deploy MAF applications.

In your MAF application development and deployment, you can use either the iOS-powered device itself (see 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 plan to use web services in your application, and you are behind a corporate firewall, you may need to configure external network access. You do so by modifying the network settings in the System Preferences on your development computer. See Configuring the Browser Proxy Information in Developing Mobile Applications with Oracle Mobile Application Framework.

2.5 Setting Up Development Tools for the Android Platform

Install the Android SDK to deploy a MAF application to Android devices.

The Android SDK provides the tools that build and package your application into an .APK file (the file type that installs applications on Android devices), an emulator to create Android Virtual Devices (AVD) where you can test your application if you do not have access to a physical Android device, and an OEM USB driver to connect your development machine to a physical Android device through a USB cable if you do have a device. This last option enables you to deploy an application from your development machine to the Android device.

Android Studio, Google’s IDE for Android development, includes the Android SDK in its installation and provides wizard options that simplify the management of the SDK platforms and tools that you need.

Install Android Studio, and the Android SDK that it includes, by downloading the installation file from https://developer.android.com/studio/index.html. The Android Developer’s website provides installation instructions for Windows, Mac, and Linux. See https://developer.android.com/studio/install.html.

Once you have installed Android Studio, perform the tasks described in the following topics:

2.5.1 Install an Emulator Accelerator

You can accelerate the performance of the emulator that renders AVDs by installing an emulator accelerator.

Once installed, the emulator accelerator speeds up the performance of the emulator and the AVDs that it emulates by allocating additional resources from your development machine. You specify the amount during installation of the accelerator. Once installed, the accelerator appears in the SDK Tools list of the SDK Manager that you can launch from Android Studio, as shown in the following image. The Intel x86 Emulator Accelerator (HAXM) is one type of emulator accelerator that is available.

Figure 2-3 Install Emulator Accelerator

Description of Figure 2-3 follows
Description of "Figure 2-3 Install Emulator Accelerator"

Make sure that the update site for the emulator accelerator that you want to download is selected in the SDK Update Sites tab shown in the previous image. Once downloaded, execute the installer. See https://developer.android.com/studio/run/emulator-acceleration.html#accel-vm.

2.5.2 Create an Android Virtual Device

An Android Virtual Device (AVD) replicates an Android device on your development computer. It is a useful option for testing, especially if you only have access to one or a limited range of physical Android devices.

The AVD Manager that you launch from Android Studio by clicking Tools, Android, and AVD Manager has a range of ready-to-use virtual devices, mostly of those devices developed by Google itself, such as the Nexus and Pixel XL range. Other Android device vendors, such as Samsung, provide specifications on their websites that you can use to create the AVD yourself.

Google maintains documentation describing how to manage AVDs. See https://developer.android.com/studio/run/managing-avds.html.

To create an AVD:

  1. In Android Studio, launch the Android Virtual Device Manager by selecting Tools > Android > AVD Manager.

  2. In the Your Virtual Devices screen, click Create Virtual Device.

  3. In the Select Hardware screen, select a phone device, such as Pixel, and then click Next.

  4. In the System Image screen, click Download for one of the recommended system images. Agree to the terms to complete the download.

  5. After the download completes, select the system image from the list and click Next.

  6. On the next screen, leave all the configuration settings unchanged and click Finish.

  7. In the Your Virtual Devices screen, select the device you just created and click Launch this AVD in the emulator.

2.5.3 Set Up Your Android Device to Install an App from Your Development Machine

You can install your app directly from your development machine to your Android device by configuring the Android device and connecting it to your development machine using a USB cable.

To set up your Android device:

  1. Connect your device to your development machine with a USB cable. If you are developing on Windows, you might need to install the appropriate USB driver for your device. For help installing drivers, see the OEM USB Drivers document.

  2. Enable USB debugging on your device by going to Settings > Developer options.

    Note:

    Developer options is hidden by default. To make it available, go to Settings > About phone and tap Build number seven times. Return to the previous screen to find Developer options.

2.6 Setting Up Development Tools for the Universal Windows Platform

Ensure that the development computer meets the installation requirements, install the MAF extension and Visual Studio 2017, create and install the PFX file, and enable Development Mode on the computer to set up a Windows 10 computer for application development.

To set up your development machine so that you can develop and deploy a MAF application to UWP:

After completing these setup tasks, a MAF application can be deployed to UWP. See Deploying a MAF Application to the Universal Windows Platform in Developing Mobile Applications with Oracle Mobile Application Framework.

2.6.1 Installing Visual Studio

Install Visual Studio 2017 along with the required Windows 10 SDKs.

  1. Download and install an edition of Visual Studio 2017 available at: https://www.visualstudio.com/downloads/.
  2. During the Visual Studio 2017 installation, select these options.
    1. Select the Universal Windows Platform development workload.
    2. Select Windows 10 SDK (10.0.10586.0) and Windows 10 SDK (10.0.14393.0) available under the Individual components.

      Note:

      If you are migrating from an existing MAF and Visual Studio 2015 installation, you might already have the required Windows 10 SDKs installed. If you are performing a fresh installation of Visual Studio 2017, you must install these Windows 10 SDKs.

      Figure 2-4 Installing Visual Studio 2017

      Description of Figure 2-4 follows
      Description of "Figure 2-4 Installing Visual Studio 2017"

      For the following information on the Windows 10 SDKs, see: https://developer.microsoft.com/en-us/windows/downloads/sdk-archive.

      • Getting started

      • System requirements

      • What's new

      • New and updated tools

      • Known issues

2.6.2 Creating a PFX File for MAF Applications

MAF applications deployed to the UWP must be digitally signed using a Personal Information Exchange (PFX) file.

Use Microsoft’s New-SelfSignedCertificate cmdlet in a PowerShell console with administrator privileges to create a PFX file.

To create a PFX file:
  1. Click Start, type PowerShell, right-click Windows PowerShell, and then click Run as administrator.
    The PS C:\windows\system32> prompt is displayed.
  2. Change the value for the -Subject parameter, as required and run the following command. 
    New-SelfSignedCertificate -CertStoreLocation cert:\localmachine\my -Subject 'CN=Example,OU=MAF,O=Oracle,C=US' -KeyAlgorithm RSA -KeyLength 2048 
-Provider 'Microsoft Enhanced RSA and AES Cryptographic Provider' -KeyExportPolicy Exportable -KeyUsage DigitalSignature 
-Type Custom -TextExtension @('2.5.29.37={text}1.3.6.1.5.5.7.3.3,1.3.6.1.4.1.311.10.3.13','2.5.29.19={text}CA=False')
    In the command:

    • -CertStoreLocation: Specifies the certificate store in which to save the new certificate.

    • -Subject: Specifies the string that appears in the subject of the new certificate.

    • -KeyAlgorithm: Specifies the algorithm used to create the asymmetric certificate key.

    • -KeyLength: Specifies the length (in bits) of the certificate key.

    • -Provider: Specifies the name of the KSP or CSP that the cmdlet uses to create the certificate.

    • -KeyExportPolicy: Specifies the policy that governs the export of the private key.

    • -KeyUsage: Specifies the key usages set in the key usage extension of the certificate.

    • -Type: Specifies the type of certificate that the cmdlet creates.

    • -TextExtension: Specifies an array of certificate extensions (strings) the cmdlet includes in the new certificate.

    For more information on the parameters, see Microsoft’s documentation.

    If successful, the command prints the thumbprint ID and subject of the certificate. Here is a sample output.

    PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\my

Thumbprint                                Subject
----------                                -------
EA8DA38619D6FF49C9BBE51651DDD6950EF767AE  CN=Example, OU=MAF, O=Oracle, C=US
  3. Enter the following command. 
    $pwd = ConvertTo-SecureString -String '<password>' -Force -AsPlainText

    In the command, replace <password> with a suitable password.

  4. Enter the following command to create the PFX file. 
    Export-PfxCertificate -cert cert:\localMachine\my\<thumbprint ID> -FilePath <path> -Password $pwd

    In the command:

    • Change <thumbprint ID> to the value output to the console (for example, EA8DA38619D6FF49C9BBE51651DDD6950EF767AE)

    • Change <path> to your preferred path, such as c:\someDir\MyPFX.pfx

  5. Navigate to the specified path and verify whether the PFX file was created.

2.6.3 Installing a PFX File on Windows 10

Follow the steps in the task to install a Personal Information Exchange (PFX) file in a certificate store on a computer so that the certificate can be used for application signing.

An operating system keeps certificates in an area called a certificate store. A Software Publisher Certificate (SPC), with its private and public keys, is used for application signing. SPC is stored in a Personal Information Exchange (.pfx) file. A PFX file has to be copied or installed to a certificate store.

Note:

The installation has to be completed once, manually, for every PFX file on a given computer.
To install a PFX file in a certificate store:
  1. Locate and double-click the .pfx file to open the file in the Certificate Import Wizard.
  2. Select Current User as the Store Location, and then click Next.
    When you install the PFX file in the Local Machine store, the Windows User Access Control dialog is opened. Click Yes for Do you want to allow this app to make changes to your PC?
  3. Verify whether the name in the File name field is the one you want, and then click Next.

    Note:

    The default file location is the location of the file that you double-clicked.
  4. Enter a password for the private key, if required.
  5. Select Included all extended properties, and then click Next.
  6. Select Place all certificates in the following store, and click Browse.
  7. In Select Certificate Store, select the certificate store that matches the store location, Personal , click OK.
  8. Click Next, and then on Completing the Certificate Import Wizard, click Finish to import the certificate.
    This procedure installs the PFX file in the Personal certificate store.
  9. Run the Certificate Import Wizard a second time, select the Current User location, and the Trusted People certificate store.
  10. Run the Certificate Import Wizard a third time, select the Local Machine location, and the Trusted People certificate store.

2.6.4 Enabling Developer Mode on Windows 10

Enable Developer Mode on the Windows 10 development computer to side-load applications and to run them in the Debug mode.

Windows 10 runs UWP applications from a trusted source. Since the certificates you imported are self-signed, they will not run by default.

If you want to develop and deploy MAF applications to the UWP you must enable Developer Mode on the Windows 10 computer that you use. Developer Mode is required for the following reasons:

  • Side-load, or install and run applications, from unofficial sources.

  • Run an application in the Debug mode.

To enable Developer Mode:
  1. Press the Windows key, search for Settings, and select Settings - Modern application from the displayed results.
  2. Select Update & Security, then For developers, and click Developer mode.

    Note:

    If you create an application in Visual Studio, the system prompts you with a dialog to enable Developer Mode.
  3. In JDeveloper, on the Tools menu, click Preferences, and from the preferences that are displayed, expand Mobile Application Framework, and then click Windows Platform.
  4. In Mobile Application Framework: Windows Platform, specify the location of MSBuild.
  5. In the Certificate Location and Password fields, enter the location of the PFX file, and the password.

    Note:

    You can use the same PFX file to run your application in the Release and Debug modes on your computer. We recommend that you use a certificate issued by a trusted authority, such as your internal CA, if you want to distribute your application and run it on other devices within your organization.

2.7 Testing the Environment Setup

Deploy a MAF sample application to test that you set up your environment successfully.

You can test your environment setup as follows:

  1. In JDeveloper, open the HelloWorld sample application.
    See MAF Sample Applications in Developing Mobile Applications with Oracle Mobile Application Framework.
  2. Select Application, and then Deploy from the main menu.

    See Deploying Mobile Applications in Developing Mobile Applications with Oracle Mobile Application Framework.

  3. From the dropdown menu, select the deployment profile for the platform to which you wish to deploy the application.
  4. Since using an iOS-powered device simulator or Android-powered device emulator to test the environment setup is preferable because it does not require signing of the application, you should select one of the following deployment actions using the Deploy dialog:
  5. Click Next on the Deploy dialog to verify the Summary page, and then click Finish.

See Deploying Mobile Applications in Developing Mobile Applications with Oracle Mobile Application Framework.

After a successful deployment (which might take a few minutes), the device to which you had deployed the application displays the launch screen of the HelloWorld application, and then displays the default application feature.

2.8 Setting Up Development Tools from the Command Line Using Startup Parameters

You can set MAF preferences required to develop MAF applications, such as the Android SDK location, by specifying startup parameters when you start JDeveloper. Startup parameters exist to specify the MAF preferences to develop and deploy MAF applications on the Android and iOS platforms.

To launch JDeveloper from the command line with startup parameters, use the -J-D options. All strings must be enclosed in double-quotes, as shown in the examples.

The following example shows how to override the location of the Android SDK:

jdeveloper.exe -J-Doracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.androidPlatformDir="C:\<my_Android_SDK_path>"

These are the startup parameters you can use to set Android preferences from the command line:

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.androidSdkDir

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.androidPlatformDir

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.androidBuildToolsDir

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.androidReleaseSigningKeystorePath

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.androidReleaseSigningKeystorePath

The following example shows how to override the location of the iTunes Media folder:

 ./jdev -J-Doracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.iOSiTunesDir="/Users/<my_username>/Music/iTunes/iTunes Media/Automatically Add to iTunes.localized"

These are the startup parameters you can use to set iOS preferences from the command line:

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.iosProvisioningProfileName

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.iosProvisioningProfileTeamName

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.iOSiTunesDir

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.iosCertificate

  • oracle.adfmf.framework.dt.preferences.PlatformSDKsPrefs.iosProvisioningProfile