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.collection;
20
21 import java.util.Collection;
22 import java.util.List;
23 import java.util.Map;
24
25 import sk.baka.ambient.collection.ampache.AmpacheServer;
26 import sk.baka.ambient.playlist.Random;
27 import android.media.MediaPlayer;
28
29 /***
30 * <p>
31 * A collection strategy. Allows read-only access to underlying storage of
32 * artists, albums, tracks and genres.
33 * </p>
34 * <p>
35 * The implementation must be thread-safe - any method may be called from
36 * multiple threads at once. The methods should periodically check for
37 * interrupted state and throw {@link InterruptedException} (or other kind of
38 * exception) if they are interrupted.
39 * </p>
40 *
41 * @author Martin Vysny
42 */
43 public interface ICollection {
44 /***
45 * Checks if the underlying strategy uses local resources to retrieve
46 * metadata (a DB backend), or it uses remote access to a server (for
47 * example Ampache).
48 *
49 * @return <code>true</code> if the collection queries will tend to be
50 * performed fast, <code>false</code> otherwise.
51 */
52 boolean isLocal();
53
54 /***
55 * Returns short descriptive name of this collection backend.
56 *
57 * @return the name.
58 */
59 String getName();
60
61 /***
62 * Returns all tracks contained in given category.
63 *
64 * @param context
65 * search in context of this item. Must not be <code>null</code>.
66 * @return list of tracks, sorted in no particular order. Must not be
67 * <code>null</code>, may be empty.
68 * @throws CollectionException
69 * thrown when the collection fails to return items.
70 * @throws InterruptedException
71 * when interrupted.
72 */
73 List<TrackMetadataBean> getTracks(final CategoryItem context)
74 throws CollectionException, InterruptedException;
75
76 /***
77 * Returns category list matching given criteria. Returns sorted list,
78 * either by name or by the year.
79 *
80 * @param request
81 * the category to search for. Must not be <code>null</code>.
82 * @param context
83 * search in context of this item. May be <code>null</code> - in
84 * this case all categories are returned.
85 * @param substring
86 * if not <code>null</code> then all category names must contain
87 * this substring.
88 * @param sortByYear
89 * if <code>true</code> then the result category list is sorted
90 * by year, then by name. If <code>false</code> then sorted only
91 * by name. Ignored when the <code>request</code> parameter is
92 * not an album.
93 * @return list of categories. Must not be <code>null</code>, may be empty.
94 * @throws CollectionException
95 * thrown when the collection fails to return items.
96 * @throws InterruptedException
97 * when interrupted.
98 */
99 List<CategoryItem> getCategoryList(final CategoryEnum request,
100 final CategoryItem context, final String substring,
101 final boolean sortByYear) throws CollectionException,
102 InterruptedException;
103
104 /***
105 * Search song which Song Title, Artist Name, Album Name or Genre Name
106 * contains given substring.
107 *
108 * @param substring
109 * the substring to search for.
110 * @return the list of tracks. Must not be <code>null</code>, may be empty.
111 * Sorted in no particular order.
112 * @throws CollectionException
113 * thrown when the collection fails to return items.
114 * @throws InterruptedException
115 * when interrupted.
116 */
117 List<TrackMetadataBean> searchTracks(final String substring)
118 throws CollectionException, InterruptedException;
119
120 /***
121 * Returns statistics for this collection.
122 *
123 * @return the statistics object, must not be <code>null</code>.
124 * @throws CollectionException
125 * thrown when the collection fails to return items.
126 * @throws InterruptedException
127 * when interrupted.
128 */
129 Statistics getStatistics() throws CollectionException, InterruptedException;
130
131 /***
132 * Returns ID returned by this collection in the {@link CategoryItem#id} as
133 * String. This item will only be used to perform searches - you should thus
134 * preserve minimum information from the category item. This functionality
135 * is only used by {@link AmpacheServer}. You do not need to store the
136 * {@link CategoryItem#category} - it will be overwritten.
137 *
138 * @param item
139 * the item to convert
140 * @return string representation of given item.
141 */
142 String serializeItem(final CategoryItem item);
143
144 /***
145 * Deserializes item serialized by {@link #serializeItem(CategoryItem)}.
146 * This item will be used to perform search only. This functionality is only
147 * used by {@link AmpacheServer}. You do not need to store the
148 * {@link CategoryItem#category} - it will be overwritten.
149 *
150 * @param serializedItem
151 * the item to deserialize
152 * @return the ID instance.
153 */
154 CategoryItem deserializeItem(final String serializedItem);
155
156 /***
157 * Returns a new instance of the track provider. May return
158 * <code>null</code> if this collection does not provide this functionality.
159 * It is caller's responsibility to close the provider.
160 *
161 * @param random
162 * initially provide tracks using this random value.
163 * @return new provider instance, may be <code>null</code>.
164 */
165 IDynamicPlaylistTrackProvider newTrackProvider(final Random random);
166
167 /***
168 * Search for tracks using given criteria search.
169 *
170 * @param criteria
171 * the criteria, must not be <code>null</code>. AND operator is
172 * used if multiple criteria are specified. String values are
173 * matched as substrings.
174 * @return tracks that comply given criteria, in no particular order.
175 * @throws CollectionException
176 * thrown when the collection fails to return items.
177 * @throws InterruptedException
178 * when interrupted.
179 */
180 List<TrackMetadataBean> findTracks(final Map<CategoryEnum, String> criteria)
181 throws CollectionException, InterruptedException;
182
183 /***
184 * Serves for optimalization purposes only: checks if this collection can
185 * perform {@link #fixLocations(Collection) obsolete locations fixup} or
186 * not.
187 *
188 * @return <code>true</code> if {@link #fixLocations(Collection)} is
189 * supported, <code>false</code> if the collection cannot fix the
190 * locations, or the fix operation is not applicable to this
191 * collection.
192 */
193 boolean supportsLocationFix();
194
195 /***
196 * <p>
197 * Given locations became invalid and need fixing.
198 * </p>
199 * <p>
200 * {@link MediaPlayer} detected an error while playing first location URL
201 * from given location list. All given locations might thus have become
202 * invalid. The collection is asked to fix these locations: it should
203 * re-connect to the server (if any) and/or perform any required steps. If
204 * any of these locations became completely invalid the method is free to
205 * omit them in the result map. If the collection is unable to fix given
206 * location then just pass input location.
207 * </p>
208 * <p>
209 * Invoked asynchronously. This method will receive only locations provided
210 * earlier by {@link TrackMetadataBean track} lookup methods such as
211 * {@link #findTracks(Map)}.
212 * </p>
213 *
214 * @param locations
215 * the list of (possibly) invalid locations. Never
216 * <code>null</code> nor empty.
217 * @return a map of locations, maps original location to a fixed locations.
218 * Must not be <code>null</code>.
219 * @throws CollectionException
220 * thrown when this collection is unable to fix the locations.
221 * @throws InterruptedException
222 * thrown when interrupted.
223 */
224 Map<String, String> fixLocations(final Collection<String> locations)
225 throws CollectionException, InterruptedException;
226 }