page.title=Connecting to the Network
parent.title=Performing Network Operations
parent.link=index.html
trainingnavtop=true
next.title=Managing Network Usage
next.link=managing.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#http-client">Choose an HTTP Client</a></li>
<li><a href="#connection">Check the Network Connection</a></li>
<li><a href="#AsyncTask">Perform Network Operations on a Separate Thread</a></li>
<li><a href="#download">Connect and Download Data</a></li>
<li><a href="#stream">Convert the InputStream to a String</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}training/volley/index.html">Transmitting Network Data Using Volley</a></li>
<li><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a></li>
<li><a href="{@docRoot}training/efficient-downloads/index.html">Transferring Data Without Draining the Battery</a></li>
<li><a href="{@docRoot}guide/webapps/index.html">Web Apps Overview</a></li>
<li><a href="{@docRoot}guide/components/fundamentals.html">Application Fundamentals</a></li>
</ul>
</div>
</div>
<p>This lesson shows you 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.</p>
<p>Note that to perform the network operations described in this lesson, your
application manifest must include the following permissions:</p>
<pre><uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /></pre>
<h2 id="http-client">Choose an HTTP Client</h2>
<p>Most network-connected Android apps use HTTP to send and receive data.
Android includes two HTTP clients: {@link java.net.HttpURLConnection} and Apache
{@link org.apache.http.client.HttpClient}. Both support HTTPS, streaming uploads and downloads, configurable
timeouts, IPv6, and connection pooling. We recommend using {@link
java.net.HttpURLConnection} for applications targeted at Gingerbread and higher. For
more discussion of this topic, see the blog post <a
href="http://android-developers.blogspot.com/2011/09/androids-http-clients.html"
>Android's HTTP Clients</a>.</p>
<h2 id="connection">Check the Network Connection</h2>
<p>Before your app attempts to connect to the network, it should check to see whether a
network connection is available using
{@link android.net.ConnectivityManager#getActiveNetworkInfo getActiveNetworkInfo()}
and {@link android.net.NetworkInfo#isConnected 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 <a
href="{@docRoot}training/basics/network-ops/managing.html">Managing Network
Usage</a>.</p>
<pre>
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
}
...
}</pre>
<h2 id="AsyncTask">Perform Network Operations on a Separate Thread</h2>
<p>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 {@link android.os.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 <a
href="http://android-developers.blogspot.com/2010/07/multithreading-for-
performance.html">Multithreading For Performance</a>.</p>
<p>In the following snippet, the <code>myClickHandler()</code> method invokes <code>new
DownloadWebpageTask().execute(stringUrl)</code>. The
<code>DownloadWebpageTask</code> class is a subclass of {@link
android.os.AsyncTask}. <code>DownloadWebpageTask</code> implements the following
{@link android.os.AsyncTask} methods:</p>
<ul>
<li>{@link android.os.AsyncTask#doInBackground doInBackground()} executes
the method <code>downloadUrl()</code>. It passes the web page URL as a
parameter. The method <code>downloadUrl()</code> fetches and processes the web
page content. When it finishes, it passes back a result string.</li>
<li>{@link android.os.AsyncTask#onPostExecute onPostExecute()} takes the
returned string and displays it in the UI.</li>
</ul>
<pre>
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 DownloadWebpageTask().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 DownloadWebpageTask extends AsyncTask<String, Void, String> {
@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);
}
}
...
}</pre>
<p>The sequence of events in this snippet is as follows:</p>
<ol>
<li>When users click the button that invokes {@code myClickHandler()},
the app passes
the specified URL to the {@link android.os.AsyncTask} subclass
<code>DownloadWebpageTask</code>.</li>
<li>The {@link android.os.AsyncTask} method {@link
android.os.AsyncTask#doInBackground doInBackground()} calls the
<code>downloadUrl()</code> method. </li>
<li>The <code>downloadUrl()</code> method takes a URL string as a parameter
and uses it to create a {@link java.net.URL} object.</li>
<li>The {@link java.net.URL} object is used to establish an {@link
java.net.HttpURLConnection}.</li>
<li>Once the connection has been established, the {@link
java.net.HttpURLConnection} object fetches the web page content as an {@link
java.io.InputStream}.</li>
<li>The {@link java.io.InputStream} is passed to the <code>readIt()</code>
method, which converts the stream to a string.</li>
<li>Finally, the {@link android.os.AsyncTask}'s {@link
android.os.AsyncTask#onPostExecute onPostExecute()} method displays the string
in the main activity's UI.</li>
</ol>
<h2 id="download">Connect and Download Data</h2>
<p>In your thread that performs your network transactions, you can use
{@link java.net.HttpURLConnection} to perform a {@code GET} and download your data.
After you call {@code connect()}, you can get an {@link java.io.InputStream} of the data
by calling {@code getInputStream()}.
<p>In the following snippet, the {@link android.os.AsyncTask#doInBackground
doInBackground()} method calls the method <code>downloadUrl()</code>. The
<code>downloadUrl()</code> method takes the given URL and uses it to connect to
the network via {@link java.net.HttpURLConnection}. Once a connection has been
established, the app uses the method <code>getInputStream()</code> to retrieve
the data as an {@link java.io.InputStream}.</p>
<pre>
// 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();
}
}
}</pre>
<p>Note that the method <code>getResponseCode()</code> returns the connection's
<a href="http://www.w3.org/Protocols/HTTP/HTRESP.html">status code</a>. This is
a useful way of getting additional information about the connection. A status
code of 200 indicates success.</p>
<h2 id="stream">Convert the InputStream to a String</h2>
<p>An {@link java.io.InputStream} is a readable source of bytes. Once you get an {@link java.io.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:</p>
<pre>InputStream is = null;
...
Bitmap bitmap = BitmapFactory.decodeStream(is);
ImageView imageView = (ImageView) findViewById(R.id.image_view);
imageView.setImageBitmap(bitmap);
</pre>
<p>In the example shown above, the {@link java.io.InputStream} represents the text of a
web page. This is how the example converts the {@link java.io.InputStream} to
a string so that the activity can display it in the UI:</p>
<pre>// 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);
}</pre>