1 /***
2 * Ambient - A music player for the Android platform
3 Copyright (C) 2007 Martin Vysny
4
5 This program is free software: you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation, either version 3 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19 package sk.baka.ambient.activity.search;
20
21 import java.util.List;
22
23 import sk.baka.ambient.views.gesturelist.GesturesListView;
24
25 /***
26 * Performs the search.
27 *
28 * @author Martin Vysny
29 */
30 public interface ISearchEngine {
31
32 /***
33 * Returns the type of this engine.
34 *
35 * @return the engine type.
36 */
37 SearchType getType();
38
39 /***
40 * Sets the owner activity and initializes the engine. Executed in handler
41 * thread.
42 *
43 * @param owner
44 * owner view.
45 * @param listViewId
46 * the ID of the list view. Note that the list view is always
47 * configured to layout items using the
48 * <code>playlist_item.xml</code> layout.
49 */
50 void init(final SearchActivity owner, final int listViewId);
51
52 /***
53 * Checks if this engine can perform an offline search. Executed in handler
54 * thread. May be invoked prior any other method.
55 *
56 * @return <code>true</code> if search can be performed offline,
57 * <code>false</code> otherwise.
58 */
59 boolean canSearchOffline();
60
61 /***
62 * Checks if this engine can currently perform the search. Executed in
63 * handler thread.
64 *
65 * @return <code>true</code> if search can be performed, <code>false</code>
66 * otherwise.
67 */
68 boolean canPerformSearch();
69
70 /***
71 * Performs a search for tracks contained words in given query. The function
72 * must return non-<code>null</code> list which will serve as a model for
73 * {@link GesturesListView}. The method always executes in a new thread. The
74 * method should periodically check for {@link Thread#isInterrupted()} and
75 * terminate ASAP when interrupted.
76 *
77 * @param query
78 * the query to search for
79 * @return result list. Not required to be thread-safe. May return
80 * <code>null</code> if interrupted. Given list must contain
81 * thread-safe objects.
82 * @throws Exception
83 * if search failed.
84 */
85 List<? extends Object> performSearch(final String query) throws Exception;
86
87 /***
88 * Updates the list view with given model. This method is run in the
89 * Handler's thread. The engine must register in
90 * {@link GesturesListView#listener} and must be able to correctly display
91 * items returned by the {@link #performSearch(String)} method.
92 *
93 * @param model
94 * the model as returned by {@link #performSearch(String)}.
95 */
96 void update(final List<? extends Object> model);
97
98 /***
99 * Passivates this engine. The engine may for example remove the listener on
100 * {@link GesturesListView} etc. Executed in handler thread.
101 */
102 void passivate();
103 }