1 /* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.globalsearch; 18 19 import android.content.ComponentName; 20 21 import java.util.concurrent.Callable; 22 23 /** 24 * Defines what is expected of each source or corpus of suggestions in the global 25 * suggestion provider. 26 */ 27 public interface SuggestionSource { 28 29 /** 30 * Gets the name of the activity that this source is for. When a suggestion is 31 * clicked, the resulting intent will be sent to this activity. Also, any icon 32 * resource IDs will be resolved relative to the package that this activity 33 * belongs to. 34 */ getComponentName()35 ComponentName getComponentName(); 36 37 /** 38 * Gets the localized, human-readable label for this source. 39 */ getLabel()40 String getLabel(); 41 42 /** 43 * Gets the icon for this suggestion source as an android.resource: URI. 44 */ getIcon()45 String getIcon(); 46 47 /** 48 * Gets the description to use for this source in system search settings. 49 */ getSettingsDescription()50 String getSettingsDescription(); 51 52 /** 53 * 54 * Note: this does not guarantee that this source will be queried for queries of 55 * this length or longer, only that it will not be queried for anything shorter. 56 * 57 * @return The minimum number of characters needed to trigger this source. 58 */ getQueryThreshold()59 int getQueryThreshold(); 60 61 /** 62 * Indicates whether a source should be invoked for supersets of queries it has returned zero 63 * results for in the past. For example, if a source returned zero results for "bo", it would 64 * be ignored for "bob". 65 * 66 * If set to <code>false</code>, this source will only be ignored for a single session; the next 67 * time the search dialog is brought up, all sources will be queried. 68 * 69 * @return <code>true</code> if this source should be queried after returning no results. 70 */ queryAfterZeroResults()71 boolean queryAfterZeroResults(); 72 73 /** 74 * Gets a {@link Callable} task that will produce a {@link SuggestionResult} for the given 75 * query. 76 * 77 * @param query The user query. 78 * @param maxResults The maximum number of suggestions that the source should return 79 * in {@link SuggestionResult#getSuggestions()}. 80 * If more suggestions are returned, the caller may discard all the returned 81 * suggestions. 82 * @param queryLimit An advisory maximum number that the source should return 83 * in {@link SuggestionResult#getCount()}. 84 * @return A callable that will produce a suggestion result. 85 */ getSuggestionTask(String query, int maxResults, int queryLimit)86 Callable<SuggestionResult> getSuggestionTask(String query, int maxResults, int queryLimit); 87 88 /** 89 * Validates shortcut. The {@link Callable} returns a {@link SuggestionData} with the up to 90 * date information for the shortcut if the shortcut is still valid, or <code>null</code> 91 * otherwise. 92 * 93 * @param shortcut The old shortcut. 94 * @return A callable that will produce the result. 95 */ getShortcutValidationTask(SuggestionData shortcut)96 Callable<SuggestionData> getShortcutValidationTask(SuggestionData shortcut); 97 98 /** 99 * Checks whether this is a web suggestion source. 100 */ isWebSuggestionSource()101 boolean isWebSuggestionSource(); 102 103 } 104