11 Using Lifecycle Listeners in MAF Applications

This chapter describes using the MAF Application Editor and MAF Features Editor to define the display behavior of the mobile application's springboard and navigation bar and how to designate content by embedding application features.

This chapter includes the following sections:

Section 11.1, "About Using Lifecycle Event Listeners in MAF Applications"
Section 11.2, "About Application Feature Lifecycle Listener Classes"

11.1 About Using Lifecycle Event Listeners in MAF Applications

Within the MAF runtime, classes implement various LifeCycleListener methods to communicate with event notifications sent from the native operating system frameworks to the JVM. These event notifications describe various states (starting, stopping, or hibernating) for both the mobile application and its embedded application features. MAF invokes the class functions to the JVM using a generic invoke message.

The MAF Application Editor and MAF Feature Editor enable you to declaratively add a lifecycle listener class that MAF calls when events occur.

After you create a mobile application, OEPE creates a lifecycle listener class for the application called LifeCycleListenerImpl.java. You can implement specific methods using this file, as illustrated in Chapter 25, "Enabling and Using Notifications." The Lifecycle Events sample application provides an example of declaring the event listener class in both the MAF Application Editor and the MAF Features Editor.

To work with this sample application, select File > New MAF Examples, then select LifecycleEvents and click Finish.

11.1.1 Events in Mobile Applications

Lifecycle listener classes for mobile applications must implement the start, stop, activate, and deactivate methods of the LifeCycleListener interface, as illustrated in the example below, to execute the application lifecycle events.

package oracle.adfmf.application;
 
public interface LifeCycleListener
{
   void start();
   void stop();
   void activate();
   void deactivate();
}

Note:

The application lifecycle listener is executed with an anonymous user (that is, there is no user associated with any of its methods and no secure web service is called).

The AppListener class, shown in the example below, uses the LifeCycleListener method calls for starting or stopping events as well as those used when the application is about to hibernate (deactivate) or return from hibernating (activate). For more information, see Section 11.1.2, "Timing for Mobile Application Events." See also the LifeCycleListener interface in Java API Reference for Oracle Mobile Application Framework.

package some.package;
import oracle.adfmf.application.LifeCycleListener;
 
public class AppListener implements LifeCycleListener
{
    public AppListener()
    {
        super();
    }
    public void start()
    {
        // Perform application startup tasks...
    }
    public void stop()
    {
        // Perform tasks to stop the application...
    }
    public void activate()
    {
        // Perform appplication activation tasks...
    }
    public void deactivate()
    {
        // Perform application deactivation tasks...
    }
}

The application controller project of the LifeCycleEvents sample application, described in Appendix G, "MAF Sample Applications," contains a class (LifeCycleListenerImpl.java) that implements the LifeCycleListener interface.

Note:

Managed beans and data bindings must be initialized before the startup lifecycle code executes.

11.1.2 Timing for Mobile Application Events

MAF calls application lifecycle methods at specific times during the mobile application's startup, shutdown, and hibernation. Table 11-1 describes when these methods are called and also notes their Objective-C counterparts.

Table 11-1 MAF Lifecycle Methods

Method	Timing	When Called	Usage	Relation to iOS Application Delegate Methods
`start`	Called after the mobile application has completely loaded the application features and immediately before presenting the user with the initial application feature or the springboard. This is a blocking call.	When the application process starts.	Uses include: Determining if there are updates to the mobile application. Requesting a remote server to download data to the local database.	This event does not correspond to a specific application delegate method. It is called after the `maf-application.xml` and `maf-feature.xml` files have loaded, just prior to hiding the splash screen.
`stop`	Called as the mobile application begins its shutdown.	When the application process terminates.	Uses include: Logging off from any remote services. Uploading any data change to the server before the application is closed.	This is called in the `applicationWillTerminate:` method on the application delegate.
`activate`	Called as the mobile application activates from being situated in the background (hibernating). This is a blocking call.	After the `start` method is called.	Uses include: Reading and re-populating cache stores. Processing web service requests. Obtaining required resources. Checkpointing. For more information, see Section 11.1.3, "Using the activate and deactivate Methods to Save Application State."	This is called in the `applicationDidBecomeActive:` method on the application delegate.
`deactivate`	Called as the mobile application deactivates and moves into the background (hibernating). This is a blocking call.	Before the `stop` method is called.	Uses include: Writing the restorable state. Checkpointing. For more information, see Section 11.1.3, "Using the activate and deactivate Methods to Save Application State." Closing the database cursor and the database connection.	This is called in the `applicationWillResignActive:` method on the application delegate.

11.1.3 Using the activate and deactivate Methods to Save Application State

Because checkpointing saves the application state, you can enable users to continue using the last page of a mobile application that was active before it began to hibernate by adding checkpoint entries to the activate and deactivate methods. The lifecycle listener reads the checkpoint entries added to the activate class and allows the processes to resume after the application has returned from hibernating; users can continue with application uninterrupted by not having to log in a second time. If the application is terminated during hibernation, you can enable the application to resume by specifying that checkpoint information be written to a database or to a device's cache directory as part of the deactivate method. The application resumes at the same page by reading this checkpoint information during activation.

11.2 About Application Feature Lifecycle Listener Classes

A mobile application feature lifecycle listener class, such as FeatureListenerPhoneList, illustrated in the example below, must implement the activate and deactivate methods of the LifeCycleListener interface.

package oracle.adfmf.feature;
public interface LifeCycleListner
{
   void activate();
   void deactivate();
}

The example below illustrates a class called FeatureListenerPhoneList that uses the activate and deactivate methods by implementing the LifeCycleListener to show and hide the application feature as described in Table 11-2. These methods hide the application feature when it hibernates, or display it when it returns from hibernating.

Note:

As noted in Java API Reference for Oracle Mobile Application Framework, both the activate and deactivate methods are blocking calls. Because these methods freeze the user interface until they have executed completely, any long-running process included within them will delay the activation of an another application feature. If an application does not require a long-running process to complete before it is deactivated, include it in a background thread rather than within these methods.

package some.package;
import oracle.adfmf.feature.LifeCycleListener;
public class FeatureListenerPhoneList implements LifeCycleListener
{
    public FeatureListenerPhoneList()
    {
        super();
    }
    public void activate()
    {
        // Perform application activation tasks...
    }
    public void deactivate()
    {
        // Perform application deactivation tasks...
    }
}

Tip:

The LifeCycle Events sample application provides an example of using the LifeCycleListener interface at the application feature level through the Feature1Handler.java and Feature2Handler.java files. These files are located within the view controller project's Application Sources folder.

11.2.1 Timing for Activate and Deactivate Events in the Application Feature Lifecycle

By implementing an application feature lifecycle listener class, you enable an application feature to automatically obtain any data changes to the applicationScope variable or to application feature-specific variables that changed when the application feature was deactivated. Table 11-2 describes when the activate and deactivate events are fired for an application feature. For more information, see Java API Reference for Oracle Mobile Application Framework.

Table 11-2 The activate and deactivate Methods for Application Features

Method Timing When Called Usage

Method	Timing	When Called	Usage
`activate`	Called before the current application feature is activated.	Called when a user selects the application feature for the first time after launching a mobile application, or when the application has been re-selected (that is, brought back to the foreground).	Uses include: Reading the `applicationScope` variable. Setting the current row on the first MAF AMX view.
`deactivate`	Called before the next application feature is activated, or before the application feature exits.	Called when the user selects another application feature.	You can, for example, use the `deactivate` event to write the `applicationScope` variable, or any other state information, for the next application feature to consume.

activate

Called before the current application feature is activated.

Called when a user selects the application feature for the first time after launching a mobile application, or when the application has been re-selected (that is, brought back to the foreground).

Uses include:

Reading the applicationScope variable.
Setting the current row on the first MAF AMX view.

deactivate

Called before the next application feature is activated, or before the application feature exits.

Called when the user selects another application feature.

You can, for example, use the deactivate event to write the applicationScope variable, or any other state information, for the next application feature to consume.

11.2.2 Enabling Sliding Windows

By implementing the oracle.adfmf.framework.api.AdfmfSlidingWindowUtilities interface in the application lifecycle listener (ALCL), you can use an application feature as a sliding window, which displays concurrently with the other application features that display within the navigation bar or springboard. You can use a sliding window to display content that always present within the application, such as a global tool bar, or for temporary (pop-up) content, such as a help window. For information on displaying application features within the springboard or navigation bar, see Section 5.1, "Introduction to the Display Behavior of MAF Applications." For information on using the methods of the AdfmfSlidingWindowUtilities API, refer to Java API Reference for Oracle Mobile Application Framework.