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.main.cb;
20
21 import java.util.List;
22
23 import sk.baka.ambient.collection.CollectionException;
24 import sk.baka.ambient.collection.ICollection;
25 import sk.baka.ambient.collection.TrackMetadataBean;
26 import sk.baka.ambient.commons.Interval;
27
28 /***
29 * <p>
30 * Manages current content as shown by the collection.
31 * </p>
32 * <p>
33 * All long-running operations (methods not executed in handler's thread) should
34 * periodically check for interrupted status, throwing
35 * {@link InterruptedException} (or other type of exception) if they are
36 * interrupted.
37 * </p>
38 *
39 * @author Martin Vysny
40 */
41 public interface IContentManager {
42
43 /***
44 * <p>
45 * Initialize this manager and fetch the data. This method will not be
46 * invoked in handler's thread. This is the first method invoked on a new
47 * manager (or managers retrieved by {@link #goBack()} and
48 * {@link #itemActivated(int)} methods).
49 * </p>
50 * <p>
51 * The manager may be initialized multiple times with different values of
52 * the <code>isYear</code>. The manager should simply do nothing if its
53 * previous contents does not change.
54 * </p>
55 *
56 * @param isYear
57 * <code>true</code> if year is displayed, <code>false</code>
58 * otherwise.
59 * @param collection
60 * the collection to poll data from.
61 * @return the manager contains new data and the display component should be
62 * invalidated to reflect this new data.
63 * @throws CollectionException
64 * if the underlying collection throws an exception.
65 * @throws InterruptedException
66 * if interrupted.
67 */
68 boolean initialize(final boolean isYear, final ICollection collection)
69 throws CollectionException, InterruptedException;
70
71 /***
72 * <p>
73 * Returns a content manager which will handle contents after a back
74 * operation.
75 * </p>
76 * <p>
77 * This method is run in handler's thread.
78 * </p>
79 *
80 * @return the manager instance, may be <code>null</code> if the back
81 * operation is not allowed. Returned manager instance is
82 * uninitialized.
83 */
84 IContentManager goBack();
85
86 /***
87 * <p>
88 * User activated given item. Return a new manager which will handle new
89 * contents.
90 * </p>
91 * <p>
92 * This method is run in handler's thread.
93 * </p>
94 *
95 * @param i
96 * the item index.
97 * @return new content manager or <code>null</code> if we cannot move
98 * forward. Returned manager instance is uninitialized.
99 */
100 IContentManager itemActivated(final int i);
101
102 /***
103 * This manager will not be used for a while. It should discard all of its
104 * internal caches.
105 */
106 void uninitialize();
107
108 /***
109 * <p>
110 * Returns string representation of items contained in this manager.
111 * </p>
112 * <p>
113 * This method is run in handler's thread.
114 * </p>
115 *
116 * @return the displayable list, never <code>null</code>, may be empty.
117 */
118 List<String> getDisplayableContent();
119
120 /***
121 * Checks if this manager can provide a list of tracks. This method is run
122 * in handler's thread.
123 *
124 * @return <code>true</code> if the manager is able to provide a list of
125 * tracks.
126 */
127 boolean canReturnTracks();
128
129 /***
130 * Computes a list of tracks. Run only if {@link #canReturnTracks()} returns
131 * <code>true</code>. This method is not run in handler's thread.
132 *
133 * @param selection
134 * the selection
135 * @return list of tracks.
136 * @throws CollectionException
137 * if the underlying collection throws an exception.
138 * @throws InterruptedException
139 * if interrupted.
140 */
141 List<TrackMetadataBean> getTracks(final Interval selection)
142 throws CollectionException, InterruptedException;
143
144 /***
145 * When activating an item, the manager should keep track of this item so
146 * that it can return its index when going back. This method is run in
147 * handler's thread.
148 *
149 * @param contentManager
150 * the other manager on the same level.
151 * @return the item index or -1 if the item could no longer be found.
152 */
153 int getIndexOfPreviouslyActivatedItem(IContentManager contentManager);
154
155 /***
156 * Returns selected item as a displayable string. If no item was selected
157 * yet since the last initialization then return a short descriptive name of
158 * this content manager.
159 *
160 * @return the item name or manager name.
161 */
162 String getSelectedItemName();
163 }