This chapter includes the following sections:
Before you can publish an application for distribution to end users, you must test it on a device or virtual device to assess its behavior and ease of use. You create deployment configurations which you use to deploy your MAF application to the device or virtual device (emulator or simulator) where you want to test your MAF application.
MAF uses the deployment configuration to execute the deployment of an application by copying a platform-specific template application to a temporary location, updating that application with the code, resources, and configuration defined in the MAF project. MAF then builds and deploys the application using the tools of the target platform. You can deploy a mobile application as the platform-specific package which you can make available from a download site or application marketplace (for example, the Apple App Store). For testing and debugging, you can deploy to a device or virtual device. You can reuse the application features by deploying the view projects as a feature archive (FAR). You also have the option to reuse the entire mobile application by deploying it as a Mobile Application Archive (.maa
) file.
Each MAF deployment configuration (Android, iOS, Windows) includes a set of different libraries that are specific to the type of deployment (release or debug) in combination with the deployment target (simulators or actual devices). In addition, each set of these libraries includes a JVM JAR file. The application binding layer resides within this virtual machine, which is a collection of Objective-C libraries. For example, MAF deploys a JVM JAR file and a set of libraries for a debug deployment targeted at an iOS simulator, but deploys a different JVM JAR file and set of libraries to a debug deployment targeted to an actual iOS-powered device. The libraries that you declare for the project are included in the deployment artifacts for the project.
Provides an overview of the quick deployment of an application to an Android emulator or an iOS simulator.
Quick deployment ensures developer productivity by providing competitive deployment times without deterioration of performance.
Quick Deployment of Applications
A quick deployment, as opposed to the normal full deployment, saves deployment time by skipping some deployment steps. A quick deployment passes only new or changed file content to an emulator or a simulator.
To use quick deployment on an Android emulator, select either of the following actions:
Click Run, then Run Configurations, and then select the configuration under MAF Application. For more information, see Deploying an Android Application.
To use quick deployment on an iOS simulator, click Run and then click Debug Configurations. Use the procedure described in Deploying an iOS Application.
Note:
The first deployment is a full deployment. A quick deployment may follow an initial full deployment.The deployment of an application to an emulator or a simulator starts a Quick Deployment Session Analysis. The results of the analysis decide whether the deployment must be a quick deployment or a full deployment.
The Quick Deployment Session Analysis is initiated to detect application file changes. The tool that analyzes application file changes triggers a quick deployment. If the analysis fails to find deployment artifacts from a previous Quick Deployment Session that used the same deployment profile, a full deployment is triggered.
MAF-OEPE simplifies the deployment functionality. When you make changes to application files in the Eclipse IDE, those changes are moved to the application that is deployed to an emulator or a simulator, thus removing the need for redeployment.
Key Features of Quick Deployment
The following features define quick deployment.
Quick deployment is supported for applications that are deployed to an Android emulator or an iOS simulator.
Virtual box images can be used for quick deployment provided that root access is configured for the images.
Changes made to an application in the IDE pushes the changes to the application deployed to an emulator or a simulator, without a full deployment, for example, changes to AMX pages or task flows. For the complete list of application changes, see About the Artifacts That Support Quick Deployment.
Deletion of files triggers a full deployment.
The quick deployment of an application only updates new or modified files. Quick deployment does no additional deployment processing.
Lists the artifacts that support MAF-OEPE quick deployment.
Artifact Changes That Support MAF-OEPE Quick Deployment
The following artifact changes support quick deployment:
Changes to AMX pages
Changes to task flows
Changes to bindings
Changes to maf-skins.xml
Addition of new style sheets and referencing them in maf-skins.xml
Changes to maf-config.xml
Changes to adf-config.xml
Changes to connections.xml
Changes to wsm-assembly.xml
Changes to sync-config.xml
Lists the requirements for the quick deployment of an application.
Prerequisites for the Quick Deployment of a MAF-OEPE Application
The quick deployment of an application starts when the following requirements are met:
An installed application is available on the target Android emulator or iOS simulator.
A unique bundle id for the application.
An initial, full deployment must have been completed.
Lists the steps in the Quick Deployment Session of a MAF-OEPE application’s quick deployment.
Quick Deployment Session and Analysis
The deployment of an application to an emulator or a simulator starts a Quick Deployment Session. The session analyzes and decides whether the deployment must be a quick deployment or a full deployment.
A quick deployment session proceeds as follows:
Conducts an initial quick deployment session analysis
Notes the application file changes:
Since the last quick deployment session
With the same deployment profile
If the changed files support quick deployment, the following steps for a quick deployment are completed. Otherwise, a full deployment follows.
Copies the modified files to the emulator or simulator
Restarts the application on the emulator or simulator
Lists the actions that can trigger the full deployment of an application.
Actions That Trigger the Full Deployment of an Application
The following actions trigger the full deployment of an application:
Eclipse is restarted.
Files are changed in non-MAF projects.
Java files in a MAF feature project are created, changed, or deleted.
Files are changed in a non-MAF project, and a Clean operation is triggered from the Project menu before deployment.
Files are deleted in the application, outside of MAF feature projects.
An application is deployed using a different deployment profile, a profile other than the one used in the previous quick deployment.
Some artifacts at the application level can trigger a full deployment. Changes to the following artifacts trigger a full deployment:
maf-application.xml
maf-feature.xml
maf-plugins.xml
maf.properties
logging.properties
Lists the actions with which you can force the full deployment of a MAF-OEPE application.
Certain user actions force the full deployment of a MAF-OEPE application.
Actions That Force the Full Deployment of a MAF-OEPE Application
The full deployment of an application can be forced in multiple ways. Use any of the following actions to trigger the full deployment of a MAF application:
Change any file that does not support quick deployment.
Click Project, and then click Clean.
Uninstall an application on the Android emulator or iOS simulator.
Restart Eclipse.
Lists the limitations of the MAF-OEPE quick deployment of applications.
Quick Deployment Limitations: Files Deployment and User Actions
The following limitations are associated with the MAF quick deployment of applications.
The following actions become necessary if a user switches between a Run session and a Debug session by means of Run or Debug options on the Run menu: Click Project and then click Clean.
The following actions become necessary if a user switches between a normal deployment and a Run or Debug session: Click Project and then click Clean.
If the run or debug configurations change, a full deployment must be forced. The following user actions become necessary: Click Project and then click Clean.
The following files cannot be deployed by means of quick deployment because they need additional processing during deployment:
Files that are created, updated, or deleted in any project other than a MAF ViewController or a ApplicationController project
Application files that are deleted outside MAF feature projects
Files that are deleted from within any MAF feature project
New, changed, or deleted Java files
Changes to the following artifacts at the application level trigger a full deployment:
maf-application.xml
maf-feature.xml
maf-plugins.xml
maf.properties
logging.properties
A quick deployment cannot be initiated in the context of the following user actions:
Changes or removes the emulator application that was installed by the previous quick deployment.
Deploys an application using a deployment profile other than the one used in the previous quick deployment.
Changes in any deployment profile content necessitates a clean build, and the following actions are needed: Click Project and then click Clean.
Quick deployment neither detects nor handles the following changes:
The quick deployment of an application to a different simulator.
MAF project changes that affect which files are included in any workspace project.
Content changes in a deployment profile.
Eclipse restart. After Eclipse restarts, the first deployment is a full deployment. No user action is needed to ensure a full deployment after the restart. A quick deployment may follow an initial full deployment.
You create a deployment configuration for the platform you want the application to run on (Android, iOS, Windows). A deployment configuration defines how an application is packaged into the archive that will be deployed to the platform device (for example, an Android-powered device or Android emulators). The deployment configuration does the following:
Select the assembly project to package and deploy.
Select the target to deploy to. The target is a combination of a platform (for example, Android) and a specific version of the MAF runtime.
Selects the device profile, that is the emulator or device, to deploy to.
Selects platform-specific advanced options.
Specifies the application to deploy.
In addition to the platform-specific deployment configurations, MAF also enables you to package the MAF application as a MAF Application Archive (.maa
) file. Using this file, you can create a new MAF application using a pre-existing application that has been packaged as an .maa
file. By default, this deployment file bears the name of the MAF application followed by _archive
. For more information, see Creating a Mobile Application Archive File.
You can use deployment configurations to deploy a MAF application immediately after creating it using the Run button, as shown in Figure 27-1.
Figure 27-1 Creating a Run Configuration
The Run Configurations and Debug Configurations are both invoked from the Run menu, and they differ in that Debug Configurations has an additional tab, the Debug tab, where you set debug options. For more information, see Testing and Debugging MAF Applications..
Debug—Select this option for development builds. Designating a debug build results in the inclusion of debugging symbols.
During development, you should choose debug in order to use the default keystore.
At runtime, MAF indicates that an application has been deployed in the debug mode by overlaying a debugging symbol that is represented by an exclamation point within a red triangle.
Run—Select to compile the build ready for release, with libraries, and so on. release bits and libraries, and so on.
Tip:
Use the run mode, where the application is compiled for release, not the debug mode, to test application performance.
When you create an application you choose the deployment targets for the application. Later, when you create the deployment configuration you choose the deployment targets to use. You can deploy an application using these configurations, edit them, or construct new ones using the MAF-specific configurations dialog. The Run configurations dialog and Debug configurations dialog enable you to create default deployment configurations. You can create as many deployment configurations as you want.
Before you begin
To enable OEPE to deploy mobile applications, you must designate the SDKs for the target platforms as described in the "Configuring Mobile Application Framework" section in .
To enable OEPE to deploy mobile applications, you must designate the SDKs for the target platforms using the MAF Preferences page.
Tip:
For iOS deployments, run iTunes and the iOS Simulator at least once before you configure their directory locations in the MAF Platforms preferences page.
To create a deployment configuration:
When you deploy an application by clicking Run or Debug, it triggers the packaging and deployment of the application. OEPE creates a deployment directory and related subdirectory. It also creates Feature Archive files (FARs) for the view projects (which must have different names) and assembly project. In addition to these two FARs, OEPE creates copies of any FARs that were imported into the project. Finally, the package is deployed to the device or emulator.
To clean the deploy artifacts, use the Clean dialog to just one set of projects, or all projects. You can clean:
Just one set of projects. This is the fastest way to do a clean-rebuild.
Select Clean projects selected below then select the assembly project you want to clean, and click OK.
All projects. This ensures that all user artifacts get rebuilt before being re-staged and deployed.
Choose Clean all projects, and click OK.
Once you have created a run configuration, you can select it by clicking the green Run arrow from the menu bar. Clicking the arrow will select the last-used run configuration. You can select a different run configuration by clicking the drop-down selector next to the green arrow and choosing the configuration you wish to run from the context menu.
After you define the deployment configuration, you can deploy a mobile application to the Android platform from the run configuration dialog or debug configuration dialog, as shown in Figure 27-2.
Using debug configuration dialog, you can deploy the completed application to an Android emulator or to an Android-powered device for testing. After you have tested and debugged the application, you can use the run configuration dialog to bundle the mobile application as an Android application package (.apk
) file so that it can be published to end users through an application marketplace, such as Google Play.
Figure 27-2 Deployment Configuration Dialog for Android Applications
To create the deployment configuration for Android, you must define the signing options for the application, the behavior of the javac
compiler, and if needed, override the default Oracle images used for application icons with custom ones.
Before you begin
Install and download the Android SDK as described in .
If you deploy to an Android emulator, you must create a virtual device for each emulator instance using the Android Virtual Device Manager, as described in the "Managing Virtual Devices" document, available from the Android Developers website (http://developer.android.com/tools/devices/index.html
).
You must also set the MAF preferences for the locations for the SDK and platform, which are part of the Android SDK package download
To set the MAF preferences for the Android platform SDKs
Open the Preferences dialog from the Window menu (Eclipse menu on MacOS) and navigate to Oracle > Mobile Application Framework > Android to open the Android preferences page, as show in Figure 27-3.
Figure 27-3 Setting Android Preferences
Click Add to open the Select SDK dialog, and navigate to the location of the Android SDK. Click OK.
The SDK information for Android 4.4.2 (API 19), which is illustrated in Figure 27-4, differs from earlier versions.
Note:
Push notifications require devices and emulators running Android 2.2 platform (or later). The Google Play store must be installed on these devices. The Google API must be installed in the SDK to enable push notifications on emulators. Users must create a Google account (and be logged in) on devices running platforms earlier than 4.0.3 (API 15).
See also "GCM Architectural Overview" chapter in Google Cloud Messaging for Android, available from the Android Developers website (http://developer.android.com/index.html
) and How to Create an Android Deployment Configuration.
To create the configuration
The Advanced Android Options page, shown in Figure 27-4, enables you to do the following:
Set a number of advanced options, including the minimum SDK API level, the target SDK API level, the version code, source files, class files, zip alignment, and preferred storage location, as shown in Figure 27-5
Figure 27-5 Setting SDK Levels
Change the default application images, as shown in Figure 27-6.
Figure 27-6 Setting Application Images
The Main and Common tabs of the deployment configurations dialog, and the Advanced Android Options dialog, invoked from the Advanced Options button, enable you to set values that are passed in by the javac
compiler tool options, and also the Android API revisions.
To set the JDK-Compatibility level for the R.java
and .class
files:
<uses-sdk>
attribute in the document entitled "The AndroidManifest.xml File," available through the Android Developers website (http://developer.android.com/guide/topics/manifest/manifest-intro.html
).An application must be signed before it can be deployed to an Android device or emulator. Android does not require a certificate authority; an application can instead be self-signed.
Before you begin
OEPE creates a keystore if one does not exist. In addition, you can create one using the keytool utility, as illustrated in the following example.
An application must be signed before it can be deployed to an Android device or emulator. Android does not require a certificate authority; an application can instead be self-signed.
Defining how the deployment signs a mobile application is a two-step process: within the MAF Platforms preference page, you first define release properties for a key that is used to sign Android applications. You only need to configure the release signing properties once. After you define these options, you configure the deployment configuration to designate if the application should be deployed in the release mode.
keytool -genkey -v -keystore c:\oepe\workspace\releasesigning.keystore -alias releaseKeyAlias -keyalg RSA -keysize 2048 -validity 10000
In this example, the keystore contains a single key, valid for 10,000 days. As described in the "Signing Your Applications" document, available from the Android Developers website (http://developer.android.com/tools/publishing/app-signing.html
), the keytool prompts you to provide passwords for the keystore and key, and to provide the Distinguished Name fields for your key before it generates the keystore. Refer to Java SE Technical Documentation (https://download.oracle.com/javase/index.html
) for information on how to use the keytool utility.
To configure the key options:
Choose Window > Preferences > Oracle > Mobile Application Framework > Android Keystore.
Click and in the Select Keystore dialog, navigate to the location of the keystore, as shown in Figure 27-7 and click OK.
Figure 27-7 Selecting the Keystore Location
Enter the password for the keystore. When you enter a correct password, the Add button is enabled.
Click Add to open the Select Key Alias dialog, as shown in Figure 27-8.
Figure 27-8 Selecting the Key Alias
Enter the password for the key alias and click OK.
The keystore and key alias are now available to be used in the deployment configuration dialog.
To set the Android build mode:
Credentials for keystore access are stored in Eclipse Secure Storage, which stores data outside the workspace. The location is usually in your home directory, although the specific location varies depending on the OS platform.
To find the Secure Storage Location
Note:
Because iOS keys are Mac-specific, there is no need to store them in Eclipse. The iOS XcodeBuild will extract them directly from the Mac Keychain based on the mobileprovision that is specified at launch (configured from the Oracle >Mobile Application Framework > Android > Android Keystores page of the Preferences dialog).
Enabling MAF application icons to display properly on Android-powered devices of different sizes and resolutions requires low-, medium-, and high-density versions of the same images. MAF provides default Oracle images that fulfill these display requirements. However, if the application requires custom icons, you can use the Application Images page, shown in Figure 27-10, to override default images by selecting PNG-formatted images for the application icon and for the splash screen. For the latter, you can add portrait and landscape images. If you do not add a custom image file, then the default Oracle icon is used instead. To create custom images, refer to the "Iconography" document, available from the Android Developers website (http://developer.android.com/design/style/iconography.html
).
Figure 27-10 Setting Custom Images for an Android Application
Figure 27-10 shows selecting images for application icons and portrait orientation splash screen images that applications use for displaying on devices with low-, medium-, high- and extra-high density displays.
Before you begin
Obtain the images in the PNG, JPEG, or GIF file format that use the dimensions, density, and components that are appropriate to Android theme and that can also support multiple screen types. The default location for images in assembly directory
\res\android
For more information, see "Supporting Multiple Screens" document, available from the Android Developers website (http://developer.android.com/guide/practices/screens_support.html
).
To add custom images:
As shown in Table 27-1, each image file is copied to a subdirectory called drawable
, named for the drawable
object, described on the Android Developers website (http://developer.android.com/reference/android/graphics/drawable/Drawable.html
). Each drawable
directory matches the image density (ldpi
, mdpi
, hdpi
, and xhdpi
) and orientation (port
, land
). Within these directories, OEPE renames each icon image file as adfmf_icon.png
and each splash screen image as adfmf_loading.png
.
Note:
In order to view the contents of assembly project
\.main.android
, you must change the default view of the Project Explorer. For more information, see What Happens When You Create an MAF Application.
Table 27-1 Deployment File Locations for Seeded Application Images
Source File (...\res\android) | Temporary Deployment File (...\.main.android\build\release\res) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For custom images, OEPE copies the set of application icons from their specified location to the corresponding density and orientation subdirectory of the temporary deployment location.
You can deploy the mobile application directly to an Android emulator.
Before you begin
Deployment to an Android emulator requires the following:
Configure the keystore password and key alias details in the Android Platform preference page (accessed by choosing Window > Preferences > Oracle > Mobile Application Framework > Android > Android Keystore).
Note:
You must install the Android 4.0.n platform (API 14 or later).
Ensure that the Android Virtual Device instance configuration reflects the ARM system image.
Start the Android emulator before you deploy an application.
You can start the emulator using the Android Virtual Device Manager, as illustrated in Figure 27-11, or from the command line by first navigating to the tools
directory (located in Android\android-sdk
) and then starting the emulator by first entering emulator -avd
followed by the emulator name (such as -avd AndroidEmulator1
).
Note:
You can run only one Android emulator at a time.
Figure 27-11 Starting an Emulator Using Android Virtual Device Manager
To deploy an application to an Android emulator:
You can deploy an application as an .apk file on the local filesystem.
Note:
You must configure the signing options in the Android Platform preference page (accessed by choosing Window > Preferences > Mobile Application Framework) as described in Defining the Android Signing Options.
To deploy an Android application to a local file:
You can deploy a mobile application directly to an Android-powered device that runs on a platform of 2.n (API Level 9) or later.
Before you begin
Connect the device to the development computer that hosts OEPE, as described in .
Ensure that the debug signing credentials are configured in the Android Platform preference page, shown in Figure 27-4.
To deploy an application to an Android device:
Choose Run, then Run Configurations to open the Run Configurations dialog. Under the MAF Applications node select an Android deployment configuration.
Check that the target is the one you want to use, and click Run.
Review the deployment log in the console, as shown in Figure 27-12. The deployment log notes that the deployer starts the Android Debug Bridge server when it detects a running instance of an Android emulator.
Figure 27-14 The Deployment Log
After you have tested and debugged the application, as described in Testing and Debugging MAF Applications, you can publish it to an application marketplace (such as Google Play) by following the instructions provided on the Android Developers website (http://developer.android.com/tools/publishing/publishing_overview.html
).
Before you begin
Create a Run Configuration.
Note:
You must configure the signing options in the Android Platform preference page (accessed by choosing Window > Preferences > Mobile Application Framework) as described in Defining the Android Signing Options.
To deploy an application as an .apk file:
Deploying an application results in the following being deployed in an .apk
file.
The content in the adfmsrc
The content in the .adf
folder
maf-application.xml
and maf-feature.xml
files
logging.properties
file
The JVM 1.4 files
Table 27-2 Contents of the .apk File
Content | Location Within the .apk File |
---|---|
The content in the |
The root folder of the Android application file ( |
The content in the |
The deployment packages the content in the This JAR file contains the following:
This JAR file is not processed by the Dalvik virtual machine. Because the |
|
Located in a file called Configuration ( |
|
Located in the root of the application file. |
JVM 1.4 files |
The JVM files are packaged into two separate folders:
|
After you select a deployment action, OEPE creates a shortcuts on the Debug and Run buttons on the main toolbar, as shown in Figure 27-15. Click the down-arrow, and choose the configuration that enables you to easily redeploy the application using that same deployment action.
Figure 27-15 Choosing a Recently Used Configuration
In OEPE, the log output from the device or emulator is streamed inside the console, as shown in Figure 27-16. This is very useful for debugging. For more information, see How to Configure Logging Using the Properties File.
Figure 27-16 Viewing the Device or Emulator Log
The deployment configuration dialog, shown in Figure 27-17, enables you to deploy an iOS application directly to an iOS simulator or to a device through iTunes. You can only deploy an iOS application from an Apple computer. Deployment to the iOS simulator does not require membership to either the iOS Developer Program or the iOS Developer Enterprise Program; registration as an Apple developer, which provides access to versions of Xcode that are not available through the App Store, will suffice. For more information on iOS developer programs, which are required for deployment to iOS-powered devices (and are described at How to Deploy an Application to an iOS-Powered Device, and How to Distribute an iOS Application to the App Store), see https://developer.apple.com/programs/
.
Figure 27-17 The Deployment Configuration Dialog (for iOS Applications)
For iOS, use the Debug Configuration dialog to define the iOS application build configuration as well as the locations for the splash screen images and application icons.
Before you begin
Download Xcode (which includes the Xcode IDE, performance analysis tools, the iOS simulator, the Mac OS X, and the iOS SDKs) to the Apple computer that also runs OEPE.
Tip:
Refer to the Certification and Support Matrix on Oracle Technology Network (http://www.oracle.com/technetwork/developer-tools/maf/documentation/index.html
) for the minimum supported version required to compile applications.
Because Xcode is used during deployment, you must install it on the Apple computer before you deploy the mobile application from OEPE.
Tip:
While the current version of Xcode is available through the App Store, you can download prior versions through the following site:
https://developer.apple.com/xcode/
Access to this site requires an Apple ID and registration as an Apple developer.
After you download Xcode, you must enter the location of its xcodebuild tool and, for deployment to iOS simulators, the location of the iOS simulator's SDK, in the iOS Platform preference page. For more information, see .
Note:
Run both iTunes and the iOS simulator at least once before entering their locations in the iOS Platform preference page.
To deploy a mobile application to an iOS-powered device (as opposed to deployment to an iOS simulator), you must obtain both a provisioning profile and a certification from the iOS Provisioning Profile as described in Setting the Device Signing Options.
To create a deployment configuration:
The iOS Platform preference page for iOS includes fields for the location of the provisioning profile on the development computer and the name of the certificate. You must define these parameters if you deploy an application to an iOS device or as a MAF Application Archive.
Note:
Neither a certificate nor a provisioning profile are required if you deploy a mobile application to an iOS simulator.
To set the signing options:
Note:
There are provisioning profiles used for both development and release versions of an application. While a provisioning profile used for the release version of an application can be installed on any device, a provisioning profile for a development version can only be installed on the devices whose IDs are embedded into the profile. For more information, see the App Distribution Guide, which is available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/
).
By default, MAF supports all orientations for both iPhone and iPad. If, for example, an application must display only in portrait and in upside-down orientations on iPads, you can limit the application to rotate only to these orientations using the Device Orientation page, shown in Figure 27-21
Figure 27-21 Select a Device Orientation
To limit the display of an application to a specific device orientation
Deselecting a device orientation updates the source .plist
file.
By default, mobile applications deployed to an iOS device through iTunes, or deployed as an archive (.ipa
file) for download, use the default Oracle image unless otherwise specified.
By selecting an iTunes artwork image as the icon for the deployed application, you override the default image. You can use an image to differentiate between versions of the application. Figure 27-22 illustrates the difference between the default image and a user-selected image, where Application4 is displayed with the default image and Application6 is displayed with a user-selected image (the Oracle icon, scaled to 512 x 512 pixels).
During deployment, MAF ensures that the icon displays in iTunes by adding the iTunes artwork image to the top-level of the .ipa
file in a file called iTunesArtwork.
Figure 27-22 Custom and Default Application Icons
For more information on iOS application icon images, see the "Icon and Image Design" section in iOS Human Interface Guidelines. This document is available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/
).
You can rebrand an application by overriding the default Oracle image used for application icons and artwork with custom images. There are three ways you can use your own custom images in an application:
The simplest way is to override the default Oracle image as part of the Run/Debug Configuration, see Overriding the Default Oracle Images in the Configuration.
You can overwrite the default file for each custom image with your own. see Replacing the Default Images..
You can copy your custom icons to the same folder as the default icons and modify the properties file for the device profile for each image, see Add Custom Images.
Note:
All images must be in the PNG format.
For each application, there is an image folder which contains the image files and a properties file which maps predefined keys to a specific image in that folder.
The images folder is application
/res/ios
.
The properties file is in the same folder, ios-resources.properties
.
The properties file configures how custom images are deployed, for example:
# iPad (76 x 76 px) # Appears on home screen on iPad (later than iOS 6.1) # deploys to Icon-76.png oepe.adfmf.res.source.icon76=Icon-76.png # iPad (152 x 152 px) # Appears on home screen on iPad with retina display (later than iOS 6.1) # deploys to Icon-76@2x.png oepe.adfmf.res.source.icon76@2x=Icon-76@2x.png # All devices (40 x 40 px) # Spotlight on all devices (later than iOS 6.1) # deploys to Icon-40.png oepe.adfmf.res.source.icon40=Icon-40.png
The Application Images page enables you to rebrand an application by overriding the default Oracle image used for application icons and artwork with custom images. The options in this page, shown in Figure 27-23, enable you to enter the locations of custom images used for different situations, and device resolutions.
Note:
When you change an icon it is changed for all the devices the icon is used for.
Figure 27-23 Overriding the Default Images
To override the default images:
If you are happy to overwrite the default images, you can overwrite them in the image directory with your own custom images.
To overwrite images:
application
/res/ios
.ios-resources.properties
.The Deployment Actions dialog enables you to deploy an iOS application directly to an iOS simulator.
Before you begin
To enable deployment to an iOS simulator, you must perform the following tasks:
To deploy an application to an iOS simulator:
OEPE can automatically redeploy an application to an iOS simulator. It does this by keeping track of the changes that you make in the application and then redeploying after a build.
The updates occur when the application builds, and not when resources change. If you do not have automatic builds set, then you should select Save automatically before build in the General > Workspace page of the Preferences dialog so that all resources are committed before building and redeploying.
There is a delay of a few seconds before the application restarts so that the application is not redeployed on every build if builds are close together. The default is 6 seconds, but you can change this in OEPE preferences. If you find that the application is restarting too often, you can change the minimum time before quick deploy.
To change the minimum quick deploy delay:
The Deploy to iTunes for Synchronization to device option enables you to deploy a mobile application to an iOS-powered device for debugging and testing. Deployment to an iOS-powered device or to a distribution site requires membership to either the iOS Developer Program or the iOS Developer Enterprise Program. For more information, see https://developer.apple.com/programs/
.
Before you begin
You cannot deploy an application directly from OEPE to a iOS device; an application must instead be deployed from the Applications folder in Apple iTunes. To accomplish this, you must perform the following tasks:
Download Apple iTunes to your development computer and run it at least once to create the needed folders and directories.
Set the location of the Automatically Add to iTunes
folder (the location used for application deployment) in the iOS Platform preference page, shown in Figure 27-26.
Tip:
Although your user home directory (/User/<username>/Music/iTunes/iTunes Media/Automatically Add to iTunes.localized
) is the default directory for the iTunes Media folder, you can change the location of this folder as follows:
In iTunes, select Edit, Preferences, then Advanced.
Click Change and then browse to the new location.
Consolidate the library.
Delete the original iTunes Media folder.
For instructions, refer to Apple Support (http://support.apple.com
).
You must also update the location in the iOS Platform preference page.
Set the location of the Xcode folder where the xcodebuild tool is invoked, such as /Developer/usr/bin
in Figure 27-26.
Figure 27-26 Setting the Locations for the iTunes Media Folder and the xcodebuild System
Enter the name of the certificate and the location of the provisioning profile in the iOS Platform preference page. The OS Provisioning Portal generates the certificate and provisioning profile needed for deployment to iOS devices, or for publishing .ipa
files to the App Store or to an internal download site.
Note:
The deployment will fail unless you set the iOS provisioning profile and certificate to deploy to a device or to an archive. MAF logs applications that fail to deploy under such circumstances. For more information, see What You May Need to Know About Deploying an Application to an iOS-Powered Device.
In the iOS Options page of the deployment configuration, select Run as the build mode and then OK.
Refer to the App Distribution Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/
).
To deploy an application to an iOS-powered device:
Choose Run > Debug Configurations, as shown in Figure 27-18.
Figure 27-27 Setting the iOS Options
Accept the default values, or define the following:
Assembly Project—Choose from the list of those available.
Deployed Bundle Id—If needed, enter a Bundle Id to use for this application that identifies the domain name of the company. The deployed bundle Id must be unique for each application installed on an iOS device and must adhere to reverse-package style naming conventions (that is, com.<organization name>.<company name>). For more information, see the App Distribution Guide, which is available through the iOS Developer Library at http://developer.apple.com/library/ios/navigation/
). For information on obtaining the Bundle Seed Id using the iOS Provisioning Portal, see Registering an Application ID. See also Setting Display Properties for a MAF Application.
Note:
The deployed bundle Id cannot contain spaces.
Because each deployed bundle Id is unique, you can deploy multiple mobile applications to the same device. Two applications can even have the same name as long as their deployed bundle Ids are different. Mobile applications deployed to the same device are in their own respective sandboxes. They are unaware of each other and do not share data (they have only the Device scope in common).
Target—Choose from the list of targets configured in the Preferences dialog, or click Target to add a new target.
Target Configuration
iOS Deploy Target—Choose device or simulator.
iOS Simulator Version—When you select Simulator
as the deploy target, select the version of the emulator to which you are deploying the application. To find the available target versions, select Hardware and then Version on an iPhone simulator. The minimum version is 6.0. The default setting is <Highest Available>. For more information, see the iOS Simulator User Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/
).
Note:
Older versions of the iOS target version are usually available in the simulator for testing.
Select Mobile Provisioning Profile—
iOS Distribution Package (ipa)—If needed, enter the name for the .ipa
file or the .app
file. MAF creates an .ipa
file when you select either the Deploy to distribution package or Deploy to iTunes for synchronization to device options in the Deployment Action dialog, shown in Figure 27-17. It creates an .app
file when you select the Deploy application to simulator option. Otherwise, accept the default name. For more information, see How to Deploy an Application to an iOS-Powered Device and How to Distribute an iOS Application to the App Store.
By default, MAF bases the name of the .ipa
file (or .app
file) on the application id
attribute configured in the maf-application.xml
file. For more information, see Setting Display Properties for a MAF Application.
Advanced Options—Click Options to open the Advanced Option dialog, where you can set various options, as shown in Figure 27-19.
Figure 27-28 Setting the Minimum iOS Version
Minimum iOS Version—Indicates the earliest version of iOS to which you can deploy the application. The default value is the current version. The version depends on the version of the installed SDK.
The application appears in the iTunes Apps Folder, similar to the one illustrated in Figure 27-22 after a successful deployment.
You cannot deploy an iOS application (that is, an .ipa
file) to an iOS-powered device or publish it to either the App Store or to an internal hosted download site without first creating a provisioning profile using the iOS Provisioning Portal, which is accessible only to members of the iOS Developer Program. You enter the location of the provisioning profile and the name of the certificate in the Options page as described in Setting the Device Signing Options.
As noted in the App Distribution Guide, (which is available through the iOS Developer Library at http://developer.apple.com/library/ios/navigation/
), a provisioning profile associates development certificates, devices, and an application ID. The iOS Provisioning Portal enables you to create these entities as well as the provisioning profile.
Tip:
After you download the provisioning profile, double-click this file to add it to your Library/MobileDevice/Provisioning Profile
directory.
Figure 27-29 The iOS Provisioning Portal
A certificate is an electronic document that combines information about a developer's identity with a public key and private key. After you download a certificate, you essentially install your identity into the development computer, as the iOS Development Certificate identifies you as an iOS developer and enables the signing of the application for deployment. In the iOS operating environment, all certificates are managed by the Keychain.
Using the Certificates page in the iOS Provisioning Portal, you log a CSR (Certificate Signing Request). The iOS Provisioning Portal issues the iOS Development Certificate after you complete the CSR.
After you install a certificate on your development computer, review the Current Available Devices tab (located in the iOS Provisioning Portal's Devices page) to identify the Apple devices used by you (or your company) for testing or debugging. The application cannot deploy unless the device is included in this list, which identifies each device by its serial number-like Unique Device Identifier (UDID).
An application ID is a unique identifier for an application on a device. An application ID is comprised of the administrator-created reverse domain name called a Bundle Identifier in the format described in Setting Display Properties for a MAF Application prefixed by a ten-character alpha-numeric string called a bundle seed, which is generated by Apple. Figure 27-30 illustrates an application ID that is unique, one that does not share files or the Keychain with any other applications.
Figure 27-30 An Explicit Application ID
Using a wildcard character (*) for the application name, such as 8E549T7128.com.oracle.*, enables a suite of applications to share an application ID. For example, if the administrator names com.oracle.MAF.* on the iOS Provisioning Portal, it enables you to specify different applications (com.oracle.MAF.application1 and com.oracle.MAF.application2).
Note:
For applications that receive push notifications, the application ID must be a full, unique ID, not a wildcard character; applications identified using wildcards cannot receive push notifications. For more information, see the "Provisioning and Development" section of Local and Push Notification Programming Guide, available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/
)
When applications share the same prefix, such as 8E549T7128, they can share files or Keychains.
Note:
The Bundle Id must match the application ID set in the Options page of the deployment configuration.
After you test and debug an application on an iOS device, you can distribute the application to a wider audience through the App Store or an internal download site. To publish an application to the App Store, you must submit the .ipa
file to iTunes Connect, which enables you to add .ipa
files to iTunes, as well as update applications and create test users.
Before you begin
Before you distribute the application, you must perform the following tasks:
In the iOS Platform preference page, shown in Figure 27-26, enter the location of the Automatically Add to iTunes
directory.
Tip:
Run iTunes at least once before entering this location. See also How to Deploy an Application to an iOS-Powered Device.
Test the application on an actual iOS device. See How to Deploy an Application to an iOS-Powered Device.
Obtain a distribution certificate through the iOS Provisioning Portal.
Note:
Only the Team Agent can create a distribution certificate.
Obtain an iTunes Connect account for distributing the .ipa
file to iTunes. For information, see "Prepare App Submission" in the iOS Development Center's App Store Resource Center. Specifically, review the App Store Review Guidelines to ensure acceptance by the App Review Team.
You may want to review both the and iTunes Connect Developer Guide. These guides are both available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/
).
In the iOS Options page of the deployment configuration, select App Distribution Guide Release as the build mode and then click OK.
To distribute an iOS application to the App Store:
MAF applications can be deployed to the local machine where you develop the application or to an installation package that you use to install the application on a supported UWP device.
MAF provides two build modes for an application that you deploy to the UWP. Use debug mode to test and debug your application as you go through the development cycle. Use release mode to deploy an application that is release ready.
Figure 27-31 Deployment Configuration Dialog for UWP Applications
For UWP, use the Debug Configuration dialog to define the UWP application build configuration as well as the locations for the splash screen images and application icons.
Release ready applications cannot be published to the Windows Store. Choose another mechanism to distribute your application. MAF provides a PowerShell script in the installation package that, when executed, installs the application on the UWP device.
Perform the following setup and configuration tasks before you attempt to deploy an application to the UWP:
Verify that your development machine meets the requirements to deploy a MAF application to the UWP. Among these requirements are that your machine be a UWP device. That is, it runs the Windows 10 operating system. You must enable Developer mode on this machine.
For more information, see the What You Need to Develop an Application for the Universal Windows Platform section in .
Install the Visual Studio software from Microsoft. This software contains the Windows SDK that enables deployment to the UWP.
For more information, see the Setting Up Development Tools for the Universal Windows Platform section in Installing .
Create a certificate (a personal information exchange file) to digitally sign the application you want to deploy.
For more information, see the How to Create a PFX File for MAF Applications section in .
Enter the following values in the Windows page of the Preferences dialog shown in Figure 27-32:
The location of the Windows SDK that is installed with the Visual Studio software from Microsoft.
(On the Windows Certificate page) The location and password (if required) for the certificate that you use to sign the application. Do this in both the Debug and Release tabs if you intend to deploy your MAF application in both modes.
You access the Preferences dialog from the Window menu (Eclipse menu on MacOS), as shown in Figure 27-32.
Before you deploy your application, note the following issues that can prevent deployment:
Microsoft Windows imposes a maximum length for the path to directories and files. MAF application deployment fails if the path for a MAF application exceeds the maximum path length. To work around this issue, place the MAF application in a location where the directory path length is less than the maximum length mandated by Windows. For more information about the maximum path length limitation, see Microsoft's documentation.
Ensure no other process uses the MAF application's data folder before you deploy the MAF application using the Deploy application to local machine option. The application data folder is typically located at C:\Users\[userName]\AppData\Local\Packages\[appBundleId]_[id]
. An example of a scenario where another process uses this folder is if you have a file in the folder open with an application, such as Notepad. If you cannot determine what application process is using the directory/file(s), reboot your machine to resolve the issue.
For information about how to debug an application that you deploy in debug mode, see How to Debug Java Code on the Universal Windows Platform.
To set the MAF preferences for the UWP platform SDKs:
Open the Preferences dialog from the Window menu (Eclipse menu on MacOS).
Navigate to Oracle > Mobile Application Framework > Windows to open the Windows preferences page, as show in Figure 27-32.
Figure 27-32 Setting UWP Preferences
Click Add to open the Select SDK dialog, and navigate to the location of the UWP SDK. Click OK.
To create the configuration:
An application must be signed before it can be deployed to a Windows device and you do this by providing the location of a Windows Personal Information Exchange (.pfx
) file.
For more information, see the How to Create a PFX File for MAF Applications section in .
To specify the location of the .pfx
file:
Deploy the application using a MAF for Windows deployment configuration that deploys the application to the UWP.
To deploy a MAF application to the UWP:
MAF deploys the application to the machine that you are using and installs the application there. In the foreground of Figure 27-33 is an instance of the WorkBetter sample application that has been deployed to a local machine in release mode. In the background of Figure 27-33, you can view the WorkBetter sample application listed among the installed applications on the Windows 10 machine's Apps & features page.
A red icon appears in the upper-left of a MAF application screen that you deploy in debug mode to indicate that the application is in debug mode. As with the application deployed in release mode, you can view and uninstall this application in Windows 10's Apps & features page.
Figure 27-33 MAF Application Deployed in Release Mode on Windows Local Machine
The default deployment launch configuration setting will always deploy application to the local machine. But there is also a way to deploy to other UWP compatible machines and tablets. For this you must change launch configuration to build a package, as described in What Happens When You Deploy Locally as a Package.
To deploy as a package:
The package is generated to the location in the deployment configuration. The directory contains another directory (MafTemplate_*_Test
). Distribute the contents of this latter directory to the end users with supported UWP devices who want to install your MAF application. The directory includes a PowerShell script (Add-AppDevPackage.ps1
) that end users execute to install the application. In addition to the script, the directory contains the application package, dependent packages, and the certificate that signed the application. The following example lists the contents:
Add-AppDevPackage.ps1 Add-AppDevPackage.resources Dependencies MafTemplate_1.0.0.0_x64.appx MafTemplate_1.0.0.0_x64.appxsym MafTemplate_1.0.0.0_x64.cer
The name of the MafTemplate_*_Test
directory and files depends on the Version number and Build mode that you specify in the deployment configuration.
For example, if you specify 2
as the Version number and select the Debug build mode, the directory name is MafTemplate_2.0.0.0_x64_Debug_Test
. A version number of 3
and the Release build mode produces a MafTemplate_3.0.0.0_x64_Test
directory.
To enable re-use by MAF view controller projects, application features— typically, those implemented as MAF AMX or Local HTML— are bundled into an archive known as a Feature Archive (FAR). A FAR is a JAR file that contains the application feature artifacts that can be consumed by mobile applications. A FAR may contain Java classes, though these classes must be compiled. The example below illustrates the contents of a FAR, which includes a single maf-feature.xml
file and a connections.xml
file.
connections.xml (or some form of connection metadata) META-INF jar-connections.xml jar-adf-config.xml adfm.xml maf-feature.xml MANIFEST.MF task-flow-registry.xml oracle application1 mobile DataControls.dcx DataBindings.cpx pageDefs view1PageDefs model Class1.class public_html adfc-mobile-config.xml index.html navbar-icon.html springboard-icon.html view1.amx task-flow-definition.xml
Working with Feature Archive files involves the following tasks:
Creating a Feature Archive file—You create a Feature Archive by exporting the view project as a FAR.
Using the Feature Archive file when creating a mobile application—This includes registering a FAR with the application, and then registering the features in the FAR with the application.
Deploying a mobile application that includes features from FARs—This includes unpacking the FAR to a uniquely named folder within the deployment template.
Note:
MAF generates FARs during the deployment process. You only need to deploy a view project if you use the FAR in another application.
Use the OEPE Export wizard to create the .far
file.
Before you begin
Create the appropriate connections for the application. Because FARs may be used in different MAF applications with different connection requirements, choose a connection name that represents the connection source or the actual standardized connection name.
How to package mobile features as a Feature Archive File:
The Deployment Actions dialog enables you to deploy the FAR as a JAR file. This dialog includes only one deployment option, Deploy to feature archive JAR file.
How to deploy the Feature Archive deployment profile:
To use a FAR from an external application, you need to register the FAR in your application's maf-application.xml
file. Figure 27-37 shows Feature Archives that can be made available to a mobile application through a file system connection.
Figure 27-37 Deployed Feature Archive JARs in the MAF Application Editor
The MAF Application Archive (.maa
) file format enables you to provide third-parties with an unsigned mobile application. By deriving a mobile application from an imported .maa
file, you enable various customizations, which include:
Giving an application a unique application ID (to enable push notifications, for example).
Signing an application with a company-specific credential or certificate.
Replacing the resources with customized splash screens and application icons.
You can create a new mobile application from a n existing mobile application by first packaging the original mobile application as a Mobile Application Archive (.maa
) file and then by deriving a new mobile application from this file. An .maa
file can be used by third parties, as described in Creating Unsigned Deployment Packages.
An .maa
file preserves the structure of the mobile application. Table 27-4 describes the contents of this file.
Table 27-4 Contents of a Mobile Application Archive File
Directory | Description |
---|---|
|
Contains the
|
|
Contains a JAR file for each project in the workspace. For example, a The |
|
Contains the application-level libraries (including FARs) that are external to the original mobile application. |
|
Includes the |
|
Includes the following directories:
|
In addition to the artifacts listed in Table 27-4, the .maa
file includes any folder containing FARs or JAR files that are internal to the original mobile application. See also What Happens When You Import a MAF Application Archive File.
Note:
Importing an .maa
file into an existing application overwrites the workspace and project container files (the.jws
and .jpr
files, respectively). As a result, all prior changes to MAF AMX pages and configuration files, such as maf-application.xml
, maf-config.xml
, connections.xml
, and adf-config.xml
, will not be retained.
The MAF Application Archive (.maa
) file format enables you to provide third-parties with an unsigned mobile application. By deriving a mobile application from an imported .maa
file, you enable various customizations, which include:
Giving an application a unique application ID (to enable push notifications, for example).
Signing an application with a company-specific credential or certificate.
Replacing the resources with customized splash screens and application icons.
You can create a new mobile application from a n existing mobile application by first packaging the original mobile application as a Mobile Application Archive (.maa
) file and then by deriving a new mobile application from this file. A .maa
file can be used by third parties, as described in Creating Unsigned Deployment Packages.
A .maa
file preserves the structure of the mobile application. Table 27-4 describes the contents of this file.
Table 27-5 Contents of a Mobile Application Archive File
Directory | Description |
---|---|
|
Contains the
|
|
Contains a JAR file for each project in the workspace. For example, a The |
|
Contains the application-level libraries (including FARs) that are external to the original mobile application. |
|
Includes the |
|
Includes the following directories:
|
In addition to the artifacts listed in Table 27-4, the .maa
file includes any folder containing FARs or JAR files that are internal to the original mobile application. See also What Happens When You Import a MAF Application Archive File.
To package a mobile application as a MAF Application Archive file:
The MAF Application Archive (.maa
) file format enables you to provide third-parties with an unsigned mobile application. By deriving a mobile application from an imported .maa
file, you enable various customizations, which include:
Giving an application a unique application ID (to enable push notifications, for example).
Signing an application with a company-specific credential or certificate.
Replacing the resources with customized splash screens and application icons.
Note:
You cannot import an .maa
file into a workspace that already contains one or more of the same projects. Instead, you must import the .maa
file into a different workspace.
You create an unsigned application by importing an .maa
file into a new mobile application.
To create an unsigned application:
Oracle Mobile Security Suite (OMSS) provides enterprise-level security for mobile applications. It offers data leakage prevention and encryption of application data and database content through containerization at deployment time. For more information about containerizing your MAF application with OMSS, see Containerizing a MAF Application for Enterprise Distribution.
You can containerize MAF applications that you deploy to the iOS and Android platforms with OMSS. MAF applications that you deploy to the Universal Windows Platform cannot be containerized with OMSS.
Before you begin
You must have the OMSS containerization tool installed. This tool is a command-line utility with the file name c14n
. You can download OMSS and read instructions on installation on the Oracle Technology Network:
http://www.oracle.com/technetwork/middleware/id-mgmt/overview/default-2099033.html
Note:
For iOS, you must also have selected the name of the provisioning profile in the iOS Platform preferences page as described in Setting the Device Signing Options.
Containerization is not supported for Android or Windows.
OEPE will not allow you to deploy a mobile app containerized with OMSS to an emulator with default names.
Figure 27-41 Mobile Application Displaying the Lock Icon for Containerization
When you deploy a MAF application containerized with Oracle Mobile Security Suite (OMSS), you can then upload it to the OMSS Mobile App Catalog, which displays a list of currently available apps. Before publishing the application to end users, the OMSS administrator applies various policies to the app to manage its functionality. By applying specific policies on the OMSS server side, the OMSS administrator can manage the security and sharing requirements for applications containerized with the Oracle Mobile Security App Containerization Tool. Data in transit and data stored locally inside containerized apps on the mobile device is encrypted. Encrypted data storage includes application data, including files, databases, application cache, and user preferences.
After applying OMSS data leakage protection and encryption, you can then make the app available to users from a download site.
Note:
iOS MAF apps that are containerized with OMSS can only be distributed to users through an internal download site or enterprise app store. Containerized iOS MAF apps cannot be uploaded to the Apple App store. This restriction is not applicable to Android MAF apps that are containerized with OMSS. These apps can be distributed through an internal download site, enterprise app store, or Google Play.
For details about how system administrators use the OMSS Mobile App Catalog to manage the MAF application provisioned to devices and workspaces, see the "Managing Devices and Workspaces" chapter in .
The following OMSS data leakage protection policies restrict how and if users can share data within an app:
Email allowed can restrict the ability to send email from an app.
Instant Message allowed can restrict the ability to send Instant Message from an app.
Video chat allowed restricts the ability to share information via services such as FaceTime.
Social Share allowed restricts the ability to share information via services such as Facebook or Twitter.
Print allowed restricts the ability of the user to print.
Restrict file sharing restricts the ability of the user to share files outside the secure enterprise workspace.
Restrict copy/paste allows copy/paste inside the secure container, containerized apps or between containerized apps, but not to apps outside the secure enterprise workspace.
Redirects to container allowed prevents any app outside the Mobile Security Container workspace from redirecting a URL into the container.
Save to media gallery allowed prevents images, videos and audio files from being saved to media gallery and photo stores.
Save to local contacts allowed prevents contacts inside secure enterprise workspace apps from being saved down to native device contacts app.
Redirects from container allowed prevents any vApp from the Mobile Security Container workspace or containerized app from redirecting a URL outside the Mobile Security Container workspace or containerized app.