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.

Communication API

The Communication API simplifies the process of interacting with web
services and other apps. 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. Use the
DestinationFactory class to create an object that
implements 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 app can request
additional data as required rather than downloading a large amount of data at
once and storing it in memory on the smartphone. This approach enables you to make
better use of both network bandwidth and memory.

Communicating with HTTP servers

To send a command to an HTTP server, you need a
SenderDestination object to communicate with an end
point. The
SenderDestination object is responsible for queuing and retrieving
messages for delivery. The
DestinationFactory class creates and maintains a list of
Destination objects that you can use to communicate with
an end point.

Before you create a
SenderDestination, you should check whether one exists
by invoking
getSenderDestination(). You can access an existing
destination by providing the name of the
Context object that you supplied when you invoked any of
the
DestinationFactory.create...() methods.

When you finish exchanging data with an end point, you should invoke
DestinationFactory.release() or
DestinationFactory.destory(). The
release() method removes the association between a
Destination and the inbound and outbound message queues.
After you invoke
release(), the API continues to attempt the delivery of
messages in the queue. You can use
release() when your app is not in a state to
send and receive messages. In addition to removing the association between a
Destination and the a message queue,
destroy() also destroys the message queue. After you
invoke
destory(), any messages in the queue will be deleted.

A message contains the details of your command, including the HTTP
request method and any additional data that you require. If you do not specify
all parameters for your message, default values are provided by the
Communication API.

After you send your message, you may need to listen for a response. For
BlockingSenderDestination objects, you need to create a
Thread object when you invoke one of the
sendReceive() methods. For
NonBlockingSenderDestination objects, you must create a
MessageListener object to receive the response.

In either case, you need to process a
Message object that contains the response. By default,
the body of the
Message contains the raw response data. You can choose
to specify a message processor from the
net.rim.device.api.io.parser package, or create your own
using the
MessageProcessor interface.

If necessary, you can connect multiple message processors together. The
MessageProcessorChain class shares memory between the
MessageProcessor objects to improve efficiency. For
example, if you receive video data that uses custom encoding and compression,
you can separate the decoding and decompression logic into separate message
processors, and then use
MessageProcessorChain to group them together.

A
Destination object can supply login information, such as
a user name and password, when a web server requests it. Login information is
stored in the
Context object that you supply when you create a
Destination using the
DestinationFactory class.

context = new Context("DemoContext", new CredentialsCollector() {
public UsernamePasswordCredentials getBasicAuthenticationCredentials
(String aeID, Hashtable properties) {
// Provide or retrieve authentication credentials here.
// For example, you could display a dialog box to ask your user
// to enter a username and password, then return them from
// this method.
return new UsernamePasswordCredentials("username", "password");
}
});