6 Controlling the Display of Application Features

6.2.1 Using the JavaScript Callbacks

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. For example, a call with no arguments, such as public static (, , ...) throws is executed within Java as follows:

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

Because JavaScript calls are asynchronous, the return is required through the callback mechanism on the completion of the execution of the function. The signature for the JavaScript is adf.mf.api.(, , ..., , ) and is invoked as follows:

 adf.mf.api.(, , ..., , )

This call is defined as function(request, response). The value of the request argument is the actual request. The response is defined as function(request, response)and its value is the actual request. The response is thrown during the execution of the function.

A call with one or more arguments, such as public static <return value> <function name>(<arg0>, <arg1>, ...) throws <exceptions>, is executed within Java as follows:

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

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.

6.2.2 Using the Container Utilities API

The Container Utilities API provides the following methods:

• checkforNewConfiguration—Checks for the changes in a hosted connections.xml file.

• getApplicationInformation—Retrieves the metadata for the ADF Mobile application.

• gotoDefaultFeature—Displays the default application feature.

• getFeatures—Retrieves the application features.

• gotoFeature—Displays a specific application feature.

• 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.

• gotoSpringboard—Displays the springboard.

• hideNavigationBar—Hides the navigation bar.

• showNavigationBar—Displays the navigation bar.

• "invokeMethod"—Invokes a Java method.

• invokeContainerJavaScriptFunction—Invokes a JavaScript method.

6.2.3 checkforNewConfiguration

When the Configuration Service is used, this method requests that ADF Mobile check a server that hosts the connections.xml file for any changes to the configured endpoints. To check for changes, ADF Mobile creates a thread that compares the connection-related content hosted on the server to the configuration on the device. If ADF Mobile finds that the device configuration is outdated, then the checkforNewConfiguration method issues a non-blocking call that notifies the user that a new configuration has been detected and then closes the application. ADF Mobile reminds the user to restart the application.

In Java, the method is as follows:

public static void checkForNewConfiguration()
                   throws oracle.adfmf.framework.exception.AdfException 

Example 6-4 illustrates using this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
     try {
        AdfmfContainerUtilities.checkForNewConfiguration();
     }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 checkForNewConfiguration(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 (void). The failed callback 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).

Example 6-5 illustrates using these callback functions to retrieve the configuration information.

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

6.2.4 getApplicationInformation

This method returns an ApplicationInformation object that contains information about the application. This method returns such metadata as the application ID, application name, version, and the vendor of a custom springboard application.

Within Java, this method is called as follows:

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

Example 6-6 illustrates calling this method.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
     try {
        ApplicationInformation[] ai = AdfmfContainerUtilities.getApplicationInformation();
        ...
     }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 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.

Example 6-7 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); }
                                    );

6.2.5 gotoDefaultFeature

This method requests that ADF Mobile display the default application feature. The default application feature is the one that is displayed when the ADF Mobile application is started.

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.

Example 6-8 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); }
                             );

6.2.6 getFeatures

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. (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

Example 6-9 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];
           ...
        }
     }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); }
                         );

6.2.7 gotoFeature

This method requests that ADF Mobile display the application feature identified by its ID.

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 Example 6-11, 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.

Example 6-12 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); }
   );

6.2.8 getFeatureByName

This 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 Example 6-13, is the name of the application feature.

 ...
     try {
        FeatureInformation fi = AdfmfContainerUtilities.getFeatureByName("feature.name");
     }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.

Example 6-14 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); }
);

6.2.9 getFeatureById

This method retrieves an application feature using its application ID.

Within Java, this method is called as follows:

import oracle.adfmf.framework.api.AdfmfContainerUtilties;

This method's parameter, as shown in Example 6-15, 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.

Example 6-16 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); }
   );

6.2.10 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 ADF Mobile application had just been loaded and displayed the application feature for the first time.

Within Java, this method is called as follows:

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

The method's parameter, as shown in Example 6-17, is the ID of the application feature that is to be reset.

import oracle.adfmf.framework.api.AdfmfContainerUtilties;
 
   ...
     try {
        AdfmfContainerUtilities.resetFeature("feature.id");
     }catch(AdfException 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 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.

Example 6-18 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); }
                       );

6.2.11 gotoSpringboard

This method requests that ADF Mobile display the springboard.

Within Java, this method is called as follows:

public static void gotoSpringboard()

Example 6-19 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.

Example 6-20 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); }
);

6.2.12 hideNavigationBar

This method requests that ADF Mobile hide the navigation bar.

Within Java, this method is called as follows:

public static void hideNavigationBar()

Example 6-21 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.

Example 6-22 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); }
);

6.2.13 showNavigationBar

This method requests that ADF Mobile display the navigation bar.

Within Java, this method is called as follows:

public static void showNavigationBar()

Example 6-23 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.

Example 6-24 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); }
);

6.2.14 invokeMethod

This method invokes a Java method from any class in a classpath as follows:.

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

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

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);

6.2.15 invokeContainerJavaScriptFunction

The invokeContainerJascriptFunction invokes a JavaScript method. Table 6-2 lists the parameters passed by this method.

This method returns a JSON object.

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

Example 6-26 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 Example 6-27. Because the application includes a command button that is configured with an action listener that calls this function, a user sees the following alerts after clicking this button:

• APP ALERT 0

• APP ALERT 1

• APP ALERT 2

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

Example 6-27 illustrates how the invokeApplicationJavaScriptFunction method calls the JavaScript method (application.testFunction) that is described in Example 6-26.

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"} );
    }

For more information, see Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile.

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 invokeContainerJavaScriptFunction(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 values, which are described in Table 6-2. The response contains the associated AdfmfContainerUtilities 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.