Before getting into the specifics of creating a push solution, it is helpful to understand the features and architecture of the BlackBerry® Push Service. The BlackBerry Push Service provides developers with access to the push technology upon which much of the success of BlackBerry devices is built.

A push solution is made up of three main components:

Be aware that to create a push solution, you must first register your solution with the BlackBerry Push Service. When you register, you will receive an Application ID for your push solution, which is used to associate your Push Initiator with your push-enabled application.

To listen for and receive push content, a push-enabled application must:

In addition, to ensure that the application is always ready to receive push content while the BlackBerry device is on, we'll need to create an alternate entry point for Bookshelf. This entry point runs a background process automatically when the BlackBerry device turns on but does not display the UI, allowing Bookshelf to receive and process push content as it arrives. See the Always on chapter for more information on setting up an alternate entry point.

1. Import the required classes and interfaces.

   import net.rim.device.api.io.messaging.*; 
   import java.io.IOException; 
   import java.io.InputStream;

2. Define a class that implements the MessageListener interface.

   public class MyMessageListener implements MessageListener {

3. Implement onMessage().

       public void onMessage(Destination dest, Message incomingMessage) {

4. Initialize a String variable (in this sample, called payload) to hold the response data.

           String payload = null;

5. If the response is a ByteMessage object, retrieve the response as a String and assign it to payload.

           if (incomingMessage instanceof ByteMessage) 
           { 
               ByteMessage reply = (ByteMessage) incomingMessage; 
               payload = (String) reply.getStringPayload(); 
           }

6. If the response is a StreamMessage object, retrieve the response as an InputStream object.

           else if(incomingMessage instanceof StreamMessage)
           { 
               StreamMessage reply = (StreamMessage) incomingMessage; 
               InputStream is = reply.getStreamPayload();

   1. If the response is small, convert the contents of the stream into a byte array.

                  byte[] data = null; 
                  try 
                  { 
                      data = net.rim.device.api.io.IOUtilities.streamToBytes(is); 
                  } 
                  catch (IOException e) 
                  { 
                      // process the error 
                  }

   2. If the conversion was successful, convert the byte array to a String and assign it to payload.

                  if(data != null) 
                  {
                      payload = new String(data); 
                  } 
              }

7. If payload contains data, issue a notification to alert the BlackBerry® device user about the newly arrived content.

           if(payload!=null) 
           { 
               updateIndicator( 1 );
           }

8. Implement onMessageCancelled() and onMessageFailed().

1. Import the required classes and interfaces.

   import net.rim.device.api.io.messaging.*;

2. Initialize a NonBlockingReceiverDestination variable to manage the subscription.

   NonBlockingReceiverDestination nbrd = null;

3. Create a MessageListener object to process incoming push content.

   try
   {
       MyMessageListener pushListener = new MyMessageListener();

4. Create a URI object that specifies the port number that the application listens on.

   URI pushURI = URI.create("http://:101");

5. Create an InboundDestinationConfiguration object to set parameters for the push subscription.

       InboundDestinationConfiguration config = InboundDestinationConfigurationFactory.createBPSConfiguration
           (false, // don't start this application when a push message arrives
           false, // allow other applications to receive these push messages
           false, // do not store these messages (persistence not supported)
           "12-Ab234cD5eF67h890", // application ID,
           BPSuri); // BlackBerry Push Service URI

6. Create a NonBlockingReceiverDestination object that specifies the InboundDestinationConfiguration object that defines the parameters for the push subscription, the port number on which the app listens, and the MessageListener object responsible for receiving and processing the incoming push content.

           nbrd = DestinationFactory.createNonBlockingReceiverDestination
                       (config, pushURI, pushListener);

7. Create a NonBlockingSenderDestination object to send a subscription message.

           NonBlockingSenderDestination bpsDestination =
                       DestinationFactory.createNonBlockingSenderDestination
                       (myContext, uri, responseListener);

8. Build the subscription message.

           ByteMessage subMsg =
                       BpsSubscriptionMessageBuilder.createByteSubscriptionMessage
                       (bpsDestination, nbrd, "user", "pwd");

9. Send the subscription message.

           bpsDestination.send();

1. Import the required classes and interfaces.

   import net.rim.blackberry.api.messagelist.*;
   import net.rim.device.api.system.EncodedImage;

2. Obtain a reference to an ApplicationIndicatorRegistry object.

   ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();

3. Create an indicator based on an encoded image by invoking EncodedImage.getEncodedImageResource() and passing in the file name as an argument. Save a reference to the encoded image in an EncodedImage variable. Create an instance of the ApplicationIcon class using the EncodedImage as an argument.

   EncodedImage image = EncodedImage.getEncodedImageResource("BookShelf-Icon-notification-32x32.png" );
   ApplicationIcon icon = new ApplicationIcon( image );

4. Register the image as an application indicator by invoking ApplicationIndicatorRegistry.register(). In the following code sample, the second parameter specifies that the indicator can have a numeric value associated with it (for example, new message count). The third parameter specifies that the indicator should be visible.

   ApplicationIndicator indicator = reg.register( icon, true, true);

5. Retrieve the registered indicator by invoking ApplicationIndicatorRegistry.getApplicationIndicator(). Save the return value in an ApplicationIndicator variable.

   ApplicationIndicator appIndicator = reg.getApplicationIndicator();

6. Set the image and value for the indicator by invoking ApplicationIndicator.set(). You should consider only showing a value if it is greater than 0.

   appIndicator.set( newIcon, newValue );