Package net.rim.device.api.io.transport

This package contains the implementation of the Network API.

See:
Description

Interface Summary

ConnectionAttemptListener	This interface prescribes methods for a class that listens for connection attempts performed by a ConnectionFactory object.
CoverageStatusListener	This interface prescribes methods for a class that listens for changes in transport coverage.

Class Summary

ConnectionDescriptor	This class stores information about a Connection opened by using a ConnectionFactory.
ConnectionFactory	This class enables you to create HTTP, HTTPS, socket, TLS, SSL and datagram (unicast) connections over supported transports.
TransportDescriptor	This class encapsulates information related to a specific transport instance.
TransportInfo	This class provides methods that provide information about the transport types available on a BlackBerry device.

Exception Summary

InsufficientCoverageException	This class is used to indicate that the coverage for the chosen transport type is not adequate to create a reliable connection.
NoAvailableTransportException	This class is used to indicate that no transport type is available to create a connection.

Package net.rim.device.api.io.transport Description

This package contains the implementation of the Network API.
The Network API attempts to simplify the establishment of connections over the different transports available on the Blackberry device.
It provides the means for querying the availability of transports and for selecting the most appropriated one to establish a connection.
It abstracts the details of parsing ServiceRecords and constructing proper URLs for Connector.open().
The Network API is intended for use with http://, https://, socket://, tls://, ssl:// and udp:// connections.

Determining transport availability and coverage

In order to successfully establish a connection, the desired transport has to be both available (i.e. the device must be capable of supporting that transport), and there must be sufficient coverage for the transport in question.

Availability of a specific transport type can be obtained as follows:

if ( TransportInfo.isTransportTypeAvailable(TransportInfo.TRANSPORT_MDS) ) {
   // MDS transport is available
}

All the available transports can be obtained like this:

TransportDescriptor[] transports = getAvailableTransports();

All the available transport types can be obtained like this:

int[] transportTypes = getAvailableTransportTypes();

Determining available coverage for a specific transport type is achieved like this:

if ( TransportInfo.hasSufficientCoverage(TransportInfo.TRANSPORT_MDS) ) {
   // Connecting via MDS can be attempted
}

Establishing Connections

Obtaining a http connection using the first available transport:

// Create ConnectionFactory
ConnectionFactory factory = new ConnectionFactory();

// use the factory to get a connection
ConnectionDescriptor conDescriptor = factory.getConnection("http://www.blackberry.com");

if ( conDescriptor != null ) {

   // connection succeeded
   int transportUsed = conDescriptor.getTransportDescriptor().getTransportType();

   // using the connection
   HttpConnection  httpCon = (HttpConnection) conDescriptor.getConnection();
   ...
}

Obtaining a http connection from a preference ordered list of transport types:

// make a list of transport types ordered according to preference (they will be tried in succession)
int[] preferredTransportTypes = {TransportInfo.TRANSPORT_MDS, TransportInfo.TRANSPORT_WAP2};

// Create ConnectionFactory
ConnectionFactory factory = new ConnectionFactory();

// Configure the factory
factory.setPreferredTransportTypes( preferredTransportTypes );

// use the factory to get a connection
ConnectionDescriptor conDescriptor = factory.getConnection("http://www.blackberry.com");

if ( conDescriptor != null ) {

   // connection suceeded
   int transportUsed = conDescriptor.getTransportDescriptor().getTransportType();

   // using the connection
   HttpConnection  httpCon = (HttpConnection) conDescriptor.getConnection();
   ...
}

Obtaining a http connection over a specific transport type:

// Create ConnectionFactory
ConnectionFactory factory = new ConnectionFactory();

// use the factory to get a connection
ConnectionDescriptor conDescriptor = factory.getConnection("http://www.blackberry.com", TransportInfo.TRANSPORT_WAP2, null);

if ( conDescriptor != null ) {

   // connection over WAP2 succeeded
   // using the connection
   HttpConnection  httpCon = (HttpConnection) conDescriptor.getConnection();
   ...
}

Obtaining a http connection over a specific transport:

// Create ConnectionFactory
ConnectionFactory factory = new ConnectionFactory();

// use the factory to get a connection
ConnectionDescriptor conDescriptor = factory.getConnection("http://www.blackberry.com", TransportInfo.TRANSPORT_MDS, "S109234");


if ( conDescriptor != null ) {

   // connection to specific BES succeeded
   // using the connection
   HttpConnection  httpCon = (HttpConnection) conDescriptor.getConnection();
   ...
}

Proper connection tear-down:

SocketConnection conn = null; 
InputStream is  = null; 
OutputStream os = null; 

// Create ConnectionFactory
ConnectionFactory factory = new ConnectionFactory();

// use the factory to get a connection descriptor
ConnectionDescriptor conDescriptor = factory.getConnection("socket://www.blackberry.com:80");

if ( conDescriptor != null ) {

   // cast to proper type
  conn = (SocketConnection) conDescriptor.getConnection();
  
  // use the connection
  try {
      is = conn.openInputStream(); 
      os = conn.openOutputStream(); 
      . . .
  } catch (Throwable t) {   // can also catch specific exceptions to include special handling for the different types
      // manage the exception
  } finally {
      // close streams in the opposite order from which they were opened, then close the connection
      try { os.close(); }   catch (Throwable t) {}
      try { is.close(); }   catch (Throwable t) {}
      try { conn.close(); } catch (Throwable t) {}
  }
}