3 Getting Started with Mobile Application Development
This chapter describes how to use the Oracle Enterprise Pack for Eclipse (OEPE) wizards and tools to create a basic application using Oracle Mobile Application Framework (MAF), and also describes the artifacts that are automatically generated when you create an application.
This chapter includes the following sections:
3.1 Introduction to Declarative Development for MAF Applications
Because MAF is integrated within the Oracle Enterprise Pack for Eclipse design time, you can create, deploy, and test simple mobile applications (and most parts of more complex mobile applications as well) without writing a single line of code.
3.2 Creating an Application Workspace
The Oracle Mobile Application Framework provides Oracle Enterprise Pack for Eclipse with the application templates that seed the completed project with basic files. The first steps in building an MAF application are to assign it a name and to specify a directory where its source files will be saved. By creating an application with the application templates provided by Oracle Enterprise Pack for Eclipse, the workspace is automatically organized into projects, along with the required configuration files.
3.2.1 How to Create a Workspace for a Mobile Application
You create an application using the application creation wizard.
To create a mobile application:
-
Choose File > New, and then select MAF Application. This opens the MAF Application wizard (see Figure 3-1).
-
In the Application Display Name field, enter a name for the application, such as MobileApplication. This is the top-level structure of the MAF application. It is also sometimes called the assembly project, and holds all of the artifacts required for packaging and deployment of the application. Click Next.
-
The next page of the wizard, shown in Figure 3-2, displays the Application Project Name and the View Project Name for the MAF application you are creating. By default, Oracle Enterprise Pack for Eclipse uses the name you entered on the first page, but adds
Application
andView
, respectively, to the projects.For example, if you had created a MAF application called Employee, the wizard creates the names
EmployeeApplication
andEmployeeView
. You can change the names if desired. To accept the default names of the projects, click Next. -
The Configure Deployment page of the MAF Application wizard, shown in Figure 3-3, lets you select the deployment targets you wish to use for the MAF application you are developing. The targets displayed on this page are those you specified when setting up your environment. For more information, see Section 2.3.1, "How to Configure the Development Environment for Target Platforms.".
By default, the wizard creates one deployment target for each SDK you have defined. Select those you want to use.
-
Click Finish to complete the creation of the MAF application and its projects.
A dialog is displayed asking you whether to change to the MAF perspective, as shown in Figure 3-4. Click Yes.
Tip:
In addition to creating an MAF application following the above-mentioned steps, you can open the HelloWorld sample application (located by selecting File > New > MAF Examples, and then selecting HelloWorld) and view the artifacts that Oracle Enterprise Pack for Eclipse generates after you complete the application creation wizard.
3.2.2 What Happens When You Create an MAF Application
When you create an MAF application, Oracle Enterprise Pack for Eclipse creates the following artifacts, which you access from the Project Explorer:
-
The top-level or assembly project. This holds all of the artifacts required for packaging and deployment of the application. In addition, the assembly project tracks the version of the MAF run time that the project uses, if you are migrating an application from an earlier version of MAF.
-
The application project. This contains a Data Control Manager which abstracts the device features and the application features.
-
The view controller-type project. This contains the source folder (
src
) and the ViewContent folder.
Oracle Enterprise Pack for Eclipse adds application-level and project-level artifacts, which you access from the Project Explorer shown in Figure 3-5. These artifacts include two MAF editors: one used for configuring the MAF application itself, such as its name, the application lifecycle listener (LifeCycleListenerImpl.java
), the login server connections for the embedded application features, and another that describes which application features comprise the MAF application. These editors, which are called the MAF Application Editor maf-application.xml
and the MAF Feature Editor maf-feature.xml
, are described in Section 3.2.2.1, "About the Assembly-Level Resources" and Section 3.2.2.2, "About the View Project Resources."
Oracle Enterprise Pack for Eclipse also creates the DeviceFeatures data control. The Apache Cordova Java API is abstracted through this data control, thus enabling the application features implemented as MAF AMX to access various services embedded on the device. Oracle Enterprise Pack for Eclipse also creates the ApplicationFeatures data control, which enables you to build a springboard page. By dragging and dropping the operations provided by the DeviceFeatures data control into a MAF AMX page (which is described in Section 7.10, "Using the DeviceFeatures Data Control," you add functions to manage the user contacts stored on the device, create and send both e-mail and SMS text messages, ascertain the location of the device, use the device's camera, and retrieve images stored in the device's file system.
By default, some files are filtered from view in the Project Explorer. In order to see the generated artifacts required for packaging and deployment of the application, click the down arrow in the explorer toolbar and choose Customize View.
In the Available Customizations dialog, shown in Figure 3-6, deselect .* resources
and click OK.
Now expand the assembly project node and .main.android
or .main.ios
node to view the package and deploy artifacts, as shown in Figure 3-7.
To filter these files from the view in the Project Explorer, reopen the customization dialog and select .* resources
and click OK.
3.2.2.1 About the Assembly-Level Resources
Oracle Enterprise Pack for Eclipse generates the files for the MAF application in the assembly project. These files, described in Table 3-1, contain configuration files for describing the metadata of the MAF application. You access these files from the res
node under the assembly project in the Project Explorer, shown in Figure 3-8.
The assembly project (which is generated with the default name, application
), which contains the application-wide resources, provides the presentation layer of the MAF application in that it includes metadata files for configuring how the application will display on a mobile device. This project dictates the security for the MAF application and can include the application's login page, an application-wide resource. The application controller project is essentially a consumer of the view controller project, which defines the application features and their content. For more information, see Section 3.2.2.2, "About the View Project Resources."
Tip:
Place code that supports application-wide functionality, such as an application-level lifecycle listener, in the application controller project.
Table 3-1 Mobile Application-Level Artifacts Accessed Through Top_Level Project
Artifact(s) | File Location | Description |
---|---|---|
|
For example:
|
A stub XML application descriptor file that enables you to define the MAF application. Similar to the application descriptors for ADF Fusion Web applications, this enables you to define the content for an application, its navigation behavior, and its user authentication requirements. For more information, see Section 4.3, "About the Mobile Application Configuration File maf-application.xml." |
|
For example:
|
Use to configure the default skin used for MAF applications. For more information, see Section 4.11, "Defining the Content Types for an Application Feature." |
Application images |
For example:
|
A set of images required for the deployment of iOS and Android applications. These include PNG images for application icons and splash screens. Deployment to an iOS-powered device, such as an iPhone, requires a set of images in varying sizes. The default iOS images provided with the project include:
To override these images, see Section 19.2.4.5, "How to Add a Custom Image to an Android Application." |
|
For example:
|
The |
|
For example:
|
Enables you to set the application error logging, such as the logging level and logging console. For more information, see Section 22.4, "Using and Configuring Logging." |
|
For example:
|
The configuration file for the Java virtual machine, JVM 1.4. Use this file to configure the application startup and heap space allotment, as well as Java and JavaScript debugging options. For more information, see Section 22.3.5, "How to Enable Debugging of Java Code and JavaScript." |
|
For example:
|
Used to configure application-level settings, including the Configuration Service parameters. See also Chapter 9, "Configuring End Points Used in MAF Applications." |
|
For example:
|
The repository for all of the connections defined in the MAF application. |
|
For example:
|
Stores the web service policy definitions used for secured web services. |
|
For example:
|
The configuration file for the offline cache of data returned from REST web services. Caching not only improves the user experience by boosting performance, but allows users to read and view data when they are working in an off-line mode. |
Within the application project itself (which is generated with the default name, application
Application
), shown in Figure 3-9, Oracle Enterprise Pack for Eclipse creates the following artifacts, listed in Table 3-1.
Table 3-2 Application Project Artifacts
Artifact(s) | File Location | Description |
---|---|---|
|
For example:
|
The default application lifecycle listener (ALCL) for the MAF application. |
|
For example:
|
Defines the available skins and also enables you to define new skins. For more information, see Section 4.13, "Skinning Mobile Applications." |
|
For example:
|
Maintains the paths (and relative paths) for the |
|
For example:
|
The data controls registry. For information on using the DeviceFeatures data control, which leverages the services of the device, see Chapter 7, "Using Bindings and Creating Data Controls." For information on the ApplicationFeatures data control, which enables you to create a springboard page that calls the embedded application features, see Section 4.6.5, "What You May Need to Know About Custom Springboard Application Features with MAF AMX Content." |
3.2.2.2 About the View Project Resources
The view project (which is generated with the default name, application
View
), as illustrated in Figure 3-10) houses the resources for the application features. Unlike the application project described in Section 3.2.2.1, "About the Assembly-Level Resources," the view project's metadata files describe the resources at the application feature-level, in particular the various application features that can be aggregated into a MAF application so that they can display on a mobile device within the springboard of the MAF application itself or its navigation bar at runtime. Further, the application feature metadata files describe whether the application feature is comprised of HTML or MAF AMX pages. In addition, the view controller project can include these application pages as well as application feature-level resources, such as icon images to represent the application feature on the springboard and navigation bar defined for the MAF application.
Tip:
Store code specific to an application feature within the view controller project. Use the application controller project as the location for code shared across application features, particularly those defined in separate view controller projects.
The view controller project can be decoupled from the application controller project and deployed as an archive file for reuse in other mobile applications as described in Section 4.14, "Working with Feature Archive Files." In rare cases, an application controller project can consume more than one view controller project.
Note:
Adding a MAF view controller project as a dependency of another MAF view controller project, or as a dependency of a MAF application controller project, prevents the deployment of a MAF application. For more information, see Section 4.7.2, "What You May Need to Know About Feature Reference IDs and Feature IDs."
As shown in Table 3-3, these resources include the configuration file for application features called maf-feature.xml
, which you edit using the MAF Feature Editor.
Table 3-3 View Controller Artifacts
Artifact(s) | File Location | Description |
---|---|---|
|
For example:
|
A stub XML descriptor file that enables you to define application features. For more information, see Section 4.9, "About the Mobile Application Feature Configuration File." After you have configured the Mobile Preferences as described in Section 2.3.1, "How to Configure the Development Environment for Target Platforms," you can deploy this application using the default deployment configuration settings. For more information, see Chapter 19, "Deploying Mobile Applications." |
Application-Specific Content |
For example:
|
The application features defined in |
3.2.2.2.1 How to Create Multiple View Projects
Each OEPE assembly project can have more than one view project, in addition to the view project included when you first create your assembly project. The features included in this view project will be available from the application created when you build and deploy the assembly project.
To create a new view project in an existing assembly project:
-
Click File > New > MAF View Project. This opens the MAF View Project Wizard.
-
From the wizard, click Browse to select the assembly project to which you wish to add a new view project.
-
OEPE automatically gives the new view project a unique name that matches the assembly project. For example, if you are creating a new view project within the CompGallery sample application, the wizard names the view project
CompGalleryView1
(to distinguish it from the defaultCompGalleryView
project initially created.If desired, you can edit the name of the new view project at this time.
-
Click Finish to create the new view project.
The wizard adds view project files to the assembly project you selected in step 2.
3.2.2.3 About Deployment Configurations
Oracle Enterprise Pack for Eclipse uses deployment configurations to determine how applications are run or debugged. The configuration defines the way the packages into the archive that will be deployed to the target environment (such as a mobile device, an emulator, or an application marketplace, such as the iOs App Store). The deployment configuration:
-
Specifies the format and contents of the archive file that will be created
-
Lists the source files, deployment descriptors, and other auxiliary files that will be packaged
-
Describes the type and name of the archive file to be created
-
Highlights dependency information, platform-specific instructions, and other information
When you create an application, Oracle Enterprise Pack for Eclipse creates deployment configurations that are seeded with default settings and image files. By default, one deployment target is created for each SDK you have. Provided that you have configured the environment correctly, you can use these configurations to test an MAF application immediately after creating it by choosing Run and then Debug Configurations, as shown in Figure 3-11.
Note:
During development, use Debug Configuration. For production deployment, use the Run Configuration.
Choosing Debug Configurations rather than Run Configurations allows Oracle Enterprise Pack for Eclipse to use, if necessary, debug settings such as the default debug keystore.
In the Create Configuration dialog, shown in Figure 3-12, create a new configuration by clicking .
Using the Configurations page, shown in Figure 3-13, you then select the appropriate deployment target.
Note:
iOS and Android application deployments to simulators and devices have distinct environment set up and configuration requirements. For more information, refer to the "Before You Begin" sections throughout Section 19.2.5, "Deploying an Android Application," and Section 19.2.7, "Deploying an iOS Application."
You can create a MAF Application configuration for each supported platform and device or emulator.
You can edit these configurations by selecting the configuration from the list under MAF Applications. For information on the values configured for MAF application configurations, see Section 19.2.4, "How to Create an Android Deployment Configuration" and Section 19.2.6, "How to Create an iOS Deployment Configuration."
In addition to the platform-specific deployment configurations, MAF also creates a deployment configuration that enables you to package the MAF application as a Mobile 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. For more information, see Section 19.4, "Creating a Mobile Application Archive File" and Section 19.5, "Creating Unsigned Deployment Packages."
3.2.3 What You May Need to Know About Editing MAF Applications and Application Features
Creating an application results in the generation of the maf-application.xml
file, which enables you to configure the mobile application and also the maf-feature.xml
file, which you use to add, remove, or edit the application features embedded within the mobile application. Oracle Enterprise Pack for Eclipse provides you with the MAF Application Editor for maf-application.xml
and with the Mobile Features Editor for maf-feature.xml
. These let you declaratively change these files. Figure 3-14 shows an example of the overview editor of the maf-application.xml
file.
As shown in Figure 3-14, the MAF Application Editor is located in the Project Explorer under the application and MAF node. The maf-application.xml
file is located under the application, adf, and META-INF nodes. You open this editor by double-clicking MAF Application Editor.
Section 4.3, "About the Mobile Application Configuration File maf-application.xml" describes the components of the maf-application.xml
page.
As illustrated in Figure 3-15, the MAF Feature Editor is located in Explorer under the view project and MAF node. The maf-feature.xml
file is located under the view project, src, and META-INF nodes. You open this editor by double-clicking MAF Feature Editor, or by double-clicking maf-feature.xml
. You use this file to compose the content for the MAF application.
Like the MAF Application Editor for editing the maf-application.xml
file, Oracle Enterprise Pack for Eclipse presents the MAF components used for building the elements of the maf-features.xml
configuration file in the MAF Feature Editor. The elements of maf-features.xml
are described in Section 4.9, "About the Mobile Application Feature Configuration File."
3.2.4 About the MAF Application Editor and MAF Feature Editor
OEPE's MAF Feature Editor and MAF Application Editor are the primary tools you use to interact with a MAF application while you are creating it. These two editors interact with each other, and with the files that comprise the application you are developing, in a way that can affect your choices while editing.
When you use the MAF Application Editor to make changes to maf-application.xml
, OEPE opens not only that file, but other files related to that application. These might include any registered feature files (edited with MAF Feature Editor) and plugins. To view some of these files in the MAF Application Editor, expand the Outline and select Registered Features. In addition, files in the Features folder (if any) may also be affected. Figure 3-16 shows the MAF Application Editor open to the Registered Feature listing, which the tooltip shows is connected to the file maf-feature.xml
.
If you double-click on maf-feature.xml
in the Registered Features pane of the MAF Application Editor, OEPE opens the file in the MAF Feature Editor, as expected. The interaction between these two files (and others as applicable) while you are editing, however, deserves attention.
When you go to the MAF Application Editor and save your application file, OEPE checks to determine whether the related feature file has been changed externally in the file system. If it has, OEPE displays a confirmation dialog informing you that the related file has been changed relative to the contents of the editor. You have the chance at this point to choose one of the following options:
-
Reload the editor. This copies the changes from your file system into the MAF Application Editor, overwriting any changes you may have made to the file.
-
Not reload the editor. This saves the
maf-feature.xml
file and overwrites the contents of your file system.
OEPE performs a similar check if you select File > Save All. In addition, the File > Close All function checks to see whether you have files open in the MAF Application Editor and MAF Feature Editor, and checks for conflicts in those open files before closing. This helps prevent data loss.
3.2.5 Creating a MAF AMX Page
As described in Chapter 5, "Creating MAF AMX Pages," the MAF AMX components enable you to build pages that run identically to those authored in a platform-specific language. MAF AMX pages enable you to declaratively create the user interface using a rich set of components. Figure 3-17 illustrates the declarative development of an MAF AMX page, which involves selecting options in the Palette and adding them to the MAF AMX page.
These pages may be created by the application assembler, who creates the MAF application and embeds application features within it, or they can be constructed by another developer and then incorporated into the MAF application either as an application feature or as a resource to an MAF application.
The project in which you create the MAF AMX page determines if the page is used to deliver the user interface content for a single application feature, or be used as a resource to the entire MAF application. For example, a page created within the application controller project, as shown in Figure 3-21, would be used as an application-wide resource.
Tip:
To make pages easier to maintain, you can break it down in to reusable segments known as page fragments. An MAF AMX page may be comprised one or more page fragments.
MAF enables you to arrange MAF AMX view pages and other activities into an appropriate sequence through the MAF task flow. As described in Chapter 5, "Creating Task Flows," an MAF task flow is visual representation of the flow of the application. It can be comprised of MAF AMX-authored user interface pages (illustrated by such view activities, such as the WorkBetter sample application's default List page and the Detail page in Figure 3-18) and nonvisual activities that can call methods on managed beans. The non-visual elements of a task flow can be used to evaluate an EL expression or call another task flow. As illustrated by Figure 3-18, MAF enables you to declaratively create the task flow by dragging task flow components onto a diagrammer. MAF provides two types of task flows: a bounded task flow, which has a single point of entry, such as the List page in the WorkBetter sample application, and an unbounded task flow, which may have multiple points of entry into the application flow. The WorkBetter sample application sample application is This sample application is available from File > New > MAF Examples.
MAF provides a number of dialogs and wizards to add MAF pages, reusable portions of MAF AMX pages called MAF page fragments, and application features. Figure 3-19 shows the menu options available from the File menu.
Additional options are available from File > New > Other (see Figure 3-19). In the New dialog, expand Oracle then expand Mobile Application Framework
3.2.5.1 How to Create an MAF AMX Page
You can use the MAF Page dialog to create AMX pages used for the user interface for an application feature, or as an application-level resource (such as a login page) that can be shared by the application features that comprise the MAF application. For more information on application feature content, see Section 4.11.1, "How to Define the Application Content."
To create an MAF AMX page as Content for an Application Feature:
-
Choose File > New and then MAF Page.
-
Complete the New MAF Page dialog, shown in Figure 3-21, by choosing the parent folder, for example
ViewContent
and entering a name in the File Name field. -
Select (or deselect) the Page Facets that are used to create a primary and secondary header and footer. Click OK.
For more information, see Section 6.2.2, "How to Use a Panel Page Component."
-
Click Finish. For more information using the AMX components, see Section 5.3.1.2, "Creating MAF AMX Pages." See also Section 4.11.1, "How to Define the Application Content."
To create an MAF AMX page as a Resource to an MAF application:
-
Choose File > New and then MAF Page.
-
Complete the Create MAF AMX Page dialog, shown in Figure 3-21, by entering a name in the File Name field. In the Directory field, enter the file location, which must be within the
public_html
folder of the application controller project. Click OK. -
Build the MAF AMX page. For more information, see Section 5.3.1.2, "Creating MAF AMX Pages."
3.2.5.2 How to Create MAF Task Flows
You can deliver the content for an application feature as an MAF task flow.
To create an MAF Task Flow as content for an application feature:
-
Choose File > New > Other.
-
In the New dialog, expand Oracle then expand Mobile Application Framework. Select MAF Task Flow and click Next.
-
Complete the New MAF Task Flow dialog, shown in Figure 3-22, by entering a name in File Name. Click OK.
-
Click Finish to build the task flow. See also Section 5.2, "Creating Task Flows."
3.2.5.3 What Happens When You Create MAF AMX Pages and Task Flows
Oracle Enterprise Pack for Eclipse places the MAF AMX pages and task flows in the ViewContent node of the view project, as shown by employeeList.amx
and emp-task-flow-definition.xml
in Figure 3-23. These artifacts are referenced in the maf-feature.xml
file as described in Section 4.7, "Configuring the Application Features within a Mobile Application."
The task flows are also listed under the view project MAF node.
Other resources, such as customized application splash screen (or launch) images and navigation bar images, are also housed in the Web Content node. For more information, refer to Table 3-3.
To manage the unbound task flows, Oracle Enterprise Pack for Eclipse generates the adfc-mobile-config.xml
file. Using this file, you can declaratively create or update a task flow by adding the various task flow components, such as a view (a user interface page), the control rules that define the transitions between various activities, and the managed beans to manage the rendering logic of the task flow.
Oracle Enterprise Pack for Eclipse places the MAF AMX page and task flow as application resources to the mobile application in the Web Content node of the application controller project. As illustrated in Figure 3-23, the file for the MAF AMX page is called application_resource.amx
and the task flow file is called ApplicationController-task-flow.xml
(the default name).
3.3 Migrating Mobile Applications
OEPE does not support the migration of ADF Mobile 1.x applications to MAF. If you need to migrate an ADF Mobile 1.x application to MAF, use JDeveloper for the migration, then import the application into OEPE. For more information about migrating ADF Mobile applications, see Section 3.3, "Migrating ADF Mobile Applications", in Developing Mobile Applications with Oracle Mobile Application Framework.