Home | History | Annotate | Download | only in network-ops
      1 page.title=Connecting to the Network
      2 parent.title=Performing Network Operations
      3 parent.link=index.html
      4 
      5 trainingnavtop=true
      6 next.title=Managing Network Usage
      7 next.link=managing.html
      8 
      9 @jd:body
     10  
     11 <div id="tb-wrapper"> 
     12 <div id="tb">
     13 
     14 
     15 
     16 <h2>This lesson teaches you to</h2>
     17 <ol>
     18   <li><a href="#http-client">Choose an HTTP Client</a></li>
     19   <li><a href="#connection">Check the Network Connection</a></li>
     20   <li><a href="#AsyncTask">Perform Network Operations on a Separate Thread</a></li>
     21   <li><a href="#download">Connect and Download Data</a></li>
     22   <li><a href="#stream">Convert the InputStream to a String</a></li>
     23   
     24 </ol>
     25 
     26 <h2>You should also read</h2>
     27 <ul>
     28   <li><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a></li>
     29   <li><a href="{@docRoot}training/efficient-downloads/index.html">Transferring Data Without Draining the Battery</a></li>
     30   <li><a href="{@docRoot}guide/webapps/index.html">Web Apps Overview</a></li>
     31   <li><a href="{@docRoot}guide/components/fundamentals.html">Application Fundamentals</a></li>
     32 </ul>
     33 
     34 </div> 
     35 </div>
     36 
     37 <p>This lesson shows you how to implement a simple application that connects to
     38 the network. It explains some of the best practices you should follow in
     39 creating even the simplest network-connected app.</p>
     40 
     41 <p>Note that to perform the network operations described in this lesson, your
     42 application manifest must include the following permissions:</p>
     43 
     44 <pre>&lt;uses-permission android:name=&quot;android.permission.INTERNET&quot; /&gt;
     45 &lt;uses-permission android:name=&quot;android.permission.ACCESS_NETWORK_STATE&quot; /&gt;</pre>
     46 
     47 
     48 
     49 <h2 id="http-client">Choose an HTTP Client</h2>
     50 
     51 <p>Most network-connected Android apps  use HTTP to send and receive  data.
     52 Android includes two HTTP clients: {@link java.net.HttpURLConnection} and Apache
     53  {@link org.apache.http.client.HttpClient}. Both support HTTPS, streaming uploads and downloads,  configurable
     54 timeouts, IPv6, and connection pooling. We recommend using {@link
     55 java.net.HttpURLConnection} for applications targeted at Gingerbread and higher. For
     56 more discussion of this topic, see the blog post <a
     57 href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html"
     58 >Android's HTTP Clients</a>.</p>
     59 
     60 <h2 id="connection">Check the Network Connection</h2>
     61 
     62 <p>Before your app attempts to connect to the network, it should check to see whether a
     63 network connection is available using 
     64 {@link android.net.ConnectivityManager#getActiveNetworkInfo getActiveNetworkInfo()}
     65 and {@link android.net.NetworkInfo#isConnected isConnected()}. 
     66 Remember, the device may be out of range of a
     67 network, or the user may have disabled both Wi-Fi and mobile data access. 
     68 For more discussion of this topic, see the lesson <a
     69 href="{@docRoot}training/basics/network-ops/managing.html">Managing Network
     70 Usage</a>.</p>
     71 
     72 <pre>
     73 public void myClickHandler(View view) {
     74     ...
     75     ConnectivityManager connMgr = (ConnectivityManager) 
     76         getSystemService(Context.CONNECTIVITY_SERVICE);
     77     NetworkInfo networkInfo = connMgr.getActiveNetworkInfo();
     78     if (networkInfo != null &amp;&amp; networkInfo.isConnected()) {
     79         // fetch data
     80     } else {
     81         // display error
     82     }
     83     ...
     84 }</pre>
     85 
     86 <h2 id="AsyncTask">Perform Network Operations on a Separate Thread</h2>
     87 
     88 <p>Network operations can involve unpredictable delays. To prevent this from
     89 causing a poor user experience, always perform network operations on a separate
     90 thread from the UI. The {@link android.os.AsyncTask} class provides one of the
     91 simplest ways to fire off a new task from the UI thread. For more discussion of
     92 this topic, see the blog post <a
     93 href="http://android-developers.blogspot.com/2010/07/multithreading-for-
     94 performance.html">Multithreading For Performance</a>.</p>
     95 
     96 
     97 <p>In the following snippet, the <code>myClickHandler()</code> method invokes <code>new
     98 DownloadWebpageTask().execute(stringUrl)</code>. The
     99 <code>DownloadWebpageTask</code> class is a subclass of {@link
    100 android.os.AsyncTask}. <code>DownloadWebpageTask</code> implements the following
    101 {@link android.os.AsyncTask} methods:</p>
    102 
    103     <ul>
    104     
    105       <li>{@link android.os.AsyncTask#doInBackground doInBackground()} executes
    106 the method <code>downloadUrl()</code>. It passes the  web page URL as a
    107 parameter. The method <code>downloadUrl()</code> fetches and processes the web
    108 page content. When it finishes, it passes back a result string.</li>
    109       
    110       <li>{@link android.os.AsyncTask#onPostExecute onPostExecute()} takes the
    111 returned string and displays it in the UI.</li>
    112       
    113       
    114     </ul>
    115     
    116 <pre>
    117 public class HttpExampleActivity extends Activity {
    118     private static final String DEBUG_TAG = "HttpExample";
    119     private EditText urlText;
    120     private TextView textView;
    121     
    122     &#64;Override
    123     public void onCreate(Bundle savedInstanceState) {
    124         super.onCreate(savedInstanceState);
    125         setContentView(R.layout.main);   
    126         urlText = (EditText) findViewById(R.id.myUrl);
    127         textView = (TextView) findViewById(R.id.myText);
    128     }
    129 
    130     // When user clicks button, calls AsyncTask.
    131     // Before attempting to fetch the URL, makes sure that there is a network connection.
    132     public void myClickHandler(View view) {
    133         // Gets the URL from the UI's text field.
    134         String stringUrl = urlText.getText().toString();
    135         ConnectivityManager connMgr = (ConnectivityManager) 
    136             getSystemService(Context.CONNECTIVITY_SERVICE);
    137         NetworkInfo networkInfo = connMgr.getActiveNetworkInfo();
    138         if (networkInfo != null &amp;&amp; networkInfo.isConnected()) {
    139             new DownloadWebpageTask().execute(stringUrl);
    140         } else {
    141             textView.setText("No network connection available.");
    142         }
    143     }
    144 
    145      // Uses AsyncTask to create a task away from the main UI thread. This task takes a 
    146      // URL string and uses it to create an HttpUrlConnection. Once the connection
    147      // has been established, the AsyncTask downloads the contents of the webpage as
    148      // an InputStream. Finally, the InputStream is converted into a string, which is
    149      // displayed in the UI by the AsyncTask's onPostExecute method.
    150      private class DownloadWebpageTask extends AsyncTask&lt;String, Void, String&gt; {
    151         &#64;Override
    152         protected String doInBackground(String... urls) {
    153               
    154             // params comes from the execute() call: params[0] is the url.
    155             try {
    156                 return downloadUrl(urls[0]);
    157             } catch (IOException e) {
    158                 return "Unable to retrieve web page. URL may be invalid.";
    159             }
    160         }
    161         // onPostExecute displays the results of the AsyncTask.
    162         &#64;Override
    163         protected void onPostExecute(String result) {
    164             textView.setText(result);
    165        }
    166     }
    167     ...
    168 }</pre>
    169 
    170 <p>The sequence of events in this snippet is as follows:</p>
    171 <ol>
    172 
    173   <li>When users click the button that invokes {@code myClickHandler()}, 
    174   the app passes
    175 the specified URL to the {@link android.os.AsyncTask} subclass
    176 <code>DownloadWebpageTask</code>.</li>
    177  
    178  <li>The {@link android.os.AsyncTask} method {@link
    179 android.os.AsyncTask#doInBackground doInBackground()} calls the 
    180 <code>downloadUrl()</code> method. </li>
    181   
    182   <li>The <code>downloadUrl()</code> method takes a URL string as a parameter
    183 and uses it to create a {@link java.net.URL} object.</li>
    184   
    185   <li>The {@link java.net.URL} object is used to establish an {@link
    186 java.net.HttpURLConnection}.</li>
    187   
    188   <li>Once the connection has been established, the {@link
    189 java.net.HttpURLConnection} object fetches the web page content as an {@link
    190 java.io.InputStream}.</li>
    191   
    192   <li>The {@link java.io.InputStream} is passed to the <code>readIt()</code>
    193 method, which converts the stream to a string.</li>
    194   
    195   <li>Finally, the {@link android.os.AsyncTask}'s {@link
    196 android.os.AsyncTask#onPostExecute onPostExecute()} method displays the string
    197 in the main activity's UI.</li>
    198 
    199 </ol>
    200 
    201  <h2 id="download">Connect and Download Data</h2>
    202  
    203  <p>In your thread that performs your network transactions, you can use 
    204  {@link java.net.HttpURLConnection} to perform a {@code GET} and download your data. 
    205  After you call {@code connect()}, you can get an {@link java.io.InputStream} of the data 
    206  by calling {@code getInputStream()}.
    207  
    208  <p>In the following snippet, the {@link android.os.AsyncTask#doInBackground
    209 doInBackground()} method calls the method <code>downloadUrl()</code>. The
    210 <code>downloadUrl()</code> method takes the given URL and uses it to connect to
    211 the network via {@link java.net.HttpURLConnection}. Once a connection has been
    212 established, the app uses the method <code>getInputStream()</code> to retrieve
    213 the data as an {@link java.io.InputStream}.</p>
    214  
    215 <pre>
    216 // Given a URL, establishes an HttpUrlConnection and retrieves
    217 // the web page content as a InputStream, which it returns as
    218 // a string.
    219 private String downloadUrl(String myurl) throws IOException {
    220     InputStream is = null;
    221     // Only display the first 500 characters of the retrieved
    222     // web page content.
    223     int len = 500;
    224         
    225     try {
    226         URL url = new URL(myurl);
    227         HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    228         conn.setReadTimeout(10000 /* milliseconds */);
    229         conn.setConnectTimeout(15000 /* milliseconds */);
    230         conn.setRequestMethod("GET");
    231         conn.setDoInput(true);
    232         // Starts the query
    233         conn.connect();
    234         int response = conn.getResponseCode();
    235         Log.d(DEBUG_TAG, "The response is: " + response);
    236         is = conn.getInputStream();
    237 
    238         // Convert the InputStream into a string
    239         String contentAsString = readIt(is, len);
    240         return contentAsString;
    241         
    242     // Makes sure that the InputStream is closed after the app is
    243     // finished using it.
    244     } finally {
    245         if (is != null) {
    246             is.close();
    247         } 
    248     }
    249 }</pre>
    250 
    251 <p>Note that the method <code>getResponseCode()</code> returns the connection's
    252 <a href="http://www.w3.org/Protocols/HTTP/HTRESP.html">status code</a>. This is
    253 a useful way of getting additional information about the connection. A status
    254 code of 200 indicates success.</p>
    255 
    256 <h2 id="stream">Convert the InputStream to a String</h2>
    257 
    258 <p>An {@link java.io.InputStream} is a readable source of bytes. Once you get an {@link java.io.InputStream}, 
    259 it's common to decode or convert it into a
    260 target data type. For example, if you were downloading image data, you might
    261 decode and display it like this:</p>
    262 
    263 <pre>InputStream is = null;
    264 ...
    265 Bitmap bitmap = BitmapFactory.decodeStream(is);
    266 ImageView imageView = (ImageView) findViewById(R.id.image_view);
    267 imageView.setImageBitmap(bitmap);
    268 </pre>
    269 
    270 <p>In the example shown above, the {@link java.io.InputStream} represents the text of a
    271 web page. This is how the example converts the {@link java.io.InputStream} to
    272 a string so that the activity can display it in the UI:</p>
    273 
    274 <pre>// Reads an InputStream and converts it to a String.
    275 public String readIt(InputStream stream, int len) throws IOException, UnsupportedEncodingException {
    276     Reader reader = null;
    277     reader = new InputStreamReader(stream, "UTF-8");        
    278     char[] buffer = new char[len];
    279     reader.read(buffer);
    280     return new String(buffer);
    281 }</pre>
    282 
    283 
    284 
    285