The Mobile & Digital Assistant Blog covers the latest in mobile and conversational AI development and engagement

10 Tips for getting started with Oracle MAF

Graeme Mawson
Senior Principal Product Manager

If you’re getting started with Oracle Mobile Application Framework (MAF) development, you can find a growing number of excellent instructional videos on the Oracle Mobile Platform YouTube channel. These videos will teach you how to design and develop MAF apps, consume web services, use the embedded SQLite database and design killer UIs. 

But what about the little tips and tricks that will make life easier as you’re learning your way around MAF? Let’s take a look at some of those now.

Tip #1: Install the MAF extension and JDeveloper patch as Administrator on Windows and wait for JDeveloper to restart

Installing MAF is a two-part process. To start with you install JDeveloper, then you need to install the MAF extension using the JDeveloper Update Center. This will require you to install a JDeveloper patch as well. It is important to select both of these at the same time within Check For Updates.

On Windows machines, you must install JDeveloper as a user with Administrator privileges.  Make sure that when you run JDeveloper to install the MAF extension, this is also done as a user with Administrator privileges.

JDeveloper should automatically restart to apply the MAF extension and JDeveloper patch.  Don't get impatient and start it again yourself, otherwise these may not be installed correctly and you may either get an error such as “adfmf-feature.xml not found” in your deployment log, or your app may freeze at the splashscreen with an error such as “[SEVERE - oracle.adfmf.framework - EmbeddedFeatureInformation - constructor] Invalid application state” in your application log.

You can verify that the requisite JDeveloper patch is installed correctly by checking the version of your oracle.adfm extension, which should end with 140623.0901. Select Help > About and click on the Extensions tab, then type “adfm” into the search box to get a screen similar to the following:

Search for “maf” to verify the installed oracle.maf extension version.

Tip #2: Copy zipalign if using Android SDK Tools 23

MAF 2.0.0 does not officially support Android SDK Tools revision 23, however if you download the Android SDK from scratch, it will contain only revision 23 of the SDK Tools.  You could download and install revision 22.6 for Windows, Mac or Linux, but there is also an easier way forward.

The issue reported by JDeveloper is similar to “Cannot run program zipalign, No such file or directory”.  If you copy the file zipalign from your Android SDK build-tools/19.1/ folder into your Android SDK tools/ folder, then JDeveloper will happily use this file.

The latest release of Oracle Enterprise Pack for Eclipse (OEPE) provides support for revision 23 and we are currently working on providing the same for JDeveloper.

Tip #3: Remove spaces from your application path

JDeveloper does not like spaces in your MAF application path, so to avoid an “Illegal character in path” error, make sure that you store your MAF apps in a location that has no spaces in the path.   When migrating an app from ADF Mobile, you will need to rename any folders that have a space in the name, or copy the app into a new folder without spaces.

Tip #4: Always enable network access

Most MAF apps will require network access to begin with, but since network access cannot be disabled on iOS, you may forget to enable it in maf-application.xml and then find your app doesn’t work on Android.

One indicator that you forgot to enable network access is that your Android app does not pause to connect to the JDeveloper Remote Debugger even when you have enabled Java debugging.

To enable network access, select the Device Access tab within maf-application.xml, then select the Network permission and save:

Oracle Enterprise Pack for Eclipse (OEPE) enables network access in debug mode automatically and we intend to enable network access by default in subsequent releases of MAF for both Eclipse and JDeveloper.

Tip #5: Remove the .data folder to purge the cache

JDeveloper provides a Build > Clean All function that removes the application’s build artefacts.  However JDeveloper also caches information in a .data folder that is not removed by the Clean All function.

If you are migrating an app from ADF Mobile, perform a Clean All and manually remove the .data folder before building and deploying your migrated app.

This approach can also be used in circumstances where you see a strange error message, such as missing files that are no longer used by your application.

We are considering the addition of a Flush All function to JDeveloper to alleviate the need to remove the .data folder manually.

Tip #6: Set the Compiler Character Encoding Option to ASCII, UTF-8 or UTF-16

MAF only supports XML encoded in the ASCII, UTF-8 or UTF-16 character sets.  By default, if your development machine’s locale is set to use a double-byte character set (for example Chinese or Japanese), then JDeveloper inherits this setting and uses it to encode the XML files in your MAF application.

Without the correct setting, your MAF apps may hang at the splash screen.

You should manually change the encoding option within the Project Properties for each JDeveloper project that you create, as follows:

Within Eclipse, you should set the XML Files > Encoding preference, which will be applied to all files, as follows:

Tip #7: Use Feature ID when calling JavaScript from Java

If you call JavaScript from your Java code via AdfmfContainerUtilities.invokeContainerJavaScriptFunction(), remember to pass in the feature ID, not the feature name.   In many cases these are the same, but if not, your JavaScript will not be invoked.  To retrieve the feature ID, use AdfmfJavaUtilities.getFeatureId().

Tip #8: Decode deployment errors by running Xcode commands directly

The MAF deployment log in Eclipse is quite verbose, but deploying MAF apps from JDeveloper can sometimes lead to a generic error message such as “Command-line execution failed (Return code: 65)”.

To determine the underlying cause of the error, you can run the Xcode command directly in a Terminal window.  In the deployment log, locate the last line that starts with “Command-line executed from path:” and in your Terminal window, change directory to the specified folder.  The following line in the deployment log will start with “Command-line executed:”.  Copy and paste the referenced command into your Terminal window, then edit the command to place quotes around the signing identity and execute it.  This will lead to a more detailed error message that should help to pinpoint the error.

The most common error deploying to an iOS device is that the application Id doesn’t match your iOS developer certificate.  By default, new MAF applications have an Id that starts with “com.company” and you should modify this in the Application tab of maf-application.xml.

After saving this file, check that your Application Bundle Id has been updated with the new value in your Deployment Profiles, which are located via Application > Application Properties > Deployment.  The Application Bundle Id is listed under iOS Options for iOS profiles, or Android Options for Android profiles.

Tip #9: Use the debugger; statement to fast-track your JavaScript debugging

Both Apple and Google have provided excellent JavaScript debugging capabilities via Safari and Chrome, respectively.  The Oracle A-Team has written comprehensive articles for Debugging MAF apps on Android and Debugging MAF apps on iOS, so be sure to check them out.

If you are finding it hard to locate your JavaScript source code within Safari or Chrome to set a breakpoint, for example if it is embedded within an AMX page, there is a handy trick.  Wherever you enter a debugger; statement in your JavaScript, the debugger will break at that point and the source code will be displayed.

Tip #10: Get involved in the MAF Community

If you face any issues or have any questions, draw on the collective wisdom of Oracle MAF Community users.  Read the blogs, post to the forum.  And remember to give back to the community when you learn something that could be helpful to others.


Join the discussion

Comments ( 2 )
  • guest Wednesday, July 30, 2014

    Thanks for tips....

  • Theresa Strepek Thursday, May 7, 2015

    Great share @Graeme Mawson! Many of these tips are the difference between success & failure. I've use them for a year...

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.