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.

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.

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.

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.

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

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.

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.

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

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().

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