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.

Subscribing to a push initiator

You can use the Communication API to send a subscription request to a content provider's URI. In addtition to the SenderDestination object that sends the subscription request, you need to create a ReceiverDestination object that defines the MessageListener object to which the BlackBerry smartphone should deliver incoming push messages from a given URI.

The following components are involved in a subscription request:

  • SenderDestination: This component sends the subscription message to the content provider. This component is optional. You can send a subscription message using any type of network connection. For example, you can use the Network API to create an HTTPConnection and send the subscription parameters manually.
  • Subscription message: The Communication API can create a properly formed subscription message for you. You can invoke BpsSubscriptionMessageBuilder.createByteSubscriptionMessage() to retrieve a ByteMessage object that is configured for your SenderDestination, NonBlockingReceiverDestination, and the MessageListener where you want to receive incoming push messages.
  • NonBlockingReceiverDestination: This component associates a particular URI with a MessageListener where you want to receive incoming push messages, and an InboundDestinationConfiguration object.
  • InboundDestinationConfiguration: This component specifies a variety of push service parameters, such as an indicator that specifies whether your app should be started when a new push message arrives. You can create an InboundDestinationConfiguration using the InboundDestinationConfigurationFactory class.
  • MessageListener: This component processes incoming push messages.

Subscribe to a push initiator

Obtain an application ID and the local port number that your app should use to listen for incoming messages. These details are provided to the content provider that creates a server-side push app.

This example focuses on creating a subscription message and the NonBlockingReceiverDestination object for a Push Service subscription. You must send your subscription message using a SenderDestination object, or by creating a network connection manually.

Import the required classes and interfaces.

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

Initialize a NonBlockingReceiverDestination variable to manage the subscription.

NonBlockingReceiverDestination nbrd = null;

Create a MessageListener object to process incoming push messages.

try
{
    MyMessageListener pushListener = new MyMessageListener();

Create a URI object with the port information that the content provider assigns to you.

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

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

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

Create a NonBlockingReceiverDestination.

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

Create a SenderDestination to send a subscription message.

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

Configure a subscription message.

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

Send the subscription message.

bpsDestination.send(subMsg);