This chapter describes the ADF Mobile JavaScript API extensions, the ADF Mobile 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:
Section B.1, "Using ADF Mobile APIs to Create a Custom HTML Springboard Application Feature"
Section B.3, "Accessing Files Using the getDirectoryPathRoot Method"
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 Section 5.5.4, "What You May Need to Know About Custom Springboard Application Features with HTML Content," you can enable callbacks and leverage Apache Cordova by including methods in the JavaScript <script> tag. Example B-1 illustrates using this tag to call Cordova.
Example B-1 Embedding the <script> Tag in an HTML Springboard Page
...
<script type="text/javascript">if (!window.adf) window.adf = {};
adf.wwwPath = "../../../www/";</script>
<script type="text/javascript" src="../../../www/js/base.js"></script>
...
The relative path to the location of the www/js directory always reflects the location of the HTML springboard page (or any custom HTML page), which can be located at the root of the view controller's public_html directory, or within a subdirectory of it. In Example B-1, the paths defined by the src attribute (../../../www/js/base.js) and the adf.wwwPath variable are relative to the location of the HTML springboard file when it is located at the root of the public_html directory, as follows:
JDeveloper\mywork\application name\ViewController\public_html\customspringboard.html
In other words, the adf.wwwPath variable must have the same number of ../ entries as base.js.
To enable the springboard files and custom HTML files located within the subdirectories of public_html to access the hosted JavaScript files, you must adjust the relative path definition accordingly by adding ../ entries for each subdirectory location. The number of ../ entries varies. It depends on the location of the HTML page within the ADF Mobile application relative to the location of the deployed www directory; if the HTML file is moved to a deeper level of folders, then you must add the appropriate number of ../ entries to the <script> tags.
Tip:
To access (and determine the location of) the www/js directory, you must first deploy an ADF Mobile application and traverse 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. See also Section 5.5.4, "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 ADF Mobile extension to the Cordova API enables the mobile device's API to access the configuration metadata in the adfmf-feature.xml and adfmf-application.xml files, which in turn results in communication between the mobile device and ADF Mobile's infrastructure. These extensions also direct the display behavior of the application features.
Note:
Because ADF Mobile requires Cordova 2.2.0, you must migrate any installed PhoneGap plugins to the Cordova 2.2.0 versions of those plugins. For more information, see the upgrading guides, available in the Apache Cordova Documentation (http://docs.phonegap.com/en/2.2.0/index.html).
For information on the default ADF Mobile springboard page, springboard.amx, and about the ApplicationFeatures data control that you can use to build a customized springboard, see Section 5.5.5, "What You May Need to Know About Custom Springboard Application Features with ADF Mobile AMX Content."
Example B-2 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 ADF Mobile has loaded and displayed the page for the first time.
Example B-2 Using the showpagecomplete Event
<script>
function handlePageShown()
{
console.log("Page is shown!");
}
document.addEventListener("showpagecomplete", handlePageShown, false);
</script>
Note:
The showpagecomplete event guarantees the appropriate ADF Mobile state; other browser and third-party events, such as load and Cordova's deviceready, may not. Do not use them.
The methods of the ADF Mobile Container Utilities API provide ADF Mobile 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 ADF Mobile.
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. Example B-3 illustrates calling the gotoSpringboard method. For more information on oracle.adfmf.framework.api.AdfmfContainerUtilities, see Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile.
Example B-3 Calling the Container Utilities API in Java
import oracle.adfmf.framework.api.AdfmfContainerUtilities; ... AdfmfContainerUtilities.gotoSpringboard(); ...
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 Example B-4 illustrates how a call with no arguments, public static functionName() throws, is executed within Java using try and catch blocks.
Example B-4 Executing a Call with No Arguments in Java
...
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 Example B-5 illustrates the signature of the JavaScript call.
Example B-5 The JavaScript Call Signature
adf.mf.api.functionName(
function(req, res) { alert("functionName complete"); },
function(req, res) { alert("functionName failed with " +
adf.mf.util.stringify(res); }
);
As illustrated by Example B-5, 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.
The pseudocode in 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.
Example B-6 Executing a Call with Multiple Arguments in Java
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.
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 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.
The Container Utilities API also include methods for placing badges and badge numbers on applications. For more information, see Section B.2.16, "Application Icon Badging."
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 compares the connection-related content hosted on the server to the configuration on the device. (This comparison happens asynchronously in the background.) 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 B-7 illustrates using this method.
Example B-7 Retrieving Configuration Information Using Java
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 B-8 illustrates using these callback functions to retrieve the configuration information.
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 an application.
Within Java, this method is called as follows:
public static oracle.adfmf.framework.ApplicationInformation
getApplicationInformation()
throws oracle.adfmf.framework.exception.AdfException
Example B-9 illustrates calling this method.
Example B-9 Retrieving Application Information Using Java
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.
Example B-10 illustrates using these callback functions to retrieve the application information.
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.
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.
Example B-11 illustrates using these callbacks to call the default application feature.
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 B-12 illustrates using this method.
Example B-12 Retrieving the Application Feature Information Using Java
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).
This method requests that ADF Mobile display the application feature 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 Example B-14, is the ID of the application feature.
Example B-14 Activating an 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 B-15 illustrates using these callback functions to call an application feature.
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 B-16, is the name of the application feature.
Example B-16 Retrieving the Application Feature Information Using the Application Feature Name
...
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.
Example B-17 illustrates using these callback functions.
Example B-17 Using JavaScript Callback Functions to Retrieve the Application Feature Information Using the Application Feature Name
adf.mf.api.getFeatureByName("feature.name",
function(req, res) { alert("getFeatureByName complete"); },
function(req, res) { alert("getFeatureByName failed with " +
adf.mf.util.stringify(res); }
);
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 B-18, is the ID of the application feature.
Example B-18 Retrieving an Application Feature Using its ID in Java
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 B-19 illustrates using these callback functions to retrieve an application feature.
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 B-20, is the ID of the application feature that is to be reset.
Example B-20 Resetting an Application Feature in Java
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 B-21 illustrates using these callback functions to call an application feature.
This method requests that ADF Mobile 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 adfmf-application.xml file, or if it has authentication or authorization-related problems. See also Section 5.5, "Configuring the Springboard and Navigation Bar Behavior."
Within Java, this method is called as follows:
public static void gotoSpringboard()
Example B-22 illustrates using this method
Example B-22 Activating the Springboard in Java
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 B-23 illustrates using these callback functions.
This method requests that ADF Mobile hide the navigation bar.
Within Java, this method is called as follows:
public static void hideNavigationBar()
Example B-24 illustrates using this method.
Example B-24 Hiding the Navigation Bar in Java
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 B-25 illustrates using these callback functions.
This method requests that ADF Mobile display the navigation bar.
Within Java, this method is called as follows:
public static void showNavigationBar()
Example B-26 illustrates using this method.
Example B-26 Showing the Navigation Bar in Java
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 B-27 illustrates using these callback functions.
This method is not available in Java. Example B-28 illustrates using the JavaScript callback methods to invoke a Java method from any class in a classpath.
Example B-28 Using JavaScript Callback Function to Call a Java Method
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 invokeJavaMethod
| Parameter | Description |
|---|---|
|
|
The class name (including the package information) that ADF Mobile uses to create an instance when calling the Java method. |
|
|
The name of the method that should be invoked on the instance of the class specified by the |
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);
The invokeContainerJavaScriptFunction invokes a JavaScript method. Table B-2 lists the parameters passed by this method.
Table B-2 Parameters Passed to invokeContainerJavaScriptFunction
| Parameter | Description |
|---|---|
|
|
The ID of the application feature used by ADF Mobile to determine the context for the JavaScript invocation. The ID determines the web view in which this method is called. |
|
|
The name of the method that should be invoked. |
|
|
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.
Example B-29 The invokeContainerJavaScriptFunction Method
public static java.lang.Object invokeContainerJavaScriptFunction(java.lang.String featureId,
java.lang.Object[] args)
throws oracle.adfmf.framework.exception.AdfException
The pseudocode in Example B-30 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 B-31. 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";
};
})();
The pseudocode in Example B-31 illustrates how the invokeApplicationJavaScriptFunction method calls the JavaScript method (application.testFunction) that is described in Example B-30.
Example B-31 Calling the JavaScript Function from Java
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 and the JSExtend 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.adf.mobile/Samples
The AdfmfContainerUtilities class includes methods to place or retrieve a badge number on an ADF Mobile application icon. Table B-3 describes these methods.
Table B-3 Icon Badging Methods
| Method | Description | Parameters |
|---|---|---|
|
|
Gets the current badge value on the ADF Mobile application icon. Returns zero (0) if the application icon is not badged. |
None |
|
|
Sets the badge number on an ADF Mobile application icon. |
The value of the badge ( |
Note:
Application icon badging is not supported on Android.
The adfmfJavaUtilties API includes the getDirectoryPathRoot method. This method, which can only be called from the Java layer, enables access to files on both iOS and Android systems. As shown in Example B-32, this method enables access to the location of the temporary files, application files (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 more information on oracle.adfmf.framework.api.AdfmfJavaUtilities, see Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile.
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
AdfmfJavaUtilities.getDirectoryPathRoot(AdfmfJavaUtilities.DownloadDirectory);
}
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. 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 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 Environment.getExternalStorageDirectory method (which retrieves the external Android storage directory, such as an SD card). For ADF Mobile applications running on iOS-powered devices, it returns the same location as ApplicationDirectory. For more 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/).