donut snapshot

1 files changed, 100 insertions, 105 deletions

diff --git a/core/java/android/app/SearchManager.java b/core/java/android/app/SearchManager.java
index fd559d6..62faadc 100644
--- a/core/java/android/app/SearchManager.java
+++ b/core/java/android/app/SearchManager.java
@@ -40,7 +40,7 @@ import java.util.List;
  * methods and the the {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH}
  * {@link android.content.Intent Intent}.  This class does provide a basic
  * overview of search services and how to integrate them with your activities.
- * If you do require direct access to the Search Manager, do not instantiate 
+ * If you do require direct access to the SearchManager, do not instantiate 
  * this class directly; instead, retrieve it through
  * {@link android.content.Context#getSystemService
  * context.getSystemService(Context.SEARCH_SERVICE)}.
@@ -49,8 +49,7 @@ import java.util.List;
  * <ol>
  * <li><a href="#DeveloperGuide">Developer Guide</a>
  * <li><a href="#HowSearchIsInvoked">How Search Is Invoked</a>
- * <li><a href="#QuerySearchApplications">Query-Search Applications</a>
- * <li><a href="#FilterSearchApplications">Filter-Search Applications</a>
+ * <li><a href="#ImplementingSearchForYourApp">Implementing Search for Your App</a>
  * <li><a href="#Suggestions">Search Suggestions</a>
  * <li><a href="#ActionKeys">Action Keys</a>
  * <li><a href="#SearchabilityMetadata">Searchability Metadata</a>
@@ -62,37 +61,18 @@ import java.util.List;
  * <h3>Developer Guide</h3>
  * 
  * <p>The ability to search for user, system, or network based data is considered to be
- * a core user-level feature of the android platform.  At any time, the user should be
+ * a core user-level feature of the Android platform.  At any time, the user should be
  * able to use a familiar command, button, or keystroke to invoke search, and the user
- * should be able to search any data which is available to them.  The goal is to make search 
- * appear to the user as a seamless, system-wide feature.
+ * should be able to search any data which is available to them.
  * 
- * <p>In terms of implementation, there are three broad classes of Applications:
- * <ol>
- * <li>Applications that are not inherently searchable</li>
- * <li>Query-Search Applications</li>
- * <li>Filter-Search Applications</li>
- * </ol>
- * <p>These categories, as well as related topics, are discussed in
- * the sections below.
+ * <p>To make search appear to the user as a seamless system-wide feature, the application
+ * framework centrally controls it, offering APIs to individual applications to control how they
+ * are searched. Applications can customize how search is invoked, how the search dialog looks,
+ * and what type of search results are available, including suggestions that are available as the
+ * user types.
  *
- * <p>Even if your application is not <i>searchable</i>, it can still support the invocation of
- * search.  Please review the section <a href="#HowSearchIsInvoked">How Search Is Invoked</a>
- * for more information on how to support this.
- * 
- * <p>Many applications are <i>searchable</i>.  These are 
- * the applications which can convert a query string into a list of results.  
- * Within this subset, applications can be grouped loosely into two families:  
- * <ul><li><i>Query Search</i> applications perform batch-mode searches - each query string is 
- * converted to a list of results.</li>
- * <li><i>Filter Search</i> applications provide live filter-as-you-type searches.</li></ul>
- * <p>Generally speaking, you would use query search for network-based data, and filter 
- * search for local data, but this is not a hard requirement and applications 
- * are free to use the model that fits them best (or invent a new model).
- * <p>It should be clear that the search implementation decouples "search 
- * invocation" from "searchable".  This satisfies the goal of making search appear
- * to be "universal".  The user should be able to launch any search from 
- * almost any context.
+ * <p>Even applications which are not searchable will by default support the invocation of
+ * search to trigger Quick Search Box, the system's 'global search'.
  * 
  * <a name="HowSearchIsInvoked"></a>
  * <h3>How Search Is Invoked</h3>
@@ -100,14 +80,15 @@ import java.util.List;
  * <p>Unless impossible or inapplicable, all applications should support
  * invoking the search UI.  This means that when the user invokes the search command, 
  * a search UI will be presented to them.  The search command is currently defined as a menu
- * item called "Search" (with an alphabetic shortcut key of "S"), or on some devices, a dedicated
+ * item called "Search" (with an alphabetic shortcut key of "S"), or on many devices, a dedicated
  * search button key.
- * <p>If your application is not inherently searchable, you can also allow the search UI
- * to be invoked in a "web search" mode.  If the user enters a search term and clicks the 
- * "Search" button, this will bring the browser to the front and will launch a web-based
+ * <p>If your application is not inherently searchable, the default implementation will cause
+ * the search UI to be invoked in a "global search" mode known as Quick Search Box.  As the user
+ * types, search suggestions from across the device and the web will be surfaced, and if they
+ * click the "Search" button, this will bring the browser to the front and will launch a web-based
  * search.  The user will be able to click the "Back" button and return to your application.
  * <p>In general this is implemented by your activity, or the {@link android.app.Activity Activity}
- * base class, which captures the search command and invokes the Search Manager to 
+ * base class, which captures the search command and invokes the SearchManager to 
  * display and operate the search UI.  You can also cause the search UI to be presented in response
  * to user keystrokes in your activity (for example, to instantly start filter searching while
  * viewing a list and typing any key).
@@ -124,7 +105,7 @@ import java.util.List;
  * button or menu item - and invoking the search UI directly.</li>
  * <li>You can provide a <i>type-to-search</i> feature, in which search is invoked automatically
  * when the user enters any characters.</li>
- * <li>Even if your application is not inherently searchable, you can allow web search, 
+ * <li>Even if your application is not inherently searchable, you can allow global search, 
  * via the search key (or even via a search menu item).
  * <li>You can disable search entirely.  This should only be used in very rare circumstances,
  * as search is a system-wide feature and users will expect it to be available in all contexts.</li>
@@ -148,21 +129,23 @@ import java.util.List;
  * setDefaultKeyMode(DEFAULT_KEYS_SEARCH_LOCAL);   // search within your activity
  * setDefaultKeyMode(DEFAULT_KEYS_SEARCH_GLOBAL);  // search using platform global search</pre>
  * 
- * <p><b>How to enable web-based search.</b>  In addition to searching within your activity or
- * application, you can also use the Search Manager to invoke a platform-global search, typically
- * a web search.  There are two ways to do this:
+ * <p><b>How to enable global search with Quick Search Box.</b>  In addition to searching within
+ * your activity or application, you can also use the Search Manager to invoke a platform-global
+ * search, which uses Quick Search Box to search across the device and the web. There are two ways
+ * to do this:
  * <ul><li>You can simply define "search" within your application or activity to mean global search.
  * This is described in more detail in the 
  * <a href="#SearchabilityMetadata">Searchability Metadata</a> section.  Briefly, you will
  * add a single meta-data entry to your manifest, declaring that the default search
  * for your application is "*".  This indicates to the system that no application-specific
  * search activity is provided, and that it should launch web-based search instead.</li>
- * <li>You can specify this at invocation time via default keys (see above), overriding
- * {@link android.app.Activity#onSearchRequested}, or via a direct call to 
- * {@link android.app.Activity#startSearch}.  This is most useful if you wish to provide local
- * searchability <i>and</i> access to global search.</li></ul> 
+ * <li>Simply do nothing and the default implementation of
+ * {@link android.app.Activity#onSearchRequested} will cause global search to be triggered.
+ * (You can also always trigger search via a direct call to {@link android.app.Activity#startSearch}.
+ * This is most useful if you wish to provide local searchability <i>and</i> access to global
+ * search.)</li></ul> 
  * 
- * <p><b>How to disable search from your activity.</b>  search is a system-wide feature and users
+ * <p><b>How to disable search from your activity.</b> Search is a system-wide feature and users
  * will expect it to be available in all contexts.  If your UI design absolutely precludes
  * launching search, override {@link android.app.Activity#onSearchRequested onSearchRequested}
  * as shown:
@@ -172,7 +155,7 @@ import java.util.List;
  *    return false;
  * }</pre> 
  * 
- * <p><b>Managing focus and knowing if Search is active.</b>  The search UI is not a separate
+ * <p><b>Managing focus and knowing if search is active.</b>  The search UI is not a separate
  * activity, and when the UI is invoked or dismissed, your activity will not typically be paused,
  * resumed, or otherwise notified by the methods defined in 
  * <a href="{@docRoot}guide/topics/fundamentals.html#actlife">Application Fundamentals: 
@@ -194,17 +177,10 @@ import java.util.List;
  * the search UI.  More details on searchable activities and search intents are provided in the
  * sections below.
  *
- * <a name="QuerySearchApplications"></a>
- * <h3>Query-Search Applications</h3>
- * 
- * <p>Query-search applications are those that take a single query (e.g. a search
- * string) and present a set of results that may fit.  Primary examples include
- * web queries, map lookups, or email searches (with the common thread being
- * network query dispatch).  It may also be the case that certain local searches
- * are treated this way.  It's up to the application to decide.
+ * <a name="ImplementingSearchForYourApp"></a>
+ * <h3>Implementing Search for Your App</h3>
  *
- * <p><b>What you need to do:</b>  The following steps are necessary in order to
- * implement query search.
+ * <p>The following steps are necessary in order to implement search.
  * <ul>
  * <li>Implement search invocation as described above.  (Strictly speaking, 
  * these are decoupled, but it would make little sense to be "searchable" but not 
@@ -220,16 +196,16 @@ import java.util.List;
  * {@link #QUERY getStringExtra(SearchManager.QUERY)}.</li>
  * <li>To identify and support your searchable activity, you'll need to 
  * provide an XML file providing searchability configuration parameters, a reference to that 
- * in your searchable activity's <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a>
- * entry, and an intent-filter declaring that you can 
- * receive ACTION_SEARCH intents.  This is described in more detail in the 
- * <a href="#SearchabilityMetadata">Searchability Metadata</a> section.</li>
- * <li>Your <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a> also needs a metadata entry
- * providing a global reference to the searchable activity.  This is the "glue" directing the search
- * UI, when invoked from any of your <i>other</i> activities, to use your application as the
- * default search context.  This is also described in more detail in the 
+ * in your searchable activity's
+ * <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a> entry, and an
+ * intent-filter declaring that you can receive ACTION_SEARCH intents. This is described in more
+ * detail in the <a href="#SearchabilityMetadata">Searchability Metadata</a> section.</li>
+ * <li>Your <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a> also needs a
+ * metadata entry providing a global reference to the searchable activity. This is the "glue"
+ * directing the search UI, when invoked from any of your <i>other</i> activities, to use your
+ * application as the default search context.  This is also described in more detail in the 
  * <a href="#SearchabilityMetadata">Searchability Metadata</a> section.</li> 
- * <li>Finally, you may want to define your search results activity as with the 
+ * <li>Finally, you may want to define your search results activity as single-top with the 
  * {@link android.R.attr#launchMode singleTop} launchMode flag.  This allows the system 
  * to launch searches from/to the same activity without creating a pile of them on the 
  * activity stack.  If you do this, be sure to also override 
@@ -255,25 +231,10 @@ import java.util.List;
  *     doSearchWithQuery(queryString);
  * }</pre>
  * 
- * <a name="FilterSearchApplications"></a>
- * <h3>Filter-Search Applications</h3>
- * 
- * <p>Filter-search applications are those that use live text entry (e.g. keystrokes)) to
- * display and continuously update a list of results.  Primary examples include applications
- * that use locally-stored data.
- * 
- * <p>Filter search is not directly supported by the Search Manager.  Most filter search
- * implementations will use variants of {@link android.widget.Filterable}, such as a 
- * {@link android.widget.ListView} bound to a {@link android.widget.SimpleCursorAdapter}.  However,
- * you may find it useful to mix them together, by declaring your filtered view searchable.  With
- * this configuration, you can still present the standard search dialog in all activities
- * within your application, but transition to a filtered search when you enter the activity
- * and display the results.
- * 
  * <a name="Suggestions"></a>
  * <h3>Search Suggestions</h3>
  * 
- * <p>A powerful feature of the Search Manager is the ability of any application to easily provide
+ * <p>A powerful feature of the search system is the ability of any application to easily provide
  * live "suggestions" in order to prompt the user.  Each application implements suggestions in a 
  * different, unique, and appropriate way.  Suggestions be drawn from many sources, including but 
  * not limited to:
@@ -285,12 +246,6 @@ import java.util.List;
  * <li>Summaries of possible results</li>
  * </ul>
  * 
- * <p>Another feature of suggestions is that they can expose queries or results before the user
- * ever visits the application.  This reduces the amount of context switching required, and helps
- * the user access their data quickly and with less context shifting.  In order to provide this
- * capability, suggestions are accessed via a 
- * {@link android.content.ContentProvider Content Provider}.  
- * 
  * <p>The primary form of suggestions is known as <i>queried suggestions</i> and is based on query
  * text that the user has already typed.  This would generally be based on partial matches in
  * the available data.  In certain situations - for example, when no query text has been typed yet -
@@ -299,7 +254,8 @@ import java.util.List;
  * available, they should be weighted based on other factors - for example, most recent queries 
  * or most recent results.
  * 
- * <p><b>Overview of how suggestions are provided.</b>  When the search manager identifies a 
+ * <p><b>Overview of how suggestions are provided.</b>  Suggestions are accessed via a
+ * {@link android.content.ContentProvider Content Provider}. When the search manager identifies a 
  * particular activity as searchable, it will check for certain metadata which indicates that
  * there is also a source of suggestions.  If suggestions are provided, the following steps are
  * taken.
@@ -405,7 +361,26 @@ import java.util.List;
  * forget to decode it.  (See {@link android.net.Uri#getPathSegments} and
  * {@link android.net.Uri#getLastPathSegment} for helpful utilities you can use here.)</li>
  * </ul>
- * 
+ *
+ * <p><b>Providing access to Content Providers that require permissions.</b>  If your content
+ * provider declares an android:readPermission in your application's manifest, you must provide
+ * access to the search infrastructure to the search suggestion path by including a path-permission
+ * that grants android:readPermission access to "android.permission.GLOBAL_SEARCH".  Granting access
+ * explicitly to the search infrastructure ensures it will be able to access the search suggestions
+ * without needing to know ahead of time any other details of the permissions protecting your
+ * provider.  Content providers that require no permissions are already available to the search
+ * infrastructure.  Here is an example of a provider that protects access to it with permissions,
+ * and provides read access to the search infrastructure to the path that it expects to receive the
+ * suggestion query on:
+ * <pre class="prettyprint">
+ * &lt;provider android:name="MyProvider" android:authorities="myprovider"
+ *        android:readPermission="android.permission.READ_MY_DATA"
+ *        android:writePermission="android.permission.WRITE_MY_DATA"&gt;
+ *    &lt;path-permission android:path="/search_suggest_query"
+ *            android:readPermission="android.permission.GLOBAL_SEARCH" /&gt;
+ * &lt;/provider&gt;
+ * </pre>
+ *
  * <p><b>Handling empty queries.</b>  Your application should handle the "empty query"
  * (no user text entered) case properly, and generate useful suggestions in this case.  There are a
  * number of ways to do this;  Two are outlined here:
@@ -413,7 +388,7 @@ import java.util.List;
  * unfiltered.  (example: People)</li>
  * <li>For a query search, you could simply present the most recent queries.  This allows the user
  * to quickly repeat a recent search.</li></ul>
- * 
+ *
  * <p><b>The Format of Individual Suggestions.</b>  Your suggestions are communicated back to the
  * Search Manager by way of a {@link android.database.Cursor Cursor}.  The Search Manager will
  * usually pass a null Projection, which means that your provider can simply return all appropriate
@@ -489,13 +464,22 @@ import java.util.List;
  *         <td align="center">No</td>
  *     </tr>
  *     
+ *     <tr><th>{@link #SUGGEST_COLUMN_INTENT_EXTRA_DATA}</th>
+ *         <td>If this column exists <i>and</i> this element exists at a given row, this is the
+ *             data that will be used when forming the suggestion's intent.  If not provided,
+ *             the Intent's extra data field will be null.  This column allows suggestions to
+ *             provide additional arbitrary data which will be included as an extra under the
+ *             key {@link #EXTRA_DATA_KEY}.</td>
+ *         <td align="center">No.</td>
+ *     </tr>
+ *
  *     <tr><th>{@link #SUGGEST_COLUMN_QUERY}</th>
  *         <td>If this column exists <i>and</i> this element exists at the given row, this is the 
  *             data that will be used when forming the suggestion's query.</td>
  *         <td align="center">Required if suggestion's action is 
  *             {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH}, optional otherwise.</td>
  *     </tr>
- *     
+ *
  *     <tr><th><i>Other Columns</i></th>
  *         <td>Finally, if you have defined any <a href="#ActionKeys">Action Keys</a> and you wish 
  *             for them to have suggestion-specific definitions, you'll need to define one 
@@ -704,7 +688,7 @@ import java.util.List;
  *             entered.</td>
  *         <td align="center">No</td>
  *     </tr>
- *     
+ *
  *     <tr><th>android:searchButtonText</th>
  *         <td>If provided, this text will replace the default text in the "Search" button.</td>
  *         <td align="center">No</td>
@@ -884,7 +868,7 @@ import java.util.List;
  *     
  *     </tbody>
  * </table>
- * 
+ *
  * <p><b>Additional metadata for search action keys.</b>  For each action key that you would like to
  * define, you'll need to add an additional element defining that key, and using the attributes
  * discussed in <a href="#ActionKeys">Action Keys</a>.  A simple example is shown here:
@@ -1262,12 +1246,16 @@ public class SearchManager
      * result indicates the shortcut refers to a no longer valid sugggestion.
      *
      * @see #SUGGEST_COLUMN_SHORTCUT_ID
+     *
+     * @hide pending enabling of global search for third parties
      */
     public final static String SUGGEST_URI_PATH_SHORTCUT = "search_suggest_shortcut";
     
     /**
      * MIME type for shortcut validation.  You'll use this in your suggestions content provider
      * in the getType() function.
+     *
+     * @hide pending enabling of global search for third parties
      */
     public final static String SHORTCUT_MIME_TYPE = 
             "vnd.android.cursor.item/vnd.android.search.suggest";
@@ -1280,7 +1268,7 @@ public class SearchManager
      * In addition to the columns below, the suggestion columns are used to pass along the full
      * suggestion so it can be shortcutted.
      *
-     * @hide
+     * @hide an implementation detail not part of the public api
      */
     public final static String SEARCH_CLICK_REPORT_AUTHORITY =
             "com.android.globalsearch.stats";
@@ -1288,21 +1276,21 @@ public class SearchManager
     /**
      * The path the write goes to.
      *
-     * @hide
+     * @hide an implementation detail not part of the public api
      */
     public final static String SEARCH_CLICK_REPORT_URI_PATH = "click";
 
     /**
      * The column storing the query for the click.
      *
-     * @hide
+     * @hide an implementation detail not part of the public api
      */
     public final static String SEARCH_CLICK_REPORT_COLUMN_QUERY = "query";
 
     /**
      * The column storing the component name of the application that was pivoted into.
      *
-     * @hide
+     * @hide an implementation detail not part of the public api
      */
     public final static String SEARCH_CLICK_REPORT_COLUMN_COMPONENT = "component";
 
@@ -1387,7 +1375,7 @@ public class SearchManager
      *  {@link #COMPONENT_NAME_KEY}. For use by the global search system only - if other providers
      *  attempt to use this column, the value will be overwritten by global search.
      *
-     * @hide
+     * @hide an implementation detail not part of the public api
      */
     public final static String SUGGEST_COLUMN_INTENT_COMPONENT_NAME = "suggest_intent_component";
     /**
@@ -1407,11 +1395,13 @@ public class SearchManager
 
     /**
      * Column name for suggestions cursor. <i>Optional.</i>  This column is used to indicate whether
-     * a search suggestion should be stored as a shortcut, and whether it should be validated.  If
+     * a search suggestion should be stored as a shortcut, and whether it should be refreshed.  If
      * missing, the result will be stored as a shortcut and never validated.  If set to
      * {@link #SUGGEST_NEVER_MAKE_SHORTCUT}, the result will not be stored as a shortcut.
-     * Otherwise, the shortcut id will be used to check back for validation via
+     * Otherwise, the shortcut id will be used to check back for an up to date suggestion using
      * {@link #SUGGEST_URI_PATH_SHORTCUT}.
+     *
+     * @hide pending reenabling of global search for third parties
      */
     public final static String SUGGEST_COLUMN_SHORTCUT_ID = "suggest_shortcut_id";
 
@@ -1420,7 +1410,7 @@ public class SearchManager
      * cursor item's background color if it needs a non-default background color. A non-zero value
      * indicates a valid background color to override the default.
      *
-     * @hide For internal use, not part of the public API.
+     * @hide an implementation detail not part of the public api
      */
     public final static String SUGGEST_COLUMN_BACKGROUND_COLOR = "suggest_background_color";
     
@@ -1428,6 +1418,8 @@ public class SearchManager
      * Column name for suggestions cursor. <i>Optional.</i> This column is used to specify
      * that a spinner should be shown in lieu of an icon2 while the shortcut of this suggestion
      * is being refreshed.
+     *
+     * @hide pending reenabling of global search for third parties
      */
     public final static String SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING =
             "suggest_spinner_while_refreshing";
@@ -1435,6 +1427,8 @@ public class SearchManager
     /**
      * Column value for suggestion column {@link #SUGGEST_COLUMN_SHORTCUT_ID} when a suggestion
      * should not be stored as a shortcut in global search.
+     *
+     * @hide pending reenabling of global search for third parties
      */
     public final static String SUGGEST_NEVER_MAKE_SHORTCUT = "_-1";
 
@@ -1481,6 +1475,8 @@ public class SearchManager
      * Intent action for starting a web search provider's settings activity.
      * Web search providers should handle this intent if they have provider-specific
      * settings to implement.
+     *
+     * @hide implementation detail only relevent to web search providers
      */
     public final static String INTENT_ACTION_WEB_SEARCH_SETTINGS
             = "android.search.action.WEB_SEARCH_SETTINGS";
@@ -1495,8 +1491,7 @@ public class SearchManager
     
     /**
      * Intent action broadcasted to inform that the search settings have changed in some way.
-     * Either searchables have been enabled or disabled, or a different web search provider
-     * has been chosen.
+     * Either searchables have been enabled or disabled.
      */
     public final static String INTENT_ACTION_SEARCH_SETTINGS_CHANGED
             = "android.search.action.SETTINGS_CHANGED";
@@ -1505,7 +1500,7 @@ public class SearchManager
      * If a suggestion has this value in {@link #SUGGEST_COLUMN_INTENT_ACTION},
      * the search dialog will take no action.
      *
-     * @hide
+     * @hide an implentation detail not part of the public api
      */
     public final static String INTENT_ACTION_NONE = "android.search.action.ZILCH";
     
@@ -1577,7 +1572,7 @@ public class SearchManager
      * no extra data is required.
      * @param globalSearch If false, this will only launch the search that has been specifically
      * defined by the application (which is usually defined as a local search).  If no default 
-     * search is defined in the current application or activity, no search will be launched.
+     * search is defined in the current application or activity, global search will be launched.
      * If true, this will always launch a platform-global (e.g. web-based) search instead.
      * 
      * @see android.app.Activity#onSearchRequested