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.

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:

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.

In the
General Information section, select Auto-run on startup.

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.

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.

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:

In Eclipse, in the Package Explorer view, expand a
BlackBerry application project.

Double-click
BlackBerry_App_Descriptor.xml.

On the
Alternate Entry Points tab, click
Add.

In the
New Entry Point dialog box, type the name of a
project in the workspace that this project invokes.

Click
OK.

Select the Alternate entry point properties and Locale Resources.

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

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.

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.

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.

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.