Opening a network connection using the Network API

After you decide which network transports to use, you can open a connection and use it to send and receive data. The ConnectionFactory object is responsible for opening connections. In addition to your preferred transports, you can use the ConnectionFactory to configure connection options such as:
  • Maximum number of connection attempts.
  • Maximum time to spend making connection attempts.
  • Delay between connection attempts.
  • Whether or not encryption is required between the connection end points.

When you are ready to open a connection, you should invoke one of the ConnectionFactory.getConnection() methods. Be sure that you call getConnection() on a thread that is separate from the main event thread. For more information about creating a thread, see the Thread class in the API reference for the BlackBerry® Java® SDK.

When you open a connection successfully, the ConnectionFactory returns a ConnectionDescriptor object. The ConnectionDescriptor contains a Connection object, and information about the transport that was used to open the connection.

For more information, see "Open a network connection using the Network API" and "Send and receive data using a network connection".

Open a network connection using the Network API

CAUTION:
The ConnectionFactory.getConnection() method blocks thread execution. You should create a separate thread to call getConnection().
  1. Import the required classes and interfaces.
    import net.rim.device.api.io.transport.*;
    import net.rim.device.api.io.transport.options.*;
    import net.rim.device.api.io.transport.TransportInfo;
    import net.rim.device.api.ui.UiApplication;
  2. Create an ordered list of preferred transports.
    int[] intTransports =
    { TransportInfo.TRANSPORT_TCP_WIFI,
      TransportInfo.TRANSPORT_WAP2,
      TransportInfo.TRANSPORT_TCP_CELLULAR
    }
  3. Configure the options for the TCP Cellular transport, if applicable.
    TcpCellularOptions tcpOptions = new TcpCellularOptions();
    if(!TcpCellularOptions.isDefaultAPNSet())
    {
        tcpOptions.setApn("My APN");
        tcpOptions.setTunnelAuthUsername("user");
        tcpOptions.setTunnelAuthPassword("password");
    }
  4. Create a ConnectionFactory object.
    ConnectionFactory factory = new ConnectionFactory();
  5. Set any other ConnectionFactory options that are applicable to your application. In this case, TCP Cellular is one of the preferred transports, so set the TCP Cellular transport options.
    factory.setTransportTypeOptions(TransportInfo.TRANSPORT_TCP_CELLULAR, tcpOptions);
    factory.setAttemptsLimit(5);
  6. Create a thread to retrieve the connection. If the connection was successful, then ConnectionFactory returns a ConnectionDescriptor object that you can use. In this step, pass the ConnectionDescriptor object to another method (displayContent()) that is responsible for displaying the content.
    Thread t = new Thread(new Runnable()
    {
        public void run()
        {
            ConnectionDescriptor cd = _factory.getConnection
                                           ("http://www.blackberry.com");
            if(cd != null) 
            {
                Connection c = cd.getConnection();
                displayContent(c);
            }
         }
    
    });
    t.start();
    
  7. Implement displayContent(). In this case, push a screen that uses a Connection parameter to retrieve and display the content, after the connection retrieval thread completes.
    private void displayContent(final Connection conn) 
    {
        UiApplication.getUiApplication().invokeLater(new Runnable()
        {
            public void run() {
                UiApplication.getUiApplication().pushScreen(new HTTPOutputScreen(conn));
            }
        });
    }
After you finish: For more information about using a connection and implementing the HTTPOutputScreen class, see "Send and receive data using a network connection".

For a complete code sample, see "Code sample: Retrieving a web page using the Network API".


Was this information helpful? Send us your comments.