am 274fb3c6: am 04a73fb6: Merge "Android Training: Making Your App Location Aware" into ics-mr1

* commit '274fb3c68077fcf710f8f9c165681265af4ffcd7':
  Android Training: Making Your App Location Aware

5 files changed, 394 insertions, 0 deletions

diff --git a/docs/html/shareables/training/LocationAware.zip b/docs/html/shareables/training/LocationAware.zip
new file mode 100644
index 0000000..e1926fa
--- /dev/null
+++ b/docs/html/shareables/training/LocationAware.zip
diff --git a/docs/html/training/location/currentlocation.jd b/docs/html/training/location/currentlocation.jd
new file mode 100644
index 0000000..4692530
--- /dev/null
+++ b/docs/html/training/location/currentlocation.jd
@@ -0,0 +1,155 @@
+page.title=Obtaining the Current Location
+parent.title=Making Your App Location Aware
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Using the Location Manager
+previous.link=locationmanager.html
+next.title=Displaying the Location Address
+next.link=geocoding.html
+
+
+@jd:body
+
+
+<!-- This is the training bar -->
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="currentlocation.html#TaskSetupLocationListener">Set Up the Location Listener</a></li>
+  <li><a href="currentlocation.html#TaskHandleLocationUpdates">Handle Multiple Sources of Location Updates</a></li>
+  <li><a href="currentlocation.html#TaskGetLastKnownLocation">Use getLastKnownLocation() Wisely</a></li>
+  <li><a href="currentlocation.html#TaskTerminateUpdates">Terminate Location Updates</a></li>
+</ol>
+
+<h2>You should also read</h2>
+
+<ul>
+  <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download
+  the sample app</a>
+<p class="filename">LocationAware.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>After setting up your application to work with {@link android.location.LocationManager}, you can begin to obtain location updates.</p>
+
+<h2 id="TaskSetupLocationListener">Set Up the Location Listener</h2>
+
+<p>The {@link android.location.LocationManager} class exposes a number of methods for applications to receive location updates.  In its simplest form, you register an event listener, identify the location manager from which you'd like to receive location updates, and specify the minimum time and distance intervals at which to receive location updates.  The {@link android.location.LocationListener#onLocationChanged(android.location.Location) onLocationChanged()} callback will be invoked with the frequency that correlates with time and distance intervals.</p>
+
+<p>
+In the sample code snippet below, the location listener is set up to receive notifications at least every 10 seconds and if the device moves by more than 10 meters.  The other callback methods notify the application any status change coming from the location provider.
+</p>
+
+<pre>
+private final LocationListener listener = new LocationListener() {
+
+    &#064;Override
+    public void onLocationChanged(Location location) {
+        // A new location update is received.  Do something useful with it.  In this case,
+        // we're sending the update to a handler which then updates the UI with the new
+        // location.
+        Message.obtain(mHandler,
+                UPDATE_LATLNG,
+                location.getLatitude() + ", " +
+                location.getLongitude()).sendToTarget();
+
+            ...
+        }
+    ...
+};
+
+mLocationManager.requestLocationUpdates(LocationManager.GPS_PROVIDER,
+        10000,          // 10-second interval.
+        10,             // 10 meters.
+        listener);
+</pre>
+
+<h2 id="TaskHandleLocationUpdates">Handle Multiple Sources of Location Updates</h2>
+
+<p>Generally speaking, a location provider with greater accuracy (GPS) requires a longer fix time than one with lower accuracy (network-based).  If you want to display location data as quickly as possible and update it as more accurate data becomes available, a common practice is to register a location listener with both GPS and network providers.  In the {@link android.location.LocationListener#onLocationChanged(android.location.Location) onLocationChanged()} callback, you'll receive location updates from multiple location providers that may have different timestamps and varying levels of accuracy.  You'll need to incorporate logic to disambiguate the location providers and discard updates that are stale and less accurate.  The code snippet below demonstrates a sample implementation of this logic.</p>
+
+<pre>
+private static final int TWO_MINUTES = 1000 * 60 * 2;
+
+/** Determines whether one Location reading is better than the current Location fix
+  * @param location  The new Location that you want to evaluate
+  * @param currentBestLocation  The current Location fix, to which you want to compare the new one
+  */
+protected boolean isBetterLocation(Location location, Location currentBestLocation) {
+    if (currentBestLocation == null) {
+        // A new location is always better than no location
+        return true;
+    }
+
+    // Check whether the new location fix is newer or older
+    long timeDelta = location.getTime() - currentBestLocation.getTime();
+    boolean isSignificantlyNewer = timeDelta &gt; TWO_MINUTES;
+    boolean isSignificantlyOlder = timeDelta &lt; -TWO_MINUTES;
+    boolean isNewer = timeDelta > 0;
+
+    // If it's been more than two minutes since the current location, use the new location
+    // because the user has likely moved
+    if (isSignificantlyNewer) {
+        return true;
+    // If the new location is more than two minutes older, it must be worse
+    } else if (isSignificantlyOlder) {
+        return false;
+    }
+
+    // Check whether the new location fix is more or less accurate
+    int accuracyDelta = (int) (location.getAccuracy() - currentBestLocation.getAccuracy());
+    boolean isLessAccurate = accuracyDelta &gt; 0;
+    boolean isMoreAccurate = accuracyDelta &lt; 0;
+    boolean isSignificantlyLessAccurate = accuracyDelta &gt; 200;
+
+    // Check if the old and new location are from the same provider
+    boolean isFromSameProvider = isSameProvider(location.getProvider(),
+            currentBestLocation.getProvider());
+
+    // Determine location quality using a combination of timeliness and accuracy
+    if (isMoreAccurate) {
+        return true;
+    } else if (isNewer &amp;&amp; !isLessAccurate) {
+        return true;
+    } else if (isNewer &amp;&amp; !isSignificantlyLessAccurate &amp;&amp; isFromSameProvider) {
+        return true;
+    }
+    return false;
+}
+
+/** Checks whether two providers are the same */
+private boolean isSameProvider(String provider1, String provider2) {
+    if (provider1 == null) {
+      return provider2 == null;
+    }
+    return provider1.equals(provider2);
+}
+</pre>
+
+<h2 id="TaskGetLastKnownLocation">Use getLastKnownLocation() Wisely</h2>
+
+<p>The setup time for getting a reasonable location fix may not be acceptable for certain applications.  You should consider calling the {@link android.location.LocationManager#getLastKnownLocation(java.lang.String) getLastKnownLocation()} method which simply queries Android for the last location update previously received by any location providers.  Keep in mind that the returned location may be stale.  You should check the timestamp and accuracy of the returned location and decide whether it is useful for your application.  If you elect to discard the location update returned from {@link android.location.LocationManager#getLastKnownLocation(java.lang.String) getLastKnownLocation()} and wait for fresh updates from the location provider(s), you should consider displaying an appropriate message before location data is received.</p>
+
+<h2 id="TaskTerminateUpdates">Terminate Location Updates</h2>
+
+<p>When you are done with using location data, you should terminate location update to reduce unnecessary consumption of power and network bandwidth.  For example, if the user navigates away from an activity where location updates are displayed, you should stop location update by calling {@link android.location.LocationManager#removeUpdates(android.location.LocationListener) removeUpdates()} in {@link android.app.Activity#onStop()}.  ({@link android.app.Activity#onStop()} is called when the activity is no longer visible.  If you want to learn more about activity lifecycle, read up on the <a href="/training/basic-activity-lifecycle/stopping.html">Starting and Stopping an Activity</a> lesson.</p>
+
+<pre>
+protected void onStop() {
+    super.onStop();
+    mLocationManager.removeUpdates(listener);
+}
+</pre>
+
+<p class="note"><strong>Note:</strong> For applications that need to continuously receive and process location updates like a near-real time mapping application, it is best to incorporate the location update logic in a background service and make use of the system notification bar to make the user aware that location data is being used.</p>
\ No newline at end of file
diff --git a/docs/html/training/location/geocoding.jd b/docs/html/training/location/geocoding.jd
new file mode 100644
index 0000000..6364976
--- /dev/null
+++ b/docs/html/training/location/geocoding.jd
@@ -0,0 +1,98 @@
+page.title=Displaying the Location Address
+parent.title=Making Your App Location Aware
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Obtaining the Current Location
+previous.link=currentlocation.html
+
+@jd:body
+
+
+<!-- This is the training bar -->
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="geocoding.html#TaskReverseGeocoding">Perform Reverse Geocoding</a></li>
+</ol>
+
+<h2>You should also read</h2>
+
+<ul>
+  <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download
+  the sample app</a>
+<p class="filename">LocationAware.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>As shown in previous lessons, location updates are received in the form of latitude and longitude coordinates.  While this format is useful for calculating distance or displaying a pushpin on a map, the decimal numbers make no sense to most end users.  If you need to display a location to user, it is much more preferable to display the address instead.</p>
+
+<h2 id="TaskReverseGeocoding">Perform Reverse Geocoding</h2>
+
+<p>Reverse-geocoding is the process of translating latitude longitude coordinates to a human-readable address.  The {@link android.location.Geocoder} API is available for this purpose.  Note that behind the scene, the API is dependent on a web service.  If such service is unavailable on the device, the API will throw a "Service not Available exception" or return an empty list of addresses.  A helper method called {@link android.location.Geocoder#isPresent()} was added in Android 2.3 (API level 9) to check for the existence of the service.</p>
+
+<p>The following code snippet demonstrates the use of the {@link android.location.Geocoder} API to perform reverse-geocoding.  Since the {@link android.location.Geocoder#getFromLocation(double, double, int) getFromLocation()} method is synchronous, you should not invoke it from the UI thread, hence an {@link android.os.AsyncTask} is used in the snippet.</p>
+
+<pre>
+private final LocationListener listener = new LocationListener() {
+
+    public void onLocationChanged(Location location) {
+        // Bypass reverse-geocoding if the Geocoder service is not available on the
+        // device. The isPresent() convenient method is only available on Gingerbread or above.
+        if (Build.VERSION.SDK_INT &gt;= Build.VERSION_CODES.GINGERBREAD &amp;&amp; Geocoder.isPresent()) {
+            // Since the geocoding API is synchronous and may take a while.  You don't want to lock
+            // up the UI thread.  Invoking reverse geocoding in an AsyncTask.
+            (new ReverseGeocodingTask(this)).execute(new Location[] {location});
+        }
+    }
+    ...
+};
+
+// AsyncTask encapsulating the reverse-geocoding API.  Since the geocoder API is blocked,
+// we do not want to invoke it from the UI thread.
+private class ReverseGeocodingTask extends AsyncTask&lt;Location, Void, Void&gt; {
+    Context mContext;
+
+    public ReverseGeocodingTask(Context context) {
+        super();
+        mContext = context;
+    }
+
+    &#064;Override
+    protected Void doInBackground(Location... params) {
+        Geocoder geocoder = new Geocoder(mContext, Locale.getDefault());
+
+        Location loc = params[0];
+        List&lt;Address&gt; addresses = null;
+        try {
+            // Call the synchronous getFromLocation() method by passing in the lat/long values.
+            addresses = geocoder.getFromLocation(loc.getLatitude(), loc.getLongitude(), 1);
+        } catch (IOException e) {
+            e.printStackTrace();
+            // Update UI field with the exception.
+            Message.obtain(mHandler, UPDATE_ADDRESS, e.toString()).sendToTarget();
+        }
+        if (addresses != null &amps;&amps; addresses.size() &gt; 0) {
+            Address address = addresses.get(0);
+            // Format the first line of address (if available), city, and country name.
+            String addressText = String.format("&#037;s, &#037;s, &#037;s",
+                    address.getMaxAddressLineIndex() &gt; 0 ? address.getAddressLine(0) : "",
+                    address.getLocality(),
+                    address.getCountryName());
+            // Update the UI via a message handler.
+            Message.obtain(mHandler, UPDATE_ADDRESS, addressText).sendToTarget();
+        }
+        return null;
+    }
+}
+</pre>
\ No newline at end of file
diff --git a/docs/html/training/location/index.jd b/docs/html/training/location/index.jd
new file mode 100644
index 0000000..48cfbc3
--- /dev/null
+++ b/docs/html/training/location/index.jd
@@ -0,0 +1,51 @@
+page.title=Making Your App Location Aware
+
+trainingnavtop=true
+startpage=true
+next.title=Using the Location Manager
+next.link=locationmanager.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>Dependencies and prerequisites</h2>
+
+<ul>
+  <li>Android 1.0 or higher (2.3+ for the sample app)</li>
+</ul>
+
+<h2>You should also read</h2>
+
+<ul>
+  <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download
+  the sample app</a>
+<p class="filename">LocationAware.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>Users bring their mobile devices with them almost everywhere.  One of the unique features available to mobile applications is location awareness.  Knowing the location and using the information wisely can bring a more contextual experience to your users.</p>
+
+<p>This class teaches you how to incorporate location based services in your Android application.  You'll learn a number of methods to receive location updates and related best practices.</p>
+
+<h2>Lessons</h2>
+
+<dl>
+  <dt><b><a href="locationmanager.html">Using the Location Manager</a></b></dt>
+    <dd>Learn how to set up your application before it can receive location updates in Android.</dd>
+
+  <dt><b><a href="currentlocation.html">Obtaining the Current Location</a></b></dt>
+    <dd>Learn how to work with underlying location technologies available on the platform to obtain current location.</dd>
+
+  <dt><b><a href="geocoding.html">Displaying a Location Address</a></b></dt>
+    <dd>Learn how to translate location coordinates into addresses that are readable to users.</dd>
+</dl>
diff --git a/docs/html/training/location/locationmanager.jd b/docs/html/training/location/locationmanager.jd
new file mode 100644
index 0000000..5da1205
--- /dev/null
+++ b/docs/html/training/location/locationmanager.jd
@@ -0,0 +1,90 @@
+page.title=Using the Location Manager
+parent.title=Making Your App Location Aware
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Obtaining the Current Location
+next.link=currentlocation.html
+
+@jd:body
+
+
+<!-- This is the training bar -->
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="locationmanager.html#TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</a></li>
+  <li><a href="locationmanager.html#TaskGetLocationManagerRef">Get a Reference to LocationManager</a></li>
+  <li><a href="locationmanager.html#TaskPickLocationProvider">Pick a Location Provider</a></li>
+</ol>
+
+<h2>You should also read</h2>
+
+<ul>
+  <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download
+  the sample app</a>
+<p class="filename">LocationAware.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>Before your application can begin receiving location updates, it needs to perform some simple steps to set up access.  In this lesson, you'll learn what these steps entail.</p>
+
+<h2 id="TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</h2>
+
+<p>The first step of setting up location update access is to declare proper permissions in the manifest.  If permissions are missing, the application will get a {@link java.lang.SecurityException} at runtime.</p>
+
+<p>Depending on the {@link android.location.LocationManager} methods used, either {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} or {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission is needed.  For example, you need to declare the {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} permission if your application uses a network-based location provider only.  The more accurate GPS requires the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission.
+Note that declaring the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission implies {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} already.</p>
+
+<p>Also, if a network-based location provider is used in the application, you'll need to declare the internet permission as well.</p>
+
+<pre>
+&lt;uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /&gt;
+&lt;uses-permission android:name="android.permission.INTERNET" /&gt;
+</pre>
+
+<h2 id="TaskGetLocationManagerRef">Get a Reference to LocationManager</h2>
+
+<p>{@link android.location.LocationManager} is the main class through which your application can access location services on Android.  Similar to other system services, a reference can be obtained from calling the {@link android.content.Context#getSystemService(java.lang.String) getSystemService()} method.  If your application intends to receive location updates in the foreground (within an {@link android.app.Activity}), you should usually perform this step in the {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method.</p>
+
+<pre>
+LocationManager locationManager =
+        (LocationManager) this.getSystemService(Context.LOCATION_SERVICE);
+</pre>
+
+<h2 id="TaskPickLocationProvider">Pick a Location Provider</h2>
+
+<p>While not required, most modern Android-powered devices can receive location updates through multiple underlying technologies, which are abstracted to an application as {@link android.location.LocationProvider} objects.  Location providers may have different performance characteristics in terms of time-to-fix, accuracy, monetary cost, power consumption, and so on.  Generally, a location provider with a greater accuracy, like the GPS, requires a longer fix time than a less accurate one, such as a network-based location provider.</p>
+
+<p>Depending on your application's use case, you have to choose a specific location provider, or multiple providers, based on similar tradeoffs.  For example, a points of interest check-in application would require higher location accuracy than say, a retail store locator where a city level location fix would suffice.  The snippet below asks for a provider backed by the GPS.</p>
+
+<pre>
+LocationProvider provider =
+        locationManager.getProvider(LocationManager.GPS_PROVIDER);
+</pre>
+
+<p>Alternatively, you can provide some input criteria such as accuracy, power requirement, monetary cost, and so on, and let Android decide a closest match location provider.  The snippet below asks for a location provider with fine accuracy and no monetary cost.  Note that the criteria may not resolve to any providers, in which case a null will be returned.  Your application should be prepared to gracefully handle the situation.</p>
+
+<pre>
+// Retrieve a list of location providers that have fine accuracy, no monetary cost, etc
+Criteria criteria = new Criteria();
+criteria.setAccuracy(Criteria.ACCURACY_FINE);
+criteria.setCostAllowed(false);
+...
+String providerName = locManager.getBestProvider(criteria, true);
+
+// If no suitable provider is found, null is returned.
+if (providerName != null) {
+   ...
+}
+</pre>