MAF Application and Project Files

Introduction to MAF Application and Project Files

An understanding of what files are generated in the ApplicationController and ViewController projects of the application is needed if you want to configure an application, application features, or files that a MAF application needs for deployment.

By default, JDeveloper creates a MAF application with two projects (ApplicationController and ViewController). The ApplicationController project contains application-wide resources such as a login page if you configure security for your MAF application. The ViewController project contains application feature resources such as HTML, AMX, or task flow files that render the content of an application feature.

Use the ViewController project to create or store artifacts that you may want to use in more than one MAF application. Consider, for example, a MAF skin that determines the look and feel of a MAF application. You may intend to reuse this artifact in multiple MAF applications. Similarly, you may want to share one or more data controls in multiple MAF applications. For this reason, create an additional ViewController project in your MAF application to store artifacts such as these that you may intend to share among multiple MAF applications. This additional ViewController project can be reused by packaging it into a FAR, as described in Reusing MAF Application Content .

See About the Application Controller Project-Level Resources and About the View Controller Project Resources.

JDeveloper also generates files within these projects that you use to configure your MAF application and application features or files that your MAF application needs when you deploy it to the targeted platform. Example C-1 shows the files that JDeveloper generates for a newly-created MAF application.

Two of the files that you use most frequently as you develop a MAF application are the maf-application.xml file (application configuration) and the maf-features.xml file (feature configuration). See About the MAF Application Configuration File and About the MAF Application Feature Configuration File.

Example C-1 Files in a Newly-Created MAF Application

Application1.jws
|   
+---.adf
|   \---META-INF
|           adf-config.xml
|           maf-application.xml
|           maf-config.xml
|           maf-plugins.xml
|           wsm-assembly.xml
|           
+---.data
|   +---00000000
|   |       00000000.jdb
|   |       je.lck
|   |       
|   \---ApplicationController
|       \---00000000
|               00000000.jdb
|               je.lck
|               
+---ApplicationController
|   |   ApplicationController.jpr
|   |   
|   +---adfmsrc
|   |   +---application
|   |   |       DataControls.dcx
|   |   |       
|   |   \---META-INF
|   |           adfm.xml
|   |           
|   +---public_html
|   \---src
|       +---application
|       |       LifeCycleListenerImpl.java
|       |       
|       \---META-INF
|               maf-skins.xml
|               
+---resources
|   +---android
|   |       display-hdpi-icon.png
|   |       display-land-hdpi-splashscreen.9.png
|   |       // Additional image files omitted for brevity
|   |       display-xxxhdpi-icon.png
|   |       
|   +---default
|   |       MissingIcon_144x144.png
|   |       
|   +---ios
|   |       Default-1104h@2x.png
|   |       Default-568h@2x.png
|   |       Default-667h@2x.png
|   |       Default-Landscape-621@2x.png
|   |       Default-LandscapeRetina.png
|   |       Default-LandscapeRetina@2x.png
|   |       Default-PortraitRetina.png
|   |       Default-PortraitRetina@2x.png
|   |       Default@2x.png
|   |       Icon-120.png
|   |       // Additional image files omitted for brevity
|   |       iTunesArtwork.png
|   |       
|   +---security
|   |       cacerts
|   |       java.security
|   |       
|   \---windows
|           BadgeLogo.scale-100.png
|           // Additional image files omitted for brevity
|           splashscreen.scale-100.png
|           
|           Square150x150Logo.scale-100.png
|           
|           Wide310x150Logo.scale-100.png
|           // Additional image files omitted for brevity
|           
+---src
|   \---META-INF
|           logging.properties
|           maf.properties
|           
\---ViewController
    |   ViewController.jpr
    |   
    +---public_html
    \---src
        \---META-INF
                maf-feature.xml

About the Application Controller Project-Level Resources

Files in the application controller project contain configuration information that describes the metadata of the MAF application, and can be accessed from the Application Resources pane of the Applications window.

JDeveloper generates the files for the MAF application in the application controller project. These files, described in Table C-1, contain configuration information describing the metadata of the MAF application. You access these files from the Application Resources pane of the Applications window, shown in the figure.

Figure C-1 MAF Application Artifacts Accessed from the Application Resources Pane

Description of "Figure C-1 MAF Application Artifacts Accessed from the Application Resources Pane"

The application controller project, 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. See About the View Controller Project Resources.

Table C-1 MAF Application-Level Artifacts Accessed Through Application Resources

Artifact(s)	File Location	Description
`maf-application.xml`	`application workspace directory\.adf\Meta-INF` For example: `JDevloper\mywork\application name\.adf\META-INF`	An XML file that defines application-level information. You can define the content for an application, its navigation behavior, and its user authentication requirements.
`maf-config.xml`	`application workspace directory\.adf\Meta-INF` For example: `JDeveloper\mywork\application name\.adf\META-INF`	Use to configure the default skin used for MAF applications. See Skinning MAF Applications.
Application images	`application workspace directory`\`Application Resources\resources\`	A set of images required for the deployment of applications. For Android and Windows, these include images for application icons and splash screens. For iOS, these include images for application icons. MAF applications that you deploy to iOS devices use a HTML page as the launch screen. The filename for each image indicates the purpose it serves. For example, use the `display-port-ldpi-splashscreen.9.png` image that appears under Android resources as a splash screen in portrait mode on Android devices. For information about how to override the application icons and splash screens for MAF applications you deploy to Android, see How to Add a Custom Image to an Android Application. For information about how to override the application icons for MAF applications you deploy to iOS, see Adding a Custom Image to an iOS Application. To change the launch screen for iOS devices, see Changing the Launch Screen for Your MAF Application on iOS.
`cacerts`	`application workspace directory`\`Application Resources\resources\Security\cacerts` For example: `JDeveloper\mywork\application name\resources\Security\cacerts`	The `cacerts` certificate file, a system-wide keystore that identifies the CA certificates to the Java virtual machine (JVM). You can update this file using the Java keytool utility. You can create a custom certificate file using keytool as described in Supporting SSL. Any certificate file must reside within the `Security` directory.
`logging.properties`	`application workspace directory\ src\.META-INF\logging.properties` For example: `JDeveloper\mywork\application name\src\META-INF\logging.properties`	Enables you to set the application error logging, such as the logging level and logging console. See Using and Configuring Logging.
`maf.properties`	`application workspace directory\src\.META-INF\maf.properties` For example: `JDeveloper\mywork\application name\src\META-INF\maf.properties`	The configuration file for the JVM. Use this file to configure the application startup and heap space allotment, as well as Java and JavaScript debugging options. See How to Enable Debugging of Java Code and JavaScript.
`adf-config.xml`	`application workspace directory\.adf\META-INF` For example: `JDeveloper\mywork\application\.adf\META-INF`	Used to configure application-level settings, including the Configuration Service parameters. See also Configuring End Points Used in MAF Applications .
`connections.xml`	`application workspace directory`\`.adf\META-INF` For example: `JDeveloper\mywork\application name\.adf\META-INF`	The repository for all of the connections defined in the MAF application.
`wsm-assembly.xml`	`application workspace directory`\`.adf\META-INF` For example: `JDeveloper\mywork\application name\.adf\META-INF`	Stores the web service policy definitions used for secured web services.

Tip:

Place code that supports application-wide functionality, such as an application-level lifecycle listener, in the application controller project.

Within the application controller project itself, JDeveloper creates the artifacts listed in Table C-2.

Table C-2 Application Controller Artifacts

Artifact(s)	File Location	Description
`LifeCycleListenerImpl.java`	`application workspace directory\ApplicationController\src\application` For example: `JDeveloper\mywork\application name\ApplicationController\src\application`	The default application lifecycle listener (ALCL) for the MAF application. See Using Lifecycle Listeners in MAF Applications .
`maf-skins.xml`	`application workspace directory\ApplicationController\src\META-INF` For example: `JDeveloper\mywork\application name\ApplicationController\src\META-INF`	Defines the available skins and also enables you to define new skins. See Skinning MAF Applications.
`adfm.xml`	`application workspace directory` `\ApplicationController\adfmsrc\META-INF` For example: `JDeveloper\mywork\application name\ApplicationController\adfmsrc\META-INF`	Maintains the paths (and relative paths) for the `.cpx`, `.dcx`, `.jpx`, and `.xcfg` files (registries of metadata).
`DataControls.dcx`	`application workspace directory\ApplicationController\adfmsrc\` For example: `JDeveloper\mywork\application name\ApplicationController\adfmsrc\`	The data controls registry. For information on using the DeviceFeatures data control, which leverages the services of the device, see Using Bindings and Creating Data Controls in MAF AMX . For information on the ApplicationFeatures data control, which enables you to create a springboard page that calls the embedded application features, see What You May Need to Know About Custom Springboard Application Features with MAF AMX Content.

About the View Controller Project Resources

The metadata files of the view controller project describe the resources at the application feature-level, and can be reused in other applications.

The view controller project (which is generated with the default name, ViewController) contains the resources for application features. Unlike the application controller project, the view controller 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. Furthermore, 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 MAF applications as described in Reusing MAF Application Content . 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. See What You May Need to Know About Feature Reference IDs and Feature IDs.

As shown in Table C-3, these resources include the configuration file for application features called maf-feature.xml.

Table C-3 View Controller Artifacts

Artifact(s) File Location Description

Artifact(s)	File Location	Description
`maf-feature.xml`	`application workspace directory\src\META_INF\maf-feature.xml` For example: `JDeveloper\mywork\application name\ViewController\src\META-INF`	A stub XML descriptor file that enables you to define application features. After you have configured the Mobile Preferences, as described in Installing Oracle Mobile Application Framework, you can deploy this application using the default deployment profile settings. See Deploying MAF Applications .
Application-Specific Content	`application workspace directory\ViewController\public_html` For example: `JDeveloper\mywork\application name\ViewController\public_html`	The application features defined in `maf-feature.xml` display in the `public_html` directory. Mobile content can include MAF AMX pages, CSS files, and task flows. Any custom images that you add to an application feature must be located within this directory. See What You May Need to Know About Selecting External Resources .

maf-feature.xml

application workspace directory\src\META_INF\maf-feature.xml

For example:

JDeveloper\mywork\application name\ViewController\src\META-INF

A stub XML descriptor file that enables you to define application features. After you have configured the Mobile Preferences, as described in Installing Oracle Mobile Application Framework, you can deploy this application using the default deployment profile settings. See Deploying MAF Applications .

Application-Specific Content

application workspace directory\ViewController\public_html

For example:

JDeveloper\mywork\application name\ViewController\public_html

The application features defined in maf-feature.xml display in the public_html directory. Mobile content can include MAF AMX pages, CSS files, and task flows. Any custom images that you add to an application feature must be located within this directory. See What You May Need to Know About Selecting External Resources .

About the MAF Application Configuration File

The maf-application.xml file not only specifies the basic configuration of a MAF application but also helps users create user preferences pages for the MAF application.

The maf-application.xml file specifies the basic configuration of the MAF application by designating its display name, a unique application ID (to prevent naming collisions) and selecting the application features that display on the springboard of the MAF application at runtime. Furthermore, the maf-application.xml file enables you to create the user preferences pages for the MAF application.

This file, which is generated by JDeveloper after you complete the application creation wizard as described in Creating a MAF Application, contains the elements listed in Table C-4.

Table C-4 Elements of the Application Descriptor File

Element	Description
`<adfmf:application>`	The root element of `maf-application.xml`.
`<adfmf:description>`	A description of the application.
`<adfmf:featureReference>`	A feature reference denotes which of the application features packaged in the FAR (Feature archive file) or defined in the `maf-feature.xml` file is relevant to the content of the MAF application. You define the character and content of MAF applications by selecting feature references. See Reusing MAF Application Content .
`<adfmf:preferences>`	Enables you to set the user preference options and behavior at the application level. You can also set how user preferences display and behave for the application features in the `maf-feature.xml` file. See Enabling User Preferences.
`<adfmf:login>`	Enables you to set the login page for an application feature. See Securing MAF Applications .
`<adfmf:navigation>`	Enables you to define the behavior of the navigation bar and the springboard. A springboard is a home page in which all of the application icons and labels for the embedded application features are organized in a List View. A springboard provides a top-level view of all of the applications available to a user, who can page through and select applications. See Configuring the Application Navigation.

About the MAF Application Feature Configuration File

The maf-feature.xml file configures the application features that the <adfmf:featureReference> elements in the MAF application's maf-application.xml file references.

Example C-2 shows the People and Organization application features of the WorkBetter sample application in that application's maf-feature.xml file.

The <adfmf:features> root element in the maf-feature.xml file accepts one or more <adfmf:feature> elements where you define the properties of the application feature(s) in your MAF application. In Example C-2, values are provided for the properties that define the name and identify of the People and Organization application features in addition to the icons that render in the springboard and navigation bars for these application features in the WorkBetter sample application. Furthermore, the <adfmf:feature> elements reference the content that the application features render. The People and Organization application features reference task flows, .CSS and .JS files.

MAF applications implement security at the application feature level. One step in securing an application feature is to require that end users be authenticated before they can access the application feature. You do this by configuring the Enable Security property (securityEnabled) for the application feature in the maf-feature.xml file. See Configuring Security for MAF Applications.

Table C-5 Child Elements of <Feature> Element

Element	Description
`<adfmf:content>`	Describes the format that the application feature uses for a particular device or user. The content (generally, the user interface) of an application feature can be written as MAF AMX pages, HTML5 pages, or be delivered from web pages hosted on a remote web server. For information on designating content as a web application, see Implementing Application Feature Content Using Remote URLs .
`<adfmf:constraint>`	Determines whether a given application feature can be displayed in the application at runtime. Constraints can be used to allow or prevent the use of an application feature based on such criteria as user roles or device properties. See Setting Constraints on Application Features .

Example C-2 WorkBetter Sample Application's maf-feature.xml File

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adfmf="http://xmlns.oracle.com/adf/mf">
<adfmf:feature id="People" name="People" icon="images/people.png" image="images/people.png">
    <adfmf:content id="People.1">
      <adfmf:amx file="People/taskflow.xml#taskflow">
        <adfmf:includes>
          <adfmf:include type="StyleSheet" file="css/WorkBetter.css" id="i1"/>
          <adfmf:include type="JavaScript" file="js/customsearch.js" id="i2"/>
        </adfmf:includes>
      </adfmf:amx>
    </adfmf:content>
  </adfmf:feature>
  <adfmf:feature id="Organizations" name="Organizations" icon="images/departments.png"
                                                         image="images/departments.png">
      <adfmf:content id="Organizations.1">
        <adfmf:amx file="Organizations/taskflow.xml#taskflow">
          <adfmf:includes>
            <adfmf:include type="StyleSheet" file="css/WorkBetter.css" id="i3"/>
            <adfmf:include type="JavaScript" file="js/customsearch.js" id="i4"/>
          </adfmf:includes>
        </adfmf:amx>
      </adfmf:content>
  </adfmf:feature>
  ...
  </adfmf:features>