Make UsageStats API comply with API Council

- Fix documentation to mention units of time in APIs.
- Return a Map instead of an ArrayMap

Bug:17289531
Change-Id: I0a2cfdc0bc003eeeb65a16e37bb7b991624b2853

6 files changed, 26 insertions, 22 deletions

diff --git a/api/current.txt b/api/current.txt
index 6815ba1..d78885d 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -5748,7 +5748,7 @@ package android.app.usage {
   }
 
   public final class UsageStatsManager {
-    method public android.util.ArrayMap<java.lang.String, android.app.usage.UsageStats> queryAndAggregateUsageStats(long, long);
+    method public java.util.Map<java.lang.String, android.app.usage.UsageStats> queryAndAggregateUsageStats(long, long);
     method public android.app.usage.UsageEvents queryEvents(long, long);
     method public java.util.List<android.app.usage.UsageStats> queryUsageStats(int, long, long);
     field public static final int INTERVAL_BEST = 4; // 0x4
diff --git a/core/java/android/app/usage/UsageEvents.java b/core/java/android/app/usage/UsageEvents.java
index 2431ad0..fb80de2 100644
--- a/core/java/android/app/usage/UsageEvents.java
+++ b/core/java/android/app/usage/UsageEvents.java
@@ -106,7 +106,9 @@ public final class UsageEvents implements Parcelable {
         }
 
         /**
-         * The time at which this event occurred.
+         * The time at which this event occurred, measured in milliseconds since the epoch.
+         * <p/>
+         * See {@link System#currentTimeMillis()}.
          */
         public long getTimeStamp() {
             return mTimeStamp;
diff --git a/core/java/android/app/usage/UsageStats.java b/core/java/android/app/usage/UsageStats.java
index e47a802..abfc435 100644
--- a/core/java/android/app/usage/UsageStats.java
+++ b/core/java/android/app/usage/UsageStats.java
@@ -81,28 +81,36 @@ public final class UsageStats implements Parcelable {
     }
 
     /**
-     * Get the beginning of the time range this {@link android.app.usage.UsageStats} represents.
+     * Get the beginning of the time range this {@link android.app.usage.UsageStats} represents,
+     * measured in milliseconds since the epoch.
+     * <p/>
+     * See {@link System#currentTimeMillis()}.
      */
     public long getFirstTimeStamp() {
         return mBeginTimeStamp;
     }
 
     /**
-     * Get the end of the time range this {@link android.app.usage.UsageStats} represents.
+     * Get the end of the time range this {@link android.app.usage.UsageStats} represents,
+     * measured in milliseconds since the epoch.
+     * <p/>
+     * See {@link System#currentTimeMillis()}.
      */
     public long getLastTimeStamp() {
         return mEndTimeStamp;
     }
 
     /**
-     * Get the last time this package was used.
+     * Get the last time this package was used, measured in milliseconds since the epoch.
+     * <p/>
+     * See {@link System#currentTimeMillis()}.
      */
     public long getLastTimeUsed() {
         return mLastTimeUsed;
     }
 
     /**
-     * Get the total time this package spent in the foreground.
+     * Get the total time this package spent in the foreground, measured in milliseconds.
      */
     public long getTotalTimeInForeground() {
         return mTotalTimeInForeground;
diff --git a/core/java/android/app/usage/UsageStatsManager.java b/core/java/android/app/usage/UsageStatsManager.java
index f9b8928..5830fcf 100644
--- a/core/java/android/app/usage/UsageStatsManager.java
+++ b/core/java/android/app/usage/UsageStatsManager.java
@@ -23,6 +23,7 @@ import android.util.ArrayMap;
 
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Provides access to device usage history and statistics. Usage data is aggregated into
@@ -149,7 +150,6 @@ public final class UsageStatsManager {
      * @param endTime The exclusive end of the range of events to include in the results.
      * @return A {@link UsageEvents}.
      */
-    @SuppressWarnings("unchecked")
     public UsageEvents queryEvents(long beginTime, long endTime) {
         try {
             UsageEvents iter = mService.queryEvents(beginTime, endTime,
@@ -170,15 +170,13 @@ public final class UsageStatsManager {
      *
      * @param beginTime The inclusive beginning of the range of stats to include in the results.
      * @param endTime The exclusive end of the range of stats to include in the results.
-     * @return An {@link android.util.ArrayMap} keyed by package name or null if no stats are
+     * @return A {@link java.util.Map} keyed by package name, or null if no stats are
      *         available.
      */
-    public ArrayMap<String, UsageStats> queryAndAggregateUsageStats(long beginTime, long endTime) {
+    public Map<String, UsageStats> queryAndAggregateUsageStats(long beginTime, long endTime) {
         List<UsageStats> stats = queryUsageStats(INTERVAL_BEST, beginTime, endTime);
         if (stats.isEmpty()) {
-            @SuppressWarnings("unchecked")
-            ArrayMap<String, UsageStats> emptyStats = ArrayMap.EMPTY;
-            return emptyStats;
+            return Collections.emptyMap();
         }
 
         ArrayMap<String, UsageStats> aggregatedStats = new ArrayMap<>();
diff --git a/core/java/com/android/internal/app/ResolverActivity.java b/core/java/com/android/internal/app/ResolverActivity.java
index 61b4567..b6e7353 100644
--- a/core/java/com/android/internal/app/ResolverActivity.java
+++ b/core/java/com/android/internal/app/ResolverActivity.java
@@ -23,7 +23,6 @@ import android.app.usage.UsageStatsManager;
 import android.os.AsyncTask;
 import android.provider.Settings;
 import android.text.TextUtils;
-import android.util.ArrayMap;
 import android.util.Slog;
 import android.widget.AbsListView;
 import android.widget.GridView;
@@ -73,6 +72,7 @@ import java.util.Comparator;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Map;
 import java.util.Set;
 
 /**
@@ -100,7 +100,7 @@ public class ResolverActivity extends Activity implements AdapterView.OnItemClic
     private boolean mResolvingHome = false;
 
     private UsageStatsManager mUsm;
-    private ArrayMap<String, UsageStats> mStats;
+    private Map<String, UsageStats> mStats;
     private static final long USAGE_STATS_PERIOD = 1000 * 60 * 60 * 24 * 14;
 
     private boolean mRegistered;
diff --git a/tests/UsageStatsTest/src/com/android/tests/usagestats/UsageStatsActivity.java b/tests/UsageStatsTest/src/com/android/tests/usagestats/UsageStatsActivity.java
index b6591bd..c08c1a3 100644
--- a/tests/UsageStatsTest/src/com/android/tests/usagestats/UsageStatsActivity.java
+++ b/tests/UsageStatsTest/src/com/android/tests/usagestats/UsageStatsActivity.java
@@ -23,7 +23,6 @@ import android.content.Context;
 import android.content.Intent;
 import android.os.Bundle;
 import android.text.format.DateUtils;
-import android.util.ArrayMap;
 import android.view.LayoutInflater;
 import android.view.Menu;
 import android.view.MenuInflater;
@@ -36,6 +35,7 @@ import android.widget.TextView;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Comparator;
+import java.util.Map;
 
 public class UsageStatsActivity extends ListActivity {
     private static final long USAGE_STATS_PERIOD = 1000 * 60 * 60 * 24 * 14;
@@ -84,7 +84,7 @@ public class UsageStatsActivity extends ListActivity {
     private void updateAdapter() {
         long now = System.currentTimeMillis();
         long beginTime = now - USAGE_STATS_PERIOD;
-        ArrayMap<String, UsageStats> stats = mUsageStatsManager.queryAndAggregateUsageStats(
+        Map<String, UsageStats> stats = mUsageStatsManager.queryAndAggregateUsageStats(
                 beginTime, now);
         mAdapter.update(stats);
     }
@@ -92,17 +92,13 @@ public class UsageStatsActivity extends ListActivity {
     private class Adapter extends BaseAdapter {
         private ArrayList<UsageStats> mStats = new ArrayList<>();
 
-        public void update(ArrayMap<String, UsageStats> stats) {
+        public void update(Map<String, UsageStats> stats) {
             mStats.clear();
             if (stats == null) {
                 return;
             }
 
-            final int packageCount = stats.size();
-            for (int i = 0; i < packageCount; i++) {
-                mStats.add(stats.valueAt(i));
-            }
-
+            mStats.addAll(stats.values());
             Collections.sort(mStats, mComparator);
             notifyDataSetChanged();
         }