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:

11.1 Introduction to Lifecycle Listeners in MAF Applications

Lifecycle listeners contain code that runs in response to specific application events. Review the information about the interfaces to be implemented for communication with event notifications, and how they can create lifecycle listeners.

Lifecycle listeners are useful locations to write code that executes in response to specific events in your application. MAF provides lifecycle listeners where you can write code in response to application or application feature events. A typical implementation of an application lifecycle listener method may be to write code that initializes the database of the application when the application starts, as described in Using the Local SQLite Database, or to update a security configuration from URL parameters, as described in How to Update Connection Attributes of a Named Connection at Runtime.

MAF provides the following two interfaces that you can implement to communicate with event notifications:

oracle.adfmf.application.LifeCycleListener

This interface specifies the following methods that an application lifecycle listener must implement:
- activate()
- deactivate()
- start()
- stop()
oracle.adfmf.feature.LifeCycleListener

This interface specifies the following methods that a feature lifecycle listener must implement:
- activate()
- deactivate()

You create a lifecycle listener by creating a Java class that implements the appropriate interface and registering the implementation in your MAF application, as described in Registering a Lifecycle Listener for a MAF Application or an Application Feature.

A new MAF application that you create implements the oracle.adfmf.application.LifeCycleListener interface through the default creation of the application.LifeCycleListenerImpl.java class in the application project, as shown in Figure 11-1.

Figure 11-1 Implementation of Application Lifecycle Listener

The surrounding text describes the image.

Note that 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).

Table 11-1 describes the specific times that MAF invokes application lifecycle methods during the application startup, shutdown, and hibernation.

Table 11-1 Timing of the MAF Invocation of Application Lifecycle Methods

Method	Timing	When Called	Usage
`start`	Called after the MAF 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 MAF application. Requesting a remote server to download data to the local database.
`stop`	Called as the MAF 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.
`activate`	Called as the MAF 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.
`deactivate`	Called as the MAF 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. Closing the database cursor and the database connection.

Table 11-2 describes the specific times that MAF invokes feature lifecycle methods during the activation and deactivation of a feature.

Table 11-2 Timing of MAF's Invocation of Feature Lifecycle Methods

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

For more information about the oracle.adfmf.application.LifeCycleListener and oracle.adfmf.feature.LifeCycleListener interfaces, see the Java API Reference for Oracle Mobile Application Framework.

The LifecycleEvents sample application demonstrates declaring listener classes that implement both the application and feature interfaces. It registers these listener classes in the maf-application.xml and maf-feature.xml files of the MAF application. For more information about this and other sample applications, see MAF Sample Applications..

11.2 Registering a Lifecycle Listener for a MAF Application or an Application Feature

In MAF, you can register additional plugins. Use the first procedure to register an application lifecycle listener using the overview editor for the mafapplication.xml file, and use the second procedure to register a feature lifecycle listener using the overview editor for the maf-features.xml file .

You register an application lifecycle listener using the MAF Application Editor and a feature lifecycle listener using the MAF Features Editor.

To register an application lifecycle listener:

In the Project Explorer, expand the assembly project, then MAF and double-click MAF Application Editor.
In the Outline, select the application node, and in the Application tab specify the Java class that implements the oracle.adfmf.application.LifeCycleListener interface in the Lifecycle Event Listener field.

Note:

If you place the mouse pointer over the label for Lifecycle Event Listener, OEPE displays a tooltip describing the listener class.

Figure 11-2 Retrieving the Application Event Listener

To register an application feature lifecycle listener:

In the Project Explorer, expand the view project, then MAF and double-click MAF Features Editor.
Select the feature in the Features list for which you want to register a feature lifecycle listener.
In the Lifecycle Event Listener field, specify the Java class that implements the oracle.adfmf.feature.LifeCycleListener interface.

11.3 What Happens When You Register a Lifecycle Listener

The application.LifeCycleListenerImpl.java class in the ApplicationController project, which is registered by the listener-class attribute in the maf-application.xml file, implements the lifecycle listener.

By default, a MAF application that you create implements an application lifecycle listener through the creation of the application.LifeCycleListenerImpl.java class in the application project of the application. The listener-class attribute in the maf-application.xml file registers this class, as shown in the following example.

<adfmf:application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"                    xmlns:adfmf="http://xmlns.oracle.com/adf/mf"
                   version="1.0" name="NewMAFapp" id="com.company.NewMAFapp"
    appControllerFolder="ApplicationController" listener-class="application.LifeCycleListenerImpl">
...
</adfmf:application>

OEPE writes an entry to the maf-feature.xml file for the listener-class attribute when you register a feature lifecycle listener. The following example shows an entry in the LifecycleEvents sample application described in MAF Sample Applications..

<?xml version="1.0" encoding="UTF-8" ?>
<adfmf:features xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:adfmf="http://xmlns.oracle.com/adf/mf">
  <adfmf:feature id="Feature1" name="Feature1" listener-class="mobile.Feature1Handler">
    <adfmf:description>This is a sample feature to show the feature lifecycle handlers.
    </adfmf:description>
    <adfmf:content id="Feature1.1">
      <adfmf:amx file="Feature1/feature1.amx"/>
    </adfmf:content>
  </adfmf:feature>
...
</adfmf:features>