B Local HTML and Application Container APIs

This chapter describes the MAF JavaScript API extensions, the MAF Container Utilities API, and how to use the AdfmfJavaUtilities API for HTML application features, including custom HTML springboard applications.

This chapter includes the following sections:

• Using MAF APIs to Create a Custom HTML Springboard Application Feature

• The MAF Container Utilities API

• Accessing Files Using the getDirectoryPathRoot Method

Using MAF APIs to Create a Custom HTML Springboard Application Feature

Call JavaScript API extensions to add navigation functions to a custom springboard page authored in HTML.

Using JavaScript to call the JavaScript API extensions enables you to add the navigation functions to a custom springboard page authored in HTML. As stated in What You May Need to Know About Custom Springboard Application Features with HTML Content, you can enable callbacks and use Apache Cordova by including methods in the JavaScript <script> tag. The following example illustrates using this tag to call Cordova.

...
<script type="text/javascript">if (!window.adf) window.adf = {}; 
                                   adf.wwwPath = 
 "/~maf.device~/www/";</script> 
 <script type="text/javascript" src="/~maf.device~/www/js/base.js"></script>
...

It is recommended that you use the virtual path /~maf.device~/ when including base.js so that the browser will identify the request as being for a MAF resource and not for the remote server. This approach works in both remote as well as local HTML pages and is the best way to include base.js in an HTML feature (regardless of where it is being served from). See Enabling Remote Applications to Access Container Services.

Tip:

To access (and determine the location of) the www/js directory, you must first deploy a MAF application and navigate to the deploy directory. The www/js directory resides within the platform-specific artifacts generated by the deployment. For iOS deployments, the directory is located within the temporary_xcode_project directory. For Android deployments, this directory is located in the assets directory of the Android application package (.apk) file. For a Windows deployment in the Release mode, the directory location is appLocationOnMachine\deploy\deploymentprofilename\release\MafTemplate\www\js. See also What You May Need to Know About Custom Springboard Application Features with HTML Content.

Note:

Because the path does not exist during design time, JDeveloper notes the JavaScript includes in the source editor as an error by highlighting it with a red, wavy underline. This path is resolved at runtime.

The MAF extension to the Cordova API enables the API of the mobile device to access the configuration metadata in the maf-feature.xml and maf-application.xml files, which in turn results in communication between the mobile device and the MAF infrastructure. These extensions also direct the display behavior of the application features.

For information on the default MAF springboard page, springboard.amx, and about the ApplicationFeatures data control that you can use to build a customized springboard, see What You May Need to Know About Custom Springboard Application Features with MAF AMX Content.

About Executing Code in Custom HTML Pages

Custom HTML pages can invoke their own code after MAF has loaded by listening to the showpagecomplete event on the handlePageShown callback function.

The following example illustrates a script defining the showpagecomplete event on the handlePageShown callback function. By listening to this event using standard DOM (Document Object Model) event listening, custom HTML pages (such as login pages) can invoke their own code after MAF has loaded and displayed the page for the first time.

<script>
        function handlePageShown()
        {
          console.log("Page is shown!");
        }
        document.addEventListener("showpagecomplete", handlePageShown, false);
</script>

Note:

The showpagecomplete event guarantees the appropriate MAF state; other browser and third-party events, such as load and Cordova's deviceready, may not. Do not use them.

The MAF Container Utilities API

The methods of the MAF Container Utilities API provide MAF applications with such functionality as navigating to the navigation bar, displaying a springboard, or displaying application features. You can use these methods at the Java and JavaScript layers of MAF.

In Java, the Container Utilities API is implemented as static methods on the AdfmfContainerUtilities class, which is located in the oracle.adfmf.framework.api package. The following example illustrates calling the gotoSpringboard method. For information on oracle.adfmf.framework.api.AdfmfContainerUtilities, see Java API Reference for Oracle Mobile Application Framework.

import oracle.adfmf.framework.api.AdfmfContainerUtilities;
...
AdfmfContainerUtilities.gotoSpringboard();
...

Using the JavaScript Callbacks

JavaScript being asynchronous has two callback functions added for every function: a success callback that returns results, and a failed callback that returns exceptions.

The signatures of Java and JavaScript both match. In Java, they are synchronous and return results directly. Because JavaScript is asynchronous, there are two callback functions added for every function: a success callback that returns the results and a failed callback that returns any exception that is thrown. Within a Java method, the success value is returned from the function, or method, and the exception is thrown directly from the method. The pseudocode in the following example illustrates how a call with no arguments, public static functionName() throws, is executed within Java using try and catch blocks.

...
 try {
    result = AdfmfContainerUtilities.functionName();
 }
 catch() {
    ...
 }

...

Because JavaScript calls are asynchronous, the return is required through the callback mechanism when the execution of the function is complete. The pseudocode in the following example illustrates the signature of the JavaScript call.

adf.mf.api.functionName(
           function(successFunction, failureFunction ) { alert("functionName complete"); },
           function(successFunction, failureFunction ) { alert("functionName failed with " + 
                                                         adf.mf.util.stringify(failureFunction); }
);

JavaScript calls cannot return a result because they are asynchronous. They instead require a callback mechanism when the execution of the function has completed. The signature for both the success and failed callbacks is function(request, response), where the request argument is a JSON representation for the actual request and the response is the JSON representation of what was returned by the method (in the case of success callback functions) or, for failed callback functions, a JSON representation of the thrown exception.

Note:

The callback functions must be invoked before subsequent JavaScript calls can be made to avoid problems related to stack depth or race conditions.

The pseudocode in the following example illustrates how a call with one or more arguments, such as public static <return value> <function name>(<arg0>, <arg1>, ...) throws <exceptions>, is executed within Java using a try-catch block.

try {
   result = AdfmfContainerUtilities.<function_name>(<arg0>, <arg1>, ...);
}
catch(<exception>) {
   ...
}

For information on how to invoke MAF JavaScript APIs from pages defined as local HTML or remote URL, see Enabling Remote Applications to Access Container Services.

Using the Container Utilities API

Call the methods in the list to use the Container Utilities API.

The Container Utilities API provides the following methods:

• getApplicationInformation—Retrieves the metadata for the MAF application.

• gotoDefaultFeature—Activates the default application feature.

• gotoFeature—Activates a specific application feature.

• getFeatures—Retrieves the application features.

• getFeatureByName—Retrieves information about the application feature using the application feature's name.

• getFeatureById—Retrieves an application feature using its ID.

• resetFeature—Resets the application feature to the same state as when it was loaded.

• resetApplication—Resets the application.

• gotoSpringboard—Activates the springboard.

• showSpringboard—Shows the springboard

• hideSpringboard—Hides the springboard

• showNavigationBar—Displays the navigation bar.

• hideNavigationBar—Hides the navigation bar.

• showPreferences—Displays the preferences page.

• invokeMethod—Invokes a Java method.

• invokeContainerMethod—Invokes a native method on the specified class with the given arguments.

• invokeContainerJavaScriptFunction—Invokes a JavaScript method.

• sendEmail—Displays the mobile device's email interface.

• sendSMS—Displays the mobile device's text messaging (SMS) interface.

The Container Utilities API also include methods for placing badges and badge numbers on applications. See Application Icon Badging.

getApplicationInformation

The getApplicationInformation method returns an ApplicationInformation object that contains metadata, such as the application ID and application name, about the application.

Within Java, this method is called as follows:

public static oracle.adfmf.framework.ApplicationInformation 
              getApplicationInformation()
              throws oracle.adfmf.framework.exception.AdfException

The following example illustrates calling this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
     try {
        ApplicationInformation ai = AdfmfContainerUtilities.getApplicationInformation();
        String applicationId = ai.getId();
        String applicationName = ai.getName();
        String vendor = ai.getVendor();
        String version = ai.getVersion();
        ...
     }
     catch(AdfException e) {
        // handle the exception
     }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void getApplicationInformation(success, failed)

The success callback must be in the form of function(request, response), where the request argument contains the original request and the response argument contains the associated AdfmfContainerUtilities method's return value, which is the ApplicatiaonInformation object containing application-level metadata. This includes the application name, vendor, version, and application ID.

The failed callback must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions to retrieve the application information.

adf.mf.api.getApplicationInformation(
           function(req, res) { alert("getApplicationInformation complete"); },
           function(req, res) { alert("getApplicationInformation failed with " +
                                      adf.mf.util.stringify(res); }
);

gotoDefaultFeature

The gotoDefaultFeature method requests that MAF display the default application feature, the feature that appears when the application starts.

Note:

This method may not be able to display an application feature if it has authentication- or authorization-related problems.

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void gotoDefaultFeature(success, failed)

The success callback function must be in the form of function(request, response), where the request argument contains the original request and the response argument contains the associated AdfmfContainerUtilities method's return value (void).

The failed callback function must be in the form of function(request, response), where the request argument contains the original request and the response argument contains the error.

The following example illustrates using these callbacks to call the default application feature.

adf.mf.api.gotoDefaultFeature(
          function(req, res) { alert("gotoDefaultFeature complete"); },
          function(req, res) { alert("gotoDefaultFeature failed with " +
                                      adf.mf.util.stringify(res); }
);

gotoFeature

The gotoFeature method requests that MAF display the application feature that is identified by its ID.

Note:

This method may not be able to display an application feature if it has authentication- or authorization-related problems.

Within Java, this method is called as follows:

public static void gotoFeature(java.lang.String featureId)
                   throws oracle.adfmf.framework.exception.AdfException

This method's parameter, as shown in the following example, is the ID of the application feature.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.gotoFeature("feature.id");
   }
   catch(AdfException e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void gotoFeature(featureId, success, failed)

The featureId parameter is the application feature ID. This parameter activates the success callback function and must be in the form of function(request, response), where the request contains the original request and the response contains the associated AdfmfContainerUtilities method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions to call an application feature.

adf.mf.api.gotoFeature("feature0",
          function(req, res) { alert("gotoFeature complete"); },
          function(req, res) { alert("gotoFeature failed with " +
                               adf.mf.util.stringify(res); }
);

getFeatures

The getFeatures method returns an array of FeatureInformation objects representing the available application features that a custom springboard implementation can use.

This method returns an array of FeatureInformation objects that represent the available application features. The returned metadata includes the feature ID, the application feature name, and the file locations for the image files used for the application icons. This call enables a custom springboard implementation to access the list of application features that are available after constraints have been applied.

Note:

These application features would also display within the default springboard.

Within Java, this method is called as follows:

public static oracle.adfmf.framework.FeatureInformation[] getFeatures()
              throws oracle.adfmf.framework.exception.AdfException

The following example illustrates using this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
  ...
   try {
      FeatureInformation[] fia = null;
      fia = AdfmfContainerUtilities.getFeatures();
 
      for(int f = 0; f < fia.length; ++f) {
           FeatureInformation fi = fia[i];
           String featureId = fi.getId();
           String featureName = fi.getName();
           String featureIconPath = = fi.getIcon();
           String featureImagePath = fi.getImage();
           ...
      }
   }
   catch(AdfException e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned values and the exceptions to be passed back to the JavaScript calling code as follows:

public void getFeatures(success, failed)

The success callback function must be in the form of function(request, response), where the request argument contains the original request and the response argument contains the associated AdfmfContainerUtilities method's return value (the array of FeatureInformation objects).

The failed callback function must be in the form of function(request, response), where the request argument contains the original request and the response argument contains the error (AdfException).

adf.mf.api.getFeatures(
          function(req, res) { alert("getFeatures complete"); },
          function(req, res) { alert("getFeatures failed with " +
                               adf.mf.util.stringify(res); }
);

getFeatureByName

The getFeatureByName method returns information about the application feature using the passed-in name of the application feature.

Within Java, this method is called as follows:

public static oracle.adfmf.framework.FeatureInformation getFeatureByName(java.lang.String
                                                                         featureName)
                                     throws oracle.adfmf.framework.exception.AdfException

This method's parameter, as shown in the following example, is the name of the application feature.

   ...
   try {
        FeatureInformation fi = AdfmfContainerUtilities.getFeatureByName("feature.name");
        String featureId = fi.getId();
        String featureName = fi.getName();
        String featureIconPath = = fi.getIcon();
        String featureImagePath = fi.getImage();
   }
   catch(AdfException e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void getFeatureByName(featureName, success, failed)

The featureName parameter is the name of the application feature. The success callback function and must be in the form of function(request, response), where the request contains the original request and the response contains the associated AdfmfContainerUtilities method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions.

adf.mf.api.getFeatureByName("feature.name",
          function(req, res) { alert("getFeatureByName complete"); },
          function(req, res) { alert("getFeatureByName failed with " +
                                     adf.mf.util.stringify(res); }
);

getFeatureById

The getFeatureById method retrieves an application feature using the application ID.

Within Java, this method is called as follows:

public static oracle.adfmf.framework.FeatureInformation getFeatureById(String featureId)
                                     throws oracle.adfmf.framework.exception.AdfException

This method's parameter, as shown in the following example, is the ID of the application feature.

   try {
      FeatureInformation fi = AdfmfContainerUtilities.getFeatureById("feature.id");
   }
   catch(AdfException e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void getFeatureById(featureId, success, failed)

The featureId parameter is the ID of the application feature. The success callback function and must be in the form of function(request, response), where the request contains the original request and the response contains the associated AdfmfContainerUtilities method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions to retrieve an application feature.

adf.mf.api.getFeatureById("feature.id",
          function(req, res) { alert("getFeatureById complete"); },
          function(req, res) { alert("getFeatureById failed with " +
                                     adf.mf.util.stringify(res); }
);

resetFeature

This method resets the state of the application feature. It resets the Java-side model for the application feature and then restarts the user interface presentation as if the MAF application had just been loaded and displayed the application feature for the first time.

If the application feature content type is MAF Task Flow, the MAF application restarts the task flow and navigates to whatever activity you have designated as the default activity within the task flow.

Two implementations of the Java API AdfmfContainerUtilities.resetFeature are available for you to use:

• resetFeature(String featureId)

• resetFeature(String featureId, boolean gotoTheFeature)

Both reset the application feature identified by the featureId parameter while the method signature that includes the boolean gotoTheFeature method parameter also navigates to the application feature when set to true. The second option, that navigates to the application feature, should not be called from the application feature’s activate lifecycle listener method as to do so may cause stack overflow errors.

The following example illustrates how AdfmfContainerUtilities.resetFeature might be used to reset all application features in a MAF application in order to use a new skin specified by a setSkinFamily method.

...
public void switchSkinFamily(String family) {
   this.setSkinFamily(family);
   // reset all the features individually as follows to load the new skin
   FeatureInformation[] features = AdfmfContainerUtilities.getFeatures();
   for 
    (int i = 0; i < features.length; i++) {
    AdfmfContainerUtilities.resetFeature(features[i].getId());
}
...

MAF also provides a JavaScript resetFeature API. In JavaScript, the success and failed callback functions enable the returned value and exception to be passed back to the JavaScript calling code as follows:

public void resetFeature(featureId, success, failed)

The success callback function and must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (The ID of the application feature).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions to call an application feature.

adf.mf.api.resetFeature("feature0",
          function(req, res) { alert("resetFeature complete"); },
          function(req, res) { alert("resetFeature failed with " +
                                     adf.mf.util.stringify(res); }
);

resetApplication

The resetApplication method, to be used only if resetting individual application features is insufficient, resets a running application.

This method resets the running application and it should be used only when resetting individual application features is not sufficient.

Within Java, this method is called as follows:

public static void resetApplication(java.lang.String message)

The method's parameter, as shown in the following example, is either a message describing the reason for which the application is being restarted, or null if no message is required.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.resetApplication("New content is available");
   }
   catch(Exception e) {
      // handle the exception
}

In JavaScript, the success and failed callback functions enable the returned value and exception to be passed back to the JavaScript calling code as follows:

public void resetApplication(message, success, failed)

The success callback function and must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (The ID of the application feature).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions to call an application.

adf.mf.api.resetApplication("message1",
          function(req, res) { alert("resetApplication complete"); },
          function(req, res) { alert("resetApplication failed with " +
                                     adf.mf.util.stringify(res); }
);

gotoSpringboard

The gotoSpringboard method requests MAF to activate the springboard.

Note:

This method may not be able to display the springboard if it has not been designated as a feature reference in the maf-application.xml file, or if it has authentication or authorization-related problems. See also Configuring Application Navigation.

Within Java, this method is called as follows:

public static void gotoSpringboard()

The following example illustrates using this method

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.gotoSpringboard();
   }
   catch(AdfException e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void gotoSpringboard(success, failed)

The success callback function must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions.

adf.mf.api.gotoSpringboard(
    function(req, res) { alert("gotoSpringboard complete"); },
    function(req, res) { alert("gotoSpringboard failed with " +
                               adf.mf.util.stringify(res); }
);

showSpringboard

The showSpringboard method requests MAF to show the springboard.

This method requests that MAF display the springboard.

Within Java, this method is called as follows:

public static void showSpringboard()

The following example illustrates using this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.showSpringboard();
   }
   catch(Exception e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void showSpringboard(success, failed)

The success callback function must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions.

adf.mf.api.showSpringboard(
           function(req, res) { alert("showSpringboard complete"); },
           function(req, res) { alert("showSpringboard failed with " +
                                       adf.mf.util.stringify(res); }
);

hideSpringboard

The hideSpringboard method requests MAF to hide the springboard.

Within Java, this method is called as follows:

public static void hideSpringboard()

The following example illustrates using this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.hideSpringboard();
   }
   catch(Exception e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void hideSpringboard(success, failed)

The success callback function must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions.

adf.mf.api.hideSpringboard(
       function(req, res) { alert("hideSpringboard complete"); },
       function(req, res) { alert("hideSpringboard failed with " +
                                   adf.mf.util.stringify(res); }
);

showNavigationBar

The showNavigationBar method requests MAF to show the navigation bar.

This method requests that MAF display the navigation bar.

Within Java, this method is called as follows:

public static void showNavigationBar()

The following example illustrates using this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.showNavigationBar();
   }
   catch(Exception e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void showNavigationBar(success, failed)

The success callback function must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions.

adf.mf.api.showNavigationBar(
           function(req, res) { alert("showNavigationBar complete"); },
           function(req, res) { alert("showNavigationBar failed with " +
                                       adf.mf.util.stringify(res); }
);

hideNavigationBar

The hideNavigationBar method requests MAF to hide the navigation bar.

Within Java, this method is called as follows:

public static void hideNavigationBar()

The following example illustrates using this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.hideNavigationBar();
   }
   catch(Exception e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void hideNavigationBar(success, failed)

The success callback function must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions.

adf.mf.api.hideNavigationBar(
       function(req, res) { alert("hideNavigationBar complete"); },
       function(req, res) { alert("hideNavigationBar failed with " +
                                   adf.mf.util.stringify(res); }
);

showPreferences

The showPreferences method requests MAF to display the Preferences page.

This method requests that MAF display the preferences page.

Within Java, this method is called as follows:

public static void showPreferences()

The following example illustrates using this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
   try {
      AdfmfContainerUtilities.showPreferences();
   }
   catch(Exception e) {
      // handle the exception
   }

In JavaScript, the success and failed callback functions enable the returned value and the exception to be passed back to the JavaScript calling code as follows:

public void showPreferences(success, failed)

The success callback function must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value (void).

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

The following example illustrates using these callback functions.

adf.mf.api.showPreferences(
           function(req, res) { alert("showPreferences complete"); },
           function(req, res) { alert("showPreferences failed with " +
                                       adf.mf.util.stringify(res); }
);

invokeMethod

With the examples and the listed parameters, call the invokeMethod, unavailable in Java, to invoke a Java method from any class in a classpath.

This method is not available in Java. The following example illustrates using the JavaScript callback methods to invoke a Java method from any class in a classpath.

adf.mf.api.invokeMethod(classname,
                        methodname,
                        param1,
                        param2,
                         ...
                        paramN,
                        successCallback,
                        failedCallback);

Table B-1 lists the parameters taken by this method.

Table B-1 Parameters Passed to invokeMethod

Parameter	Description
classname	The class name (including the package information) that MAF uses to create an instance when calling the Java method.
methodname	The name of the method that should be invoked on the instance of the class specified by the classname parameter.

The success callback function must be in the form of function(request, response), where the request contains the original request and the response contains the associated method's return value.

The failed callback function must be in the form of function(request, response), where the request contains the original request and the response contains the error.

Examples of using this method with multiple parameters are as follows:

• adf.mf.api.invokeMethod("TestBean", "setStringProp", "foo", success, failed);
  

• adf.mf.api.invokeMethod("TestBean", "getStringProp", success, failed)
  

An example of using an integer parameter is as follows:

adf.mf.api.invokeMethod("TestBean", "testSimpleIntMethod", "101", success, failed);

The following illustrates using complex parameters:

adf.mf.api.invokeMethod("TestBean", "testComplexMethod", 
           {"foo":"newfoo","baz":"newbaz",".type":"TestBeanComplexSubType"}, success, failed);

The following illustrates using no parameters:

adf.mf.api.invokeMethod("TestBean", "getComplexColl", success, failed);

The following illustrates using String parameters:

adf.mf.api.invokeMethod("TestBean", "testMethodStringStringString", "Hello ",
                        "World", success, failed);

invokeContainerMethod

Use the listed parameters and call invokeContainerMethod to invoke a native method on a specified class with given arguments.

The invokeContainerMethod invokes a native method on the specified class with the given arguments. Table B-2 lists the parameters passed by this method.

Table B-2 Parameters Passed to invokeContainerMethod

Parameter	Description
className	The class name (including the package information) that MAF uses to create an instance.
methodName	The name of the method that should be invoked.
args	An array of arguments that are passed to the method. Within this array, these arguments should be arranged in the order expected by the method.

This method returns an Object.

public static java.lang.Object invokeContainerMethod(java.lang.String className,
                                                     java.lang.String methodName)
                                                     java.lang.Object[] args)

invokeContainerJavaScriptFunction

Use the invokeContainerJavaScriptFunction method to invoke JavaScript methods.

The invokeContainerJavaScriptFunction invokes a JavaScript method. Table B-3 lists the parameters passed by this method.

Table B-3 Parameters Passed to invokeContainerJavaScriptFunction

Parameter	Description
featureId	The ID of the application feature used by MAF to determine the context for the JavaScript invocation. The ID determines the web view in which this method is called.
method	The name of the method that should be invoked.
args	An array of arguments that are passed to the method. Within this array, these arguments should be arranged in the order expected by the method.

This method returns a JSON object.

Note:

The invokeContainerJavaScriptFunction API expects the JavaScript function to finish within 15 seconds for applications running on an Android-powered device or emulator, or it will return a timeout error.

public static java.lang.Object invokeContainerJavaScriptFunction(java.lang.String featureId,
                                                                 java.lang.Object[] args)
                                throws oracle.adfmf.framework.exception.AdfException

The pseudocode in the following example illustrates a JavaScript file called appFunctions.js that is included in the application feature, called feature1. The JavaScript method, application.testFunction, which is described within this file, is called by the invokeContainerJavaScriptFunction method, shown in the next example.

(function() 
    {
       if (!window.application) window.application = {};
 
       application.testFunction = function()
       {
          var args = arguments;
 
          alert("APP ALERT " + args.length + " ");
          return "application.testFunction - passed";
       };
    })();

Because the application includes a command button that is configured with an action listener that calls this function, an end user sees the following alerts after clicking this button:

• APP ALERT 0

• APP ALERT 1

• APP ALERT 2

The pseudocode in the following example illustrates how the invokeApplicationJavaScriptFunction method calls the JavaScript method (application.testFunction) that is described in the preceding example.

invokeApplicationJavaScriptFuntions 
    public void invokeApplicationJavaScriptFuntions(ActionEvent actionEvent) {
        AdfmfContainerUtilities.invokeContainerJavaScriptFunction("feature1",
                                                                  "application.testFunction",
                                                                   new Object[] {} );
        AdfmfContainerUtilities.invokeContainerJavaScriptFunction("feature1",
                                                                  "application.testFunction",
                                                                   new Object[] {"P1"} );
        AdfmfContainerUtilities.invokeContainerJavaScriptFunction("feature1",
                                                                  "application.testFunction",
                                                                   new Object[] {"P1", "P2"} );
    }

See Java API Reference for Oracle Mobile Application Framework and the APIDemo sample application. This sample application is in the PublicSamples.zip file at the following location within the JDeveloper installation directory of your development computer:

jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples

sendEmail

For information, see How to Use the sendEmail Method to Enable Email.

sendSMS

For information, see How to Use the SendSMS Method to Enable Text Messaging.

Application Icon Badging

On the iOS platform, use the listed methods of the AdfmfContainerUtilities class either to place a badge number on a MAF application icon, or to retrieve it.

The AdfmfContainerUtilities class includes methods to place or retrieve a badge number on a MAF application icon. Table B-4 describes these methods.

Table B-4 Icon Badging Methods

Method	Description	Parameters
getApplicationIconBadgeNumber	Gets the current badge value on the MAF application icon. Returns zero (0) if the application icon is not badged.	None
setApplicationIconBadgeNumber	Sets the badge number on a MAF application icon.	The value of the badge (int badge).

Note:

Application icon badging is not supported either on the Android or the Windows platforms.

Accessing Files Using the getDirectoryPathRoot Method

The AdfmfJavaUtilties API includes the getDirectoryPathRoot method. This method, which can only be called from the Java layer, enables access to directories on the iOS, Android, and Windows systems.

As shown in the following example, this method enables access to the location of the temporary, application (on iOS systems), and the cache directory on the device using the TemporaryDirectory, ApplicationDirectory, and DeviceOnlyDirectory constants, respectively. Files stored in the DeviceOnlyDirectory location are not synchronized when the device is connected.

Note:

Verify that any directories or files accessed by an application exist before the application attempts to access them.

For information about oracle.adfmf.framework.api.AdfmfJavaUtilities, see the Java API Reference for Oracle Mobile Application Framework.

import oracle.adfmf.framework.api.AdfmfJavaUtilities;
 
...
 
public void getDirectoryPathRoot() {
   // returns the directory for storing temporary files
   String tempDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.TemporaryDirectory);
 
   // returns the directory for storing application files
   String appDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.ApplicationDirectory);
 
   // returns the directory for storing cache files
   String deviceDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.DeviceOnlyDirectory);
  
   // returns the directory for storing downloaded files
   String downloadDir =
      AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.DownloadDirectory);
} 

Accessing Platform-Independent Download Locations

Use the getDirectoryPathRoot method to get the paths to external storage directories and the default attachments directory.

File storage requirements differ by platform. The Android platform does not prescribe a central location from which applications can access files; instead, an application can write a file to any location to which it has write permission. iOS platforms, on the other hand, generally store files within an application directory. In Windows, applications do not access external files or directories: files are stored within the application package. Because of these differences, passing ApplicationDirectory to the getDirectoryPathRoot method can return the file location needed to display attachments for applications running on iOS-powered or Windows-powered devices, but not on Android-powered devices. Rather than writing platform-specific code to retrieve these locations for applications intended to run on both iOS- and Android-powered devices, you can enable the getDirectoryPathRoot method to return the paths to both the external storage location and the default attachments directory by passing it DownloadDirectory. This constant (an enum type) reflects the locations used by the displayFile method of the DeviceManager API, which displays attachments by using platform-specific functionality to locate these locations.

On Android, DownloadDirectory refers to the path returned by the android.os.Environment.getExternalStorageDirectory method (which retrieves the external Android storage directory, such as an SD card). For MAF applications running on iOS-powered devices, it returns the same location as ApplicationDirectory. For information on the getExternalStorageDirectory, see the package reference documentation available from the Android Developers website (http://developer.android.com/reference/packages.html). See also Files System Programming Guide, available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).