2 Getting Started with MAF Application Development

This chapter describes how to create a MAF application in OEPE and introduces the files and other artifacts that OEPE generates when you create the application.

This chapter includes the following sections:

2.1 Introduction to the MAF Development Environment

The Oracle Mobile Application Framework (MAF) extension in OEPE provides a number of editors and wizards to facilitate the development, testing, and deployment of MAF applications. Using these wizards, you can create a MAF application, define one or more application features, add content to an application feature, and deploy the MAF application to a test environment or device in a relatively short amount of time.

Figure 2-1 shows the WorkBetter sample application in OEPE's MAF Application Editor where a number of the items that you use to develop MAF applications are identified:

  1. The MAF Application Editor (invoked from the assembly project), used to specify the MAF application's name, the default navigation menus (navigation bar or springboard) that the application renders, security, and device access options for the application.

  2. The MAF Features Editor (invoked from the view project), where you define the application features that your MAF application contains.

  3. By default, OEPE creates a MAF application with two data controls, one in the application project applicationApplication and one in the view project applicationView. These data controls expose operations that you can drag to a MAF AMX page where OEPE displays context menus to complete configuration of the operation when you drop it on the page. For example, dragging the hideNavigationBar() operation to a page prompts OEPE to display a context menu where you configure a control for end users to hide an application's navigation bar.

The WorkBetter sample application is one of a number of sample applications that MAF provides to demonstrate how to create mobile applications using MAF. For more information, see Section 1.4, "MAF Sample Applications."

OEPE proposes default options in the wizards so that you can create a MAF application with one application feature displaying one MAF AMX page as follows:

  1. Create a MAF application, as described in Section 2.3, "Creating a MAF Application."

  2. Define an application feature for the MAF application and add content, as described in Section 2.4, "Defining Application Features for a MAF Application."

  3. Add content to the application feature, as described in Section 2.5, "Adding Content to an Application Feature."

Figure 2-1 MAF Application Editor

This image is described in the surrounding text

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.

As shown in Figure 2-1, the MAF Application Editor is located in the Project Explorer under the application and MAF node. It edits the maf-application.xml file.

The MAF Feature Editor is located in Explorer under the view project and MAF node. It edits the maf-feature.xml file.

2.1.1 About the MAF Application Editor

The MAF Application Editor enables you to configure the maf-application.xml file to set the basic configuration of the mobile application by designating its display name, a unique application ID (to prevent naming collisions) and also by selecting the application features that will display on the application springboard (the equivalent of a home page on a smartphone). Further, this editor enables you to create the user preferences pages for the mobile application. The editor is described in Section 2.3, "Creating a MAF Application,".

Figure 2-2 Application Features Displaying in the Mobile Application's Springboard

This image is described in the surrounding text

You can modify these elements declaratively using the MAF Application Editor, shown in Figure 2-3, or manually using the XML Editor or the Source editor. You can use these approaches interchangeably.

Figure 2-3 The MAF Application Editor for the maf-application.xml File

This image is described in the surrounding text

2.1.2 About the MAF Feature Editor

The MAF Feature Editor enables you to add features to your application. You create the features with this editor, and specify the characteristics (ID, name, description, vendor information, version, lifecycle event listener, security, and images for navigation and for the springboard) through the editor.

2.2 Using the Oracle MAF Perspective

In Eclipse, a perspective is a collection of views arranged in a specific layout that is suitable for a type of development. MAF has its own perspective which you should use when you are developing MAF applications. It gives you access to menu and toolbar options that we describe elsewhere in this manual.

To change to the Oracle MAF perspective:

  1. In the IDE, click Window > Open Perspective > Other.

    Alternatively, click This image is described in the surrounding text.

  2. In the Open Perspectives dialog, choose Oracle MAF. Click OK.

2.3 Creating a MAF Application

You create a MAF application using the creation wizards in OEPE.

2.3.1 How to Create a MAF Application

You create a MAF application in OEPE using the application creation wizard.

To create a MAF application:

  1. In the main menu, choose File > New, and then select MAF Application.

  2. In the MAF Application wizard, enter application details like name and deployment targets.

  3. Click Finish.

2.3.2 What Happens When You Create an MAF Application

OEPE creates a MAF application with three projects and two data controls (for application features and device features), as shown in Figure 2-4. It also creates files that you use to configure your MAF application and files that your MAF application needs when you deploy it to the Android and/or iOS platform(s).

For more information about the files and artifacts that OEPE generates when you create a MAF application, see Appendix C, "MAF Application and Project Files.".

Figure 2-4 Generated MAF Application Artifacts

This image is described in the surrounding text

Note:

If you have the Error Log open when you create a MAF application you will see messages similar to: 
org.eclipse.core.runtime.CoreException: Illegal install location
D:\p4\depots\OEPE\tools-eclipse\annex\maf-2.1\install for vmInstall
oracle.eclipse.tools.maf.JVMCDCv201 contributed by
oracle.eclipse.tools.maf.dt.v201: Associated MAF runtime is not installed.

There will be one entry for each release of MAF with OEPE. You can safely ignore them.

2.4 Defining Application Features for a MAF Application

A MAF application must have at least one application feature. The WorkBetter sample application, for example, includes four application features (Dashboard, People, Organizations, and Springboard). Figure 2-5 shows three of these application features displaying in that application's custom springboard.

Figure 2-5 Application Features in the WorkBetter Application's Springboard

This image is described in the surrounding text

2.4.1 How to Define an Application Feature

You define an application feature for a MAF application using the MAF Application Editor.

To define an application feature for a MAF application:

  1. In the Project Explorer, expand the view project, applicationView and MAF and double-click MAF Feature Editor.

  2. In the Mobile Features page, click the Add icon.

  3. In the New Object dialog, select Feature and

    Complete entries in the New Object dialog as follows:

    • Type of new object: Feature.

    • Feature ID: Enter a unique ID for the application feature or accept the value that OEPE generates.

  4. Click OK.

2.5 Adding Content to an Application Feature

One of the tasks to do after you define an application feature is to add content to the application feature. In the Outline section of the editor, expand the new node for the feature and click the Add icon. Choose the type of new feature and complete the information required:

  • MAF AMX Page: Choose this content type if you want the application feature to render MAF AMX pages.

  • MAF Task Flow: Choose this content type if you want the application feature to render a collection of activities that make up a task flow. Examples of activities that you can include in a task flow are views (to display MAF AMX pages), method calls (to invoke managed bean methods), and task flow calls (to call other task flows).

  • Local HTML: Choose if you want the application feature to render HTML page.

  • Remote URL: Choose if you want the application feature to render content from a remote URL.

The general steps to add a content type to an application feature are the same for all content types. That is, you choose the type of content to add to the application feature in the Content tab of the Features page of the maf-features.xml file's overview editor. For the specific steps for each content type, see Chapter 5, "Defining the Content Type of MAF Application Features."

2.6 Adding Application Features to a MAF Application

Application features are automatically added to the MAF application when you create them using the MAF Feature Editor.

2.6.1 How to Add an Application Feature to a MAF Application

To work with the features in the application:

  1. In the Project Explorer, expand the assembly project, application and MAF and double-click MAF Application Editor.

  2. In the outline, select Registered Features.

  3. In the Registered Features pane you can see the features associated with the application.

Select a feature to define how it works in the application. For example, you can specify that the feature is available on the navigation bar, or on the springboard.

2.6.2 What You May Need to Know About Feature Reference IDs and Feature IDs

OEPE writes an entry in the maf-application.xml file to reference the application feature that you add to the MAF application.

In the maf-application.xml file, the refId attribute of an <adfmf:featureReference> element identifies the corresponding application feature in the maf-feature.xml file. For this reason, the value of the refId attribute for a <adfmf:featureReference> element in the maf-application.xml file must match the value of the id attribute defined for the <adfmf:feature> element in the maf-feature.xml file.

Use a naming convention consistently to make sure that application feature IDs are unique. Application feature IDs must be unique across a MAF application.

The example below shows the entries for the People application feature in the WorkBetter sample application's maf-application.xml and maf-feature.xml files.

<!-- Feature Reference ID in maf-application.xml File -->
<adfmf:featureReference id="fr2" refId="People"/>
...
<!-- Feature ID in maf-feature.xml File -->
<adfmf:feature id="People" name="People" icon="images/people.png" image="images/people.png">
...

2.7 Creating MAF AMX Pages and MAF Task Flows

As described in Chapter 11, "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 2-6 illustrates the declarative development of an MAF AMX page, which involves selecting options in the Palette and adding them to the MAF AMX page.

Figure 2-6 Creating an MAF AMX Page

The surrounding text describes this image.

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 2-7, 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 Figure 11-0 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 2-8) 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 2-8, 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.

Figure 2-7 MAF Task Flow

The surrounding text describes this image.

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 2-8 shows the menu options available from the File menu.

Figure 2-8 Options for Creating Resources for Application Features

This image is described in the surrounding text

Additional options are available from File > New > Other (see Figure 2-9). In the New dialog, expand Oracle then expand Mobile Application Framework

Figure 2-9 Wizards for Creating Resources for Application Features

This image is described in the surrounding text

2.7.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 5.2, "Defining the Application Feature Content as Remote URL or Local HTML."

To create an MAF AMX page as Content for an Application Feature:

  1. Choose File > New and then MAF Page.

  2. Complete the New MAF Page dialog, shown in Figure 2-10, by choosing the parent folder, for example ViewContent and entering a name in the File Name field.

    Figure 2-10 Creating an MAF AMX Page in an Application Controller Project

    This image is described in the surrounding text

  3. 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 12.2.2, "How to Use a Panel Page Component."

  4. Click Finish. For more information using the AMX components, see Section 11.3.1.2, "Creating MAF AMX Pages." See also Section 5.2, "Defining the Application Feature Content as Remote URL or Local HTML."

To create an MAF AMX page as a Resource to an MAF application:

  1. Choose File > New and then MAF Page.

  2. Complete the Create MAF AMX Page dialog, shown in Figure 2-10, 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.

  3. Build the MAF AMX page. For more information, see Section 11.3.1.2, "Creating MAF AMX Pages."

2.7.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:

  1. Choose File > New > Other.

  2. In the New dialog, expand Oracle then expand Mobile Application Framework. Select MAF Task Flow and click Next.

  3. Complete the New MAF Task Flow dialog, shown in Figure 2-11, by entering a name in File Name. Click OK.

    Figure 2-11 Creating an MAF Task Flow in a View Controller Project

    This image is described in the surrounding text

  4. Click Finish to build the task flow. See also Section 11.2.3, "Task Flow File."

2.7.3 What Happens When You Create MAF AMX Pages and Task Flows

OEPE 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 2-12. These artifacts are referenced in the maf-feature.xml file.

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 ViewContent node.

To manage the unbound task flows, OEPE 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.

Figure 2-12 MAF AMX Pages and Task Flows within the View Project

This image is described in the surrounding text

OEPE places the MAF AMX page and task flow as application resources to the mobile application in the ViewContent node of the application controller project. As illustrated in Figure 2-12, 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).

2.8 Containerizing a MAF Application for Enterprise Distribution

At the time of deployment, you can choose to wrap the MAF application with the OMSS (Oracle Mobile Security Suite) to take advantage of its enterprise mobile application management capabilities. OMSS allows secure access to corporate apps and data from mobile devices while preserving a rich user experience. Its Mobile Security Container creates the enterprise Workspace on any iOS or Android device, corporate-owned or personal. Employees get seamless access to corporate data and apps with enterprise-grade security and single sign-on authentication.

With the Mobile Security App Containerization Tool, you can add a standardized security layer to native mobile apps. The containerization process is simple and injects the following security services into your app.

  • Secure data transport: An encrypted AppTunnel through Mobile Security Access Server to application back-end resources behind an enterprise firewall.

  • Authentication: Managed by the Secure Workspace app and provides single sign-on across apps in the secure workspace.

  • Secure data storage: Encrypted storage of app data, including files, database, app cache and user preferences.

  • Data leakage controls: The ability to restrict file sharing and copy paste to only other trusted apps. This enables you to control the sharing of data, including e-mail, messaging, printing and saving.

  • Dynamic policy engine: More than 50 detailed app controls, including authentication frequency, geo and time fencing as well as remote lock and wipe.

The OMSS single sign-on authentication and user identity propagation to MAF app services is supported only for applications configured to use the Web SSO authentication server type for login connections. Applications using HTTP Basic or OAuth authentication will be required to log in to the MAF app after the Container authentication is successful. For details about these authentication types and the role they play in OMSS, see Section 29.5.11, "What You May Need to Know About Login Connections and Containerized MAF Applications."

The containerization process is simple and does not change the way you develop the MAF application. In fact, you should not change application code specifically with containerization in mind. You develop the MAF application the same way whether or not you intend to deploy with OMSS containerization enabled.

When you deploy the application with OMSS containerization enabled, OEPE runs the Mobile Security App Containerization Tool provided by OMSS to containerize the MAF application.

After deployment, the MAF app developer works with the OMSS system administrator to get the app added to OMSS Mobile App Catalog and to configure appropriate policies. For details, see the "Managing Mobile Apps" chapter in Administering Oracle Mobile Security Suite.

When the user launches the containerized MAF application, the Secure Workspace app redirects to the Mobile Security Container, which performs SSO authentication before handing the session back to the MAF application. The containerized MAF application does not require VPN to connect to internal websites or services. Instead a secure AppTunnel is established between the application and Mobile Security Access Server (MSAS), which provides secure transport for accessing internal sites and services that have been registered for access by mobile device users.

For more information about how OMSS containerization affects MAF applications, see these sections:

In the OMSS documentation library, refer to the following list of resources for details about OMSS administration tasks related to mobile devices and workspace containers.

  • For background information about OMSS, see the "Understanding Oracle Mobile Security Suite" chapter in Administering Oracle Mobile Security Suite.

  • For details about how system administrators use the OMSS Mobile Security Manager console to enroll the MAF application user's mobile device and workspace, see the "Enrolling Devices and Workspaces" chapter in Administering Oracle Mobile Security Suite.

  • 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 Mobile Apps" chapter in Administering Oracle Mobile Security Suite.

  • For details about how system administrators use the OMSS Mobile Security Manager console to manage access to a corporate file shared by MAF application capabilities, see the "Managing Mobile Security Policies" chapter in Administering Oracle Mobile Security Suite.

In the OMSS documentation library, refer to the following list of resources for details about MSAS administration tasks related to securing resources and authentication.