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. Not required to be thread-safe.
68 * Sorted in no particular order.
69 * @throws CollectionException
70 * thrown when the collection fails to return items.
71 * @throws InterruptedException
72 * when interrupted.
73 */
74 List<TrackMetadataBean> getTracks(final CategoryItem context)
75 throws CollectionException, InterruptedException;
76
77 /***
78 * Returns category list matching given criteria. Returns sorted list,
79 * either by name or by the year.
80 *
81 * @param request
82 * the category to search for. Must not be <code>null</code>.
83 * @param context
84 * search in context of this item. May be <code>null</code> - in
85 * this case all categories are returned.
86 * @param substring
87 * if not <code>null</code> then all category names must contain
88 * this substring.
89 * @param sortByYear
90 * if <code>true</code> then the result category list is sorted
91 * by year, then by {@link CategoryItem#sortKey}. If
92 * <code>false</code> then sorted only by
93 * {@link CategoryItem#sortKey}. Ignored when the
94 * <code>request</code> parameter is not an album.
95 * @return list of categories. Must not be <code>null</code>, may be empty.
96 * Not required to be thread-safe. Sorted depending on the value of
97 * the <code>sortByYear</code> parameter.
98 * @throws CollectionException
99 * thrown when the collection fails to return items.
100 * @throws InterruptedException
101 * when interrupted.
102 */
103 List<CategoryItem> getCategoryList(final CategoryEnum request,
104 final CategoryItem context, final String substring,
105 final boolean sortByYear) throws CollectionException,
106 InterruptedException;
107
108 /***
109 * A simpler version of {@link #findTracks(Map)}. Search song which Song
110 * Title, Artist Name, Album Name or Genre Name contains given substring.
111 *
112 * @param substring
113 * the substring to search for.
114 * @return the list of tracks. Must not be <code>null</code>, may be empty.
115 * Sorted in no particular order. Not required to be thread-safe.
116 * @throws CollectionException
117 * thrown when the collection fails to return items.
118 * @throws InterruptedException
119 * when interrupted.
120 */
121 List<TrackMetadataBean> findTracks(final String substring)
122 throws CollectionException, InterruptedException;
123
124 /***
125 * Returns statistics for this collection.
126 *
127 * @return the statistics object, must not be <code>null</code>.
128 * @throws CollectionException
129 * thrown when the collection fails to return items.
130 * @throws InterruptedException
131 * when interrupted.
132 */
133 Statistics getStatistics() throws CollectionException, InterruptedException;
134
135 /***
136 * Returns ID returned by this collection in the {@link CategoryItem#id} as
137 * String. This item will only be used to perform searches - you should thus
138 * preserve minimum information from the category item. This functionality
139 * is only used by {@link AmpacheServer}. You do not need to store the
140 * {@link CategoryItem#category} - it will be overwritten.
141 *
142 * @param item
143 * the item to convert
144 * @return string representation of given item.
145 */
146 String serializeItem(final CategoryItem item);
147
148 /***
149 * Deserializes item serialized by {@link #serializeItem(CategoryItem)}.
150 * This item will be used to perform search only. This functionality is only
151 * used by {@link AmpacheServer}. You do not need to store the
152 * {@link CategoryItem#category} - it will be overwritten.
153 *
154 * @param serializedItem
155 * the item to deserialize
156 * @return the ID instance.
157 */
158 CategoryItem deserializeItem(final String serializedItem);
159
160 /***
161 * Returns a new instance of the track provider. May return
162 * <code>null</code> if this collection does not provide this functionality.
163 * It is caller's responsibility to close the provider.
164 *
165 * @param random
166 * initially provide tracks using this random value.
167 * @return new provider instance, may be <code>null</code>.
168 */
169 IDynamicPlaylistTrackProvider newTrackProvider(final Random random);
170
171 /***
172 * Search for tracks using given criteria search.
173 *
174 * @param criteria
175 * the criteria, must not be <code>null</code>. AND operator is
176 * used if multiple criteria are specified. String values are
177 * matched as substrings.
178 * @return tracks that comply given criteria, in no particular order. Not
179 * required to be thread-safe.
180 * @throws CollectionException
181 * thrown when the collection fails to return items.
182 * @throws InterruptedException
183 * when interrupted.
184 */
185 List<TrackMetadataBean> findTracks(final Map<CategoryEnum, String> criteria)
186 throws CollectionException, InterruptedException;
187
188 /***
189 * Serves for optimalization purposes only: checks if this collection can
190 * perform {@link #fixLocations(Collection) obsolete locations fixup} or
191 * not.
192 *
193 * @return <code>true</code> if {@link #fixLocations(Collection)} is
194 * supported, <code>false</code> if the collection cannot fix the
195 * locations, or the fix operation is not applicable to this
196 * collection.
197 */
198 boolean supportsLocationFix();
199
200 /***
201 * <p>
202 * Given locations became invalid and need fixing.
203 * </p>
204 * <p>
205 * {@link MediaPlayer} detected an error while playing first location URL
206 * from given location list. All given locations might thus have become
207 * invalid. The collection is asked to fix these locations: it should
208 * re-connect to the server (if any) and/or perform any required steps. If
209 * any of these locations became completely invalid the method is free to
210 * omit them in the result map. If the collection is unable to fix given
211 * location then just pass input location.
212 * </p>
213 * <p>
214 * Invoked asynchronously. This method will receive only locations provided
215 * earlier by {@link TrackMetadataBean track} lookup methods such as
216 * {@link #findTracks(Map)}.
217 * </p>
218 *
219 * @param locations
220 * the list of (possibly) invalid locations. Never
221 * <code>null</code> nor empty.
222 * @return a map of locations, maps original location to a fixed locations.
223 * Must not be <code>null</code>. Not required to be thread-safe.
224 * @throws CollectionException
225 * thrown when this collection is unable to fix the locations.
226 * @throws InterruptedException
227 * thrown when interrupted.
228 */
229 Map<String, String> fixLocations(final Collection<String> locations)
230 throws CollectionException, InterruptedException;
231 }