Always on

Whether it listens and reacts to events, generates notifications, or shares data with other applications, a Super App is always working behind the scenes. By permitting your application to run in the background, you can take advantage of a number of powerful features of the BlackBerry® Application Platform. Do you want your application to listen for pushed content and notify BlackBerry device users when the content arrives? Do you want your application to provide location-specific information updates to your users? These types of tasks rely on your application's ability to run in the background.

This chapter focuses on how to create the framework for an application that provides an always-on experience, which is a fundamental characteristic of a Super App. Once we've demonstrated the framework by using the Bookshelf application, you'll have a starting point and can begin implementing other Super App characteristics that are discussed in later chapters.

What are the benefits of an always-on application?

  • Keep the user informed. You can create a framework that supports push communication, allowing BlackBerry device users to receive information and updates as changes occur.
  • Use the capabilities of BlackBerry devices. A BlackBerry device is a multitasking environment that integrates with a user's schedule and needs.
  • Anticipate the needs of your users. Your application can download content before users need it.
  • Integrate with other applications. Your application can communicate with other applications that are running in the background.

Approaches to the always-on experience

To create an always-on experience, you can implement some of the following approaches.

Approach

Description

Run your application at startup.

One of the most basic steps in creating an always-on experience is making your application run automatically when users turn on their BlackBerry® devices.

Keep your application running in the background.

Once your application is up and running, there are steps that you can take to make sure that it continues to run efficiently in the background, even after a user closes the UI component for your application.

Create alternate entry points.

By creating alternate entry points, you can split your application into multiple processes. For example, your main entry point might launch a UI component (using an icon on the Home screen) while another entry point starts a background process that listens for pushed content and sends users notifications.

Schedule processes to run periodically.

By scheduling processes to run at set intervals, you can keep your users up-to-date and you can conserve memory and battery power on the device when the process doesn't need to be running.

Creating an always-on experience

The Bookshelf app can receive pushed information about books that other Bookshelf users release and information about the books that interest you (see the Social and connected and Proactive and notification-driven chapters for more information). Since you don't want to have to wait for users to manually start Bookshelf before they can receive notifications when new information arrives, it's up to you to make sure that there are threads running in the background that can listen for updates, and send notifications to your users when new content is available.

Bookshelf can also help users locate books that other users release. To locate these books, make sure that Bookshelf can efficiently retrieve the position of the BlackBerry® device so that the application can notify users when books are nearby.

Running an application at startup

Making your application to run when BlackBerry® device users turn on their devices doesn't require any changes to your application code. If you're using the BlackBerry® Java® Plug-in for Eclipse®, you can edit the BlackBerry_App_Descriptor.xml file so that your application runs each time the BlackBerry device turns on. For BlackBerry® WebWorks™ application developers, a similar option is available in the BlackBerry® WebWorks™ Plug-in for Eclipse in the config.xml file.

If you want your application to run when BlackBerry device users turn on their devices, chances are that you probably don't want to launch the UI component for the application (most users are not going to want to see your application UI every time they turn on their devices). In Bookshelf, we need the ability to launch a background process that can listen for push events.

Run an application at startup
  1. In Eclipse®, in the Package Explorer view, expand a BlackBerry® application project and double-click BlackBerry_App_Descriptor.xml. The application descriptor opens in the Editor view.
  2. In the General Information section, select the Auto-run on startup check box.
  3. On the File menu, click Save.

Keeping the application running in the background

If your application has a UI component, you might want to keep your application running in the background even after a BlackBerry® device user closes the screen for your application. By default, when the last screen for your application is popped off the display stack, Screen.onClose() invokes System.exit() to terminate the application. To get your application to continue to run in the background, you can override Screen.onClose() and invoke UiApplication.getUiApplication().requestBackground() to push the application to the background when a user closes the last screen in the display stack.

Though it might seem inefficient to keep your application always running, there are a number of steps that you can perform to ensure that your application isn't hogging resources or draining the battery. See the Efficient chapter for more information about releasing unneeded resources, stopping UI processes, and managing the backlight.

Keep the application running in the background
The following steps demonstrates how to create an application that displays a simple screen. When the BlackBerry® device user closes the screen (for example, by pressing the Escape key or by switching applications) the application is pushed to the background rather than terminated. If you want to verify that the application is still running, you can press and hold the Menu key until the Switch Application menu appears. The icon for your application is still present.
  1. Import the required classes and interfaces.
    import net.rim.device.api.ui.container.MainScreen;
    import net.rim.device.api.ui.UiApplication;
  2. Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. The BackgroundAppDemoScreen class, which is described in step 3, represents the custom screen.
    public class BackgroundAppDemo extends UiApplication
    {
        public static void main(String[] args)
        {
            BackgroundAppDemo app = new BackgroundAppDemo();
            app.enterEventDispatcher();
        }
    
        public BackgroundAppDemo()
        {
            BackgroundAppDemoScreen screen = new BackgroundAppDemoScreen();
            pushScreen(screen);
        }
  3. Create the framework for the custom screen by extending the MainScreen class. In the screen constructor, invoke setTitle() to specify the title for the screen.
    public class BackgroundAppDemoScreen extends MainScreen
    {
        public BackgroundAppDemoScreen()
        {
            setTitle("Background app demo");
        }
    }
  4. In the class for the custom screen, override onClose() and invoke requestBackground() so that the application is pushed to the background rather than terminated when a user closes the screen.
    public boolean onClose()
    {
        requestBackground();
        return true;
    }

Creating alternate entry points

You can use alternate entry points in your application, to launch an application in different ways. For example, your application could have one entry point that launches the UI component for your application and another entry point that launches a background process that listens for incoming push messages, pre-processes data, or initializes network communications with a host server.

In Bookshelf, we need at least three entry points. The main entry point, which launches the UI component for the application, runs when BlackBerry® device users click the Home screen icon for the application. A second entry point, which runs automatically when the device turns on, listens for pushed content in the background. A third entry point, which also runs automatically at startup (and then afterwards at scheduled intervals) acquires the location of the device and communicates the location to the Bookshelf web service. We'll discuss this entry point later on, when we discuss how to schedule processes to run periodically.

If you're using the BlackBerry® Java® Plug-in for Eclipse®, you can specify an alternate entry point in the BlackBerry_App_Descriptor.xml file. After you set up an entry point in Eclipse, you need to set up the main() method in your application to support the alternate entry points.

Specify the alternate entry point settings for a BlackBerry application
  1. In Eclipse®, in the Package Explorer view, expand a BlackBerry® application project.
  2. Double-click BlackBerry_App_Descriptor.xml.
  3. On the Alternate Entry Points tab, click Add.
  4. In the New Entry Point dialog box, type the name of a project in the workspace that this project invokes.
  5. Click OK.
  6. Select the Alternate entry point properties and Locale Resources.
  7. On the File menu, click Save.
Properties for the alternate entry point settings

Setting

Description

Title

Type a name for the alternate entry point that is displayed on the Home screen of the BlackBerry® device.

Application arguments

Specify the arguments to pass into the application's main() method.

Do not show the application icon on the BlackBerry device Home screen

Select this setting to run the application in the background, without displaying an icon on the Home screen of the BlackBerry device.

This setting is not available if the Application type is Library.

Auto-run on startup

Select this setting to start the application automatically when the BlackBerry device starts.

Applications that run automatically must be digitally signed by Research In Motion to run on a BlackBerry device.

Startup tier

If the Auto-run on startup setting is selected, specify the priority in which the application is started, in relation to other applications.

For third-party applications, you can select tier 6 or 7 (other start-up tiers are reserved for core BlackBerry Applications). The default setting is 7 (lowest priority).

Internationalized resource bundle available

Select this setting if the title and the description of the alternate entry point have been internationalized in a resource bundle.

Resource bundle

Select the resource header file to use for the alternate entry point.

Title ID

Select the resource key to use for the application title (for example, AEP_TITLE). If you do not provide a resource key for the application title, the BlackBerry® Java® Plug-in uses the title that is specified in the Title field.

Alternate Entry Point icons

Add the files for application icons from the project's resources or from a location external to the project.

To specify a rollover icon, select Rollover.

The number of application icons is limited to two.

Support alternate entry points in an application
The following steps demonstrate how to create a simple application that supports multiple entry points. The main() method checks to see which entry is used to enter the application by checking the application argument (this example specifies pushListener as the argument to check for). If the application is entered by using the pushListener argument, the BlackBerry® device vibrates. If the application is started by using any other argument, the application launches the UI component for the application.
  1. Import the required classes and interfaces.
    import net.rim.device.api.system.Alert;
    import net.rim.device.api.ui.container.MainScreen;
    import net.rim.device.api.ui.UiApplication;
  2. Create the application framework by extending the UiApplication class. In main(), create an if statement that checks to see which entry point is used to enter the application. In the if block, invoke Alert.setVibrate() to make the device vibrate if the application is entered by using the pushListener argument. In the else block, create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. The EntryPointsDemoScreen class, which is described in step 3, represents the custom screen.
    public class EntryPointsDemo extends UiApplication
    {
        public static void main(String[] args)
        {
            if (args != null && args.length > 0 && "pushListener".equals(args[0]))
            {
                Alert.startVibrate(2550);
            }
            else
            {
                EntryPointsDemo app = new EntryPointsDemo();
                app.enterEventDispatcher();
            }
        }
    	
        public EntryPointsDemo()
        {
            EntryPointsDemoScreen screen = new EntryPointsDemoScreen();
            pushScreen(screen);
        }
  3. Create the framework for the custom screen by extending the MainScreen class. In the screen constructor, invoke setTitle() to specify the title for the screen.
    public class EntryPointsDemoScreen extends MainScreen
    {
        public EntryPointsDemoScreen()
        {
            setTitle("Entry points demo");
        }
    }

Scheduling processes to run periodically

The Bookshelf app permits users to find books that other Bookshelf users release to the world. To notify users when there are books nearby, Bookshelf needs to send the Bookshelf web service the current location of the BlackBerry® device. Since acquiring the location of a device can consume a lot of battery power, it can make sense to schedule this process to run periodically rather than run constantly in the background. To schedule your application to run at a particular time, you can use ApplicationManager.scheduleApplication().

Schedule processes to run periodically
This task demonstrates how to create a simple application that can schedule itself to run again. The main() method checks to see which entry is used to enter the application by checking the application argument (this example specifies startVibrate as the argument to check for). Each time the application is entered using the startVibrate argument, the BlackBerry® device vibrates and schedules the application to run again. If the application is entered using any other argument, the application launches the UI component for the application and does not schedule the application to run again.
  1. Import the required classes and interfaces.
    import net.rim.device.api.system.Alert;
    import net.rim.device.api.system.ApplicationDescriptor;
    import net.rim.device.api.system.ApplicationManager;
    import net.rim.device.api.ui.container.MainScreen;
    import net.rim.device.api.ui.UiApplication;
  2. Create the application framework by extending the UiApplication class. In main(), create an if statement that checks to see which entry point is used to enter the application. In the if block, invoke scheduleVibrate(), which is the custom static method that starts the vibration and schedules the application to run again. In the else block, create an instance of the new class and invoke enterEventDispatcher() to enable the application to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the application. The ScheduleAppDemoScreen class, which is described in step 3, represents the custom screen.
    public class ScheduleAppDemo extends UiApplication
    {
        public static void main(String[] args)
        {
            if (args != null && args.length > 0 && "startVibrate".equals(args[0]))
            {
                scheduleVibrate();
            }
            else
            {
                ScheduleAppDemo app = new ScheduleAppDemo();
                app.enterEventDispatcher();
            }
        }
        public ScheduleAppDemo()
        {
            ScheduleAppDemoScreen screen = new ScheduleAppDemoScreen();
            pushScreen(screen);
        }
  3. Create the framework for the custom screen by extending the MainScreen class. In the screen constructor, invoke setTitle() to specify the title for the screen.
    public class ScheduleAppDemoScreen extends MainScreen
    {
        public ScheduleAppDemoScreen()
        {
            setTitle("Schedule app demo");
        }
    }
  4. Create scheduleVibrate(). Invoke Alert.startVibrate(2550) to make the device vibrate. Create an ApplicationDescriptor object by invoking ApplicationDescriptor.currentApplicationDescriptor() to retrieve the application descriptor of the application that is currently running. Invoke setPowerOnBehavior(ApplicationDescriptor.DO_NOT_POWER_ON) on the application descriptor so that when the application runs as scheduled, if the device is currently off, the application doesn't force the device to turn on. Invoke ApplicationManager.getApplicationManager() to retrieve an instance of the system's ApplicationManager. Invoke ApplicationManager.scheduleApplication() and specify the ApplicationDescriptor that you created and the time that you want the application to run as arguments.
    private static void scheduleVibrate()
    {
        Alert.startVibrate(2550);
        ApplicationDescriptor current = ApplicationDescriptor.
                currentApplicationDescriptor();
        current.setPowerOnBehavior(ApplicationDescriptor.DO_NOT_POWER_ON);
        ApplicationManager manager = ApplicationManager.getApplicationManager();
        manager.scheduleApplication(current, System.currentTimeMillis() 
                + 60000, true);
    }

Was this information helpful? Send us your comments.