package android.content;
import android.app.SearchManager;
import android.database.Cursor;
import android.database.sqlite.SQLiteDatabase;
import android.database.sqlite.SQLiteOpenHelper;
import android.net.Uri;
import android.text.TextUtils;
import android.util.Log;
/**
* This superclass can be used to create a simple search suggestions provider for your application.
* It creates suggestions (as the user types) based on recent queries and/or recent views.
*
* <p>In order to use this class, you must do the following.
*
* <ul>
* <li>Implement and test query search, as described in {@link android.app.SearchManager}. (This
* provider will send any suggested queries via the standard
* {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent, which you'll already
* support once you have implemented and tested basic searchability.)</li>
* <li>Create a Content Provider within your application by extending
* {@link android.content.SearchRecentSuggestionsProvider}. The class you create will be
* very simple - typically, it will have only a constructor. But the constructor has a very
* important responsibility: When it calls {@link #setupSuggestions(String, int)}, it
* <i>configures</i> the provider to match the requirements of your searchable activity.</li>
* <li>Create a manifest entry describing your provider. Typically this would be as simple
* as adding the following lines:
* <pre class="prettyprint">
* <!-- Content provider for search suggestions -->
* <provider android:name="YourSuggestionProviderClass"
* android:authorities="your.suggestion.authority" /></pre>
* </li>
* <li>Please note that you <i>do not</i> instantiate this content provider directly from within
* your code. This is done automatically by the system Content Resolver, when the search dialog
* looks for suggestions.</li>
* <li>In order for the Content Resolver to do this, you must update your searchable activity's
* XML configuration file with information about your content provider. The following additions
* are usually sufficient:
* <pre class="prettyprint">
* android:searchSuggestAuthority="your.suggestion.authority"
* android:searchSuggestSelection=" ? "</pre>
* </li>
* <li>In your searchable activities, capture any user-generated queries and record them
* for future searches by calling {@link android.provider.SearchRecentSuggestions#saveRecentQuery
* SearchRecentSuggestions.saveRecentQuery()}.</li>
* </ul>
*
* @see android.provider.SearchRecentSuggestions
*/
public class SearchRecentSuggestionsProvider extends ContentProvider {
// debugging support
private static final String TAG = "SuggestionsProvider";
// client-provided configuration values
private String mAuthority;
private int mMode;
private boolean mTwoLineDisplay;
// general database configuration and tables
private SQLiteOpenHelper mOpenHelper;
private static final String sDatabaseName = "suggestions.db";
private static final String sSuggestions = "suggestions";
private static final String ORDER_BY = "date DESC";
private static final String NULL_COLUMN = "query";
// Table of database versions. Don't forget to update!
// NOTE: These version values are shifted left 8 bits (x 256) in order to create space for
// a small set of mode bitflags in the version int.
//
// 1 original implementation with queries, and 1 or 2 display columns
// 1->2 added UNIQUE constraint to display1 column
private static final int DATABASE_VERSION = 2 * 256;
/**
* This mode bit configures the database to record recent queries. <i>required</i>
*
* @see #setupSuggestions(String, int)
*/
public static final int DATABASE_MODE_QUERIES = 1;
/**
* This mode bit configures the database to include a 2nd annotation line with each entry.
* <i>optional</i>
*
* @see #setupSuggestions(String, int)
*/
public static final int DATABASE_MODE_2LINES = 2;
// Uri and query support
private static final int URI_MATCH_SUGGEST = 1;
private Uri mSuggestionsUri;
private UriMatcher mUriMatcher;
private String mSuggestSuggestionClause;
private String[] mSuggestionProjection;
/**
* Builds the database. This version has extra support for using the version field
* as a mode flags field, and configures the database columns depending on the mode bits
* (features) requested by the extending class.
*
* @hide
*/
private static class DatabaseHelper extends SQLiteOpenHelper {
private int mNewVersion;
public DatabaseHelper(Context context, int newVersion) {
super(context, sDatabaseName, null, newVersion);
mNewVersion = newVersion;
}
@Override
public void onCreate(SQLiteDatabase db) {
StringBuilder builder = new StringBuilder();
builder.append("CREATE TABLE suggestions (" +
"_id INTEGER PRIMARY KEY" +
",display1 TEXT UNIQUE ON CONFLICT REPLACE");
if (0 != (mNewVersion & DATABASE_MODE_2LINES)) {
builder.append(",display2 TEXT");
}
builder.append(",query TEXT" +
",date LONG" +
");");
db.execSQL(builder.toString());
}
@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
Log.w(TAG, "Upgrading database from version " + oldVersion + " to "
+ newVersion + ", which will destroy all old data");
db.execSQL("DROP TABLE IF EXISTS suggestions");
onCreate(db);
}
}
/**
* In order to use this class, you must extend it, and call this setup function from your
* constructor. In your application or activities, you must provide the same values when
* you create the {@link android.provider.SearchRecentSuggestions} helper.
*
* @param authority This must match the authority that you've declared in your manifest.
* @param mode You can use mode flags here to determine certain functional aspects of your
* database. Note, this value should not change from run to run, because when it does change,
* your suggestions database may be wiped.
*
* @see #DATABASE_MODE_QUERIES
* @see #DATABASE_MODE_2LINES
*/
protected void setupSuggestions(String authority, int mode) {
if (TextUtils.isEmpty(authority) ||
((mode & DATABASE_MODE_QUERIES) == 0)) {
throw new IllegalArgumentException();
}
// unpack mode flags
mTwoLineDisplay = (0 != (mode & DATABASE_MODE_2LINES));
// saved values
mAuthority = new String(authority);
mMode = mode;
// derived values
mSuggestionsUri = Uri.parse("content://" + mAuthority + "/suggestions");
mUriMatcher = new UriMatcher(UriMatcher.NO_MATCH);
mUriMatcher.addURI(mAuthority, SearchManager.SUGGEST_URI_PATH_QUERY, URI_MATCH_SUGGEST);
if (mTwoLineDisplay) {
mSuggestSuggestionClause = "display1 LIKE ? OR display2 LIKE ?";
mSuggestionProjection = new String [] {
"0 AS " + SearchManager.SUGGEST_COLUMN_FORMAT,
"display1 AS " + SearchManager.SUGGEST_COLUMN_TEXT_1,
"display2 AS " + SearchManager.SUGGEST_COLUMN_TEXT_2,
"query AS " + SearchManager.SUGGEST_COLUMN_QUERY,
"_id"
};
} else {
mSuggestSuggestionClause = "display1 LIKE ?";
mSuggestionProjection = new String [] {
"0 AS " + SearchManager.SUGGEST_COLUMN_FORMAT,
"display1 AS " + SearchManager.SUGGEST_COLUMN_TEXT
