Connecting to the Network

how to implement a simple application that connects to the network. It explains some of the best practices you should follow in creating even the simplest network-connected app.

Note that to perform the network operations described in this lesson, your application manifest must include the following permissions:

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Choose an HTTP Client

Most network-connected Android apps use HTTP to send and receive data. Android includes two HTTP clients: ​​HttpURLConnection​​​ and Apache ​​HttpClient​​​. Both support HTTPS, streaming uploads and downloads, configurable timeouts, IPv6, and connection pooling. We recommend using ​​HttpURLConnection​​​ for applications targeted at Gingerbread and higher. For more discussion of this topic, see the blog post ​​ Android's HTTP Clients​​.

Check the Network Connection

Before your app attempts to connect to the network, it should check to see whether a network connection is available using ​​getActiveNetworkInfo()​​​ and ​​isConnected()​​​. Remember, the device may be out of range of a network, or the user may have disabled both Wi-Fi and mobile data access. For more discussion of this topic, see the lesson ​​Managing Network Usage​​.

public void myClickHandler(View view) {
    ...
    ConnectivityManager connMgr = (ConnectivityManager) 
        getSystemService(Context.CONNECTIVITY_SERVICE);
    NetworkInfo networkInfo = connMgr.getActiveNetworkInfo();
    if (networkInfo != null && networkInfo.isConnected()) {
        // fetch data
    } else {
        // display error
    }
    ...
}

Perform Network Operations on a Separate Thread

Network operations can involve unpredictable delays. To prevent this from causing a poor user experience, always perform network operations on a separate thread from the UI. The ​​AsyncTask​​​ class provides one of the simplest ways to fire off a new task from the UI thread. For more discussion of this topic, see the blog post ​​ Multithreading For Performance​​.

In the following snippet, the ​​myClickHandler()​​​ method invokes ​​ new DownloadWebpageTask().execute(stringUrl)​​​. The ​​DownloadWebpageTask​​​ class is a subclass of ​​AsyncTask​​​. ​​DownloadWebpageTask​​​ implements the following ​​AsyncTask​​ methods:

• ​​doInBackground()​​​ executes the method ​​downloadUrl()​​​. It passes the web page URL as a parameter. The method ​​downloadUrl()​​ fetches and processes the web page content. When it finishes, it passes back a result string.
• ​​onPostExecute()​​ takes the returned string and displays it in the UI.

public class HttpExampleActivity extends Activity {
    private static final String DEBUG_TAG = "HttpExample";
    private EditText urlText;
    private TextView textView;
    
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);   
        urlText = (EditText) findViewById(R.id.myUrl);
        textView = (TextView) findViewById(R.id.myText);
    }

    // When user clicks button, calls AsyncTask.
    // Before attempting to fetch the URL, makes sure that there is a network connection.
    public void myClickHandler(View view) {
        // Gets the URL from the UI's text field.
        String stringUrl = urlText.getText().toString();
        ConnectivityManager connMgr = (ConnectivityManager) 
            getSystemService(Context.CONNECTIVITY_SERVICE);
        NetworkInfo networkInfo = connMgr.getActiveNetworkInfo();
        if (networkInfo != null && networkInfo.isConnected()) {
            new DownloadWebpageText().execute(stringUrl);
        } else {
            textView.setText("No network connection available.");
        }
    }

     // Uses AsyncTask to create a task away from the main UI thread. This task takes a 
     // URL string and uses it to create an HttpUrlConnection. Once the connection
     // has been established, the AsyncTask downloads the contents of the webpage as
     // an InputStream. Finally, the InputStream is converted into a string, which is
     // displayed in the UI by the AsyncTask's onPostExecute method.
     private class DownloadWebpageText extends AsyncTask
   
     {
        @Override
        protected String doInBackground(String... urls) {
              
            // params comes from the execute() call: params[0] is the url.
            try {
                return downloadUrl(urls[0]);
            } catch (IOException e) {
                return "Unable to retrieve web page. URL may be invalid.";
            }
        }
        // onPostExecute displays the results of the AsyncTask.
        @Override
        protected void onPostExecute(String result) {
            textView.setText(result);
       }
    }
    ...
}

The sequence of events in this snippet is as follows:

1. When users click the button that invokes ​​myClickHandler()​​​, the app passes the specified URL to the ​​AsyncTask​​​ subclass ​​DownloadWebpageTask​​.
2. The ​​AsyncTask​​​ method ​​doInBackground()​​​ calls the ​​downloadUrl()​​ method.
3. The ​​downloadUrl()​​​ method takes a URL string as a parameter and uses it to create a ​​URL​​ object.
4. The ​​URL​​​ object is used to establish an ​​HttpURLConnection​​.
5. Once the connection has been established, the ​​HttpURLConnection​​​ object fetches the web page content as an ​​InputStream​​.
6. The ​​InputStream​​​ is passed to the ​​readIt()​​ method, which converts the stream to a string.
7. Finally, the ​​AsyncTask​​​'s ​​onPostExecute()​​ method displays the string in the main activity's UI.

Connect and Download Data

In your thread that performs your network transactions, you can use ​​HttpURLConnection​​​ to perform a ​​GET​​​ and download your data. After you call ​​connect()​​​, you can get an ​​InputStream​​​ of the data by calling ​​getInputStream()​​.

In the following snippet, the ​​doInBackground()​​​ method calls the method ​​downloadUrl()​​​. The ​​downloadUrl()​​​ method takes the given URL and uses it to connect to the network via ​​HttpURLConnection​​​. Once a connection has been established, the app uses the method ​​getInputStream()​​​ to retrieve the data as an ​​InputStream​​.

// Given a URL, establishes an HttpUrlConnection and retrieves
// the web page content as a InputStream, which it returns as
// a string.
private String downloadUrl(String myurl) throws IOException {
    InputStream is = null;
    // Only display the first 500 characters of the retrieved
    // web page content.
    int len = 500;
        
    try {
        URL url = new URL(myurl);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setReadTimeout(10000 /* milliseconds */);
        conn.setConnectTimeout(15000 /* milliseconds */);
        conn.setRequestMethod("GET");
        conn.setDoInput(true);
        // Starts the query
        conn.connect();
        int response = conn.getResponseCode();
        Log.d(DEBUG_TAG, "The response is: " + response);
        is = conn.getInputStream();

        // Convert the InputStream into a string
        String contentAsString = readIt(is, len);
        return contentAsString;
        
    // Makes sure that the InputStream is closed after the app is
    // finished using it.
    } finally {
        if (is != null) {
            is.close();
        } 
    }
}

Note that the method ​​getResponseCode()​​​ returns the connection's ​​ status code​​. This is a useful way of getting additional information about the connection. A status code of 200 indicates success.

Convert the InputStream to a String

An ​​InputStream​​​ is a readable source of bytes. Once you get an ​​InputStream​​, it's common to decode or convert it into a target data type. For example, if you were downloading image data, you might decode and display it like this:

InputStream is = null;
...
Bitmap bitmap = BitmapFactory.decodeStream(is);
ImageView imageView = (ImageView) findViewById(R.id.image_view);
imageView.setImageBitmap(bitmap);
 
In the example shown above, the ​​InputStream​​​ represents the text of a web page. This is how the example converts the ​​InputStream​​ to a string so that the activity can display it in the UI:
 
// Reads an InputStream and converts it to a String.
public String readIt(InputStream stream, int len) throws IOException, UnsupportedEncodingException {
    Reader reader = null;
    reader = new InputStreamReader(stream, "UTF-8");        
    char[] buffer = new char[len];
    reader.read(buffer);
    return new String(buffer);
}