Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Always on

By permitting your app to run in the background, you can take advantage of a number of powerful features of the BlackBerry Application Platform. Do you want your app to listen for pushed content and notify BlackBerry device users when the content arrives? Do you want your app to provide location-specific information updates to your users? These types of tasks rely on your app's ability to run in the background.

What are the benefits of an always-on app?

  • 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 app can download content before users need it.
  • Integrate with other apps. Your app can communicate with other apps that are running in the background.

Approaches to creating an always-on experience

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

Approach

Description

Run your app at startup

You can make your app run automatically when a user turns on their BlackBerry device. This is one of the most basic steps to creating an always-on experience.

Keep your app running in the background

You can have your app run in the background, and alert users when the app needs their attention. You should make it run as efficiently as possible when running the background.

Create alternate entry points

You can split your app into multiple processes by creating alternate entry points. 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

You can keep your users up-to-date by scheduling processes to run at set intervals. This allows your users to conserve memory and battery power on their devices when the processes don't need to be running.

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 page and the Proactive and notification-driven page 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 app can notify users when books are nearby.

Running an app at startup

Making your app to run when BlackBerry device users turn on their devices doesn't require any changes to your app code. If you're using the BlackBerry Java Plug-in for Eclipse, you can edit the BlackBerry_App_Descriptor.xml file so that your app runs each time the BlackBerry device turns on.

If you want your app 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 app (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.

To run an app 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 Auto-run on startup.

  3. On the File menu, click Save.

Keeping the app running in the background

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

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

Keep the app running in the background

The following steps demonstrates how to create an app that displays a simple screen. When the BlackBerry device user closes the screen (for example, by pressing the Escape key or by switching apps) the app is pushed to the background rather than terminated. You can verify that the app is still running by pressing and holding the Menu Key until the Switch Application menu appears. If your app is still running, its icon will be displayed.

Import the required classes and interfaces.

import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.UiApplication;

Create the application framework by extending the UiApplication class. In main(), create an instance of the new class and invoke enterEventDispatcher() to enable the app to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the app. The BackgroundAppDemoScreen class 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);
    }

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

In the class for the custom screen, override onClose() and invoke requestBackground() so that the app 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 app, to launch an app in different ways. For example, your app could have one entry point that launches the UI component for your app 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 app, runs when BlackBerry device users click the Home screen icon for the app. 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 app to support the alternate entry points.

To specify alternate entry points:

  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 app's main() method.

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

Select this setting to run the app 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 app automatically when the BlackBerry device starts.

Apps 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 app is started, in relation to other apps.

For third-party apps, 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 for Eclipse 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 app

Here's how to create a simple app that supports multiple entry points.

The main() method checks to see which entry is used to enter the app by checking the application argument (this example specifies pushListener as the argument to check for). If the app is entered by using the pushListener argument, the BlackBerry device vibrates. If the app is started by using any other argument, the app launches the UI component.

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;

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 app. In the if block, invoke Alert.setVibrate() to make the device vibrate if the app is entered by using the pushListener argument. In the else block, create an instance of the new class and invoke enterEventDispatcher() to enable the app to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the app. The EntryPointsDemoScreen class 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);
    }

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

For example, the Bookshelf app lets users 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. You can use ApplicationManager.scheduleApplication() to schedule your app to run at a particular time.

Schedule processes to run periodically

Here's how to create a simple app that can schedule itself to run again.

The main() method checks to see which entry is used to enter the app by checking the application argument. In this example, startVibrate is used. Each time the app is entered using the startVibrate argument, the BlackBerry device vibrates and schedules the app to run again. If the app is entered using any other argument, the app launches the UI component for the app and does not schedule the app to run again.

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;

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 app. In the if block, invoke scheduleVibrate(), which is the custom static method that starts the vibration and schedules the app to run again. In the else block, create an instance of the new class and invoke enterEventDispatcher() to enable the app to receive events. In the application constructor, invoke pushScreen() to display the custom screen for the app. The ScheduleAppDemoScreen class 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);
    }

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

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 app that is currently running. Invoke setPowerOnBehavior(ApplicationDescriptor.DO_NOT_POWER_ON) on the application descriptor so that when the app runs as scheduled, if the device is currently off, the app 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 app 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);
}