Communication API

The Communication API simplifies the process of interacting with web services and other applications. The objects that you create using this API automate the process of finding an available network transport, creating a thread-safe connection, and negotiating an exchange of data with the URI or URL end point that you specify. The API is implemented in the net.rim.device.api.io.messaging package.

Within the Communication API, URI and URL end points are called destinations. You can use objects that implement the SenderDestination interface to send data to a web service and access the response. Similarly, you can use objects that implement the ReceiverDestination interface to subscribe to a push service and provide access to new messages from that service. You must use the DestinationFactory class to create an object that implements one of the Destination subinterfaces that suits your requirements.

Interface

Description

BlockingSenderDestination

You can use this interface to send a message to a web service, but this object blocks thread execution while it waits for a response from the web service.

Alternatively, BlockingSenderDestination can return a MessageFuture object. This allows thread execution to continue until you invoke one of the get() methods from the MessageFuture.

When you invoke sendReceive() in BlockingSenderDestination to send a message and wait for a response, you should not invoke it from the main event thread.

NonBlockingSenderDestination

You can use this interface to send a message to a web service. In the parameter list, pass your implementation of the MessageListener interface to receive the response from the web service.

BlockingReceiverDestination

You can use this interface to subscribe to a push service and block thread execution until you receive confirmation of your subscription request.

NonBlockingReceiverDestination

You can use this interface to subscribe to a push service. In the parameter list, pass your implementation of MessageListener to receive push messages.

FireAndForgetDestination

You can use this interface to send data to a web service when you don't expect a response.

Data that you send to and receive from a web service is wrapped in a Message object. You can set the headers and content of the data that is sent to a web service in the Message object. Alternatively, you can allow the Communication API to choose reasonable default values for your request. For example, you can request a web page by invoking SenderDestination.send() without specifying an HTTP GET command.

You can also instruct the API to automatically parse the response data from a web service. If you implement the MessageProcessor interface with your parser class, you can supply your parser object to the method in DestinationFactory that creates your Destination object. You can then retrieve the parsed response using Message.getObjectPayload().

The net.rim.device.api.io.parser packages contain message processors for a variety of standard data formats that are used on the Internet. The packages include parsers for:
  • JSON
  • RSS (RDF, Atom)
  • SOAP
  • XML

To improve efficiency, the Communication API provides large responses from web services in an InputStream object. An application can request additional data as required rather than downloading a large amount of data at once and storing it in memory on the device. This approach enables you to make better use of both network bandwidth and memory.


Was this information helpful? Send us your comments.