Source code: jreceiver/common/rpc/Menus.java
1 /* $Header: /cvsroot/jreceiver/jreceiver/src/jreceiver/common/rpc/Menus.java,v 1.7 2002/12/29 00:44:08 reedesau Exp $ */
2
3 package jreceiver.common.rpc;
4
5 import java.util.Vector;
6
7 import jreceiver.common.rec.util.TuneQuery;
8
9 /**
10 * Menu-related queries and updates for a (possibly-remote) JRec server,
11 * returning MenuRecs or String-formatted results.
12 * <p>
13 * <b>TUNE QUERIES</b>
14 * <P>
15 * A 'tune query' is a shorthand means of specifying a filter.
16 * <p>
17 * For example, to obtain a list of albums for an artist:
18 * <pre>
19 * Menus mnu_rpc = RpcFactory.newMenus();
20 *
21 * TuneQuery tq = new TuneQuery();
22 * tq.setArtistName("Pink Floyd");
23 *
24 * Vector albums = mnu_rpc.getAlbumMenuRecs(tq, driver_id, 0, Menu.NO_LIMIT);
25 * Iterator it = albums.iterator();
26 * while (it.hasNext()) {
27 * Menu menu = (Menu)it.next();
28 * System.out.println("album_name=" + menu.getMenuText()
29 * + " tune_count=" + menu.getTuneCount());
30 * }
31 * </pre>
32 *
33 * You can even combine several criteria. For example, query the
34 * titles for a specific album that start with "An":
35 * <pre>
36 * TuneQuery tq = new TuneQuery();
37 * tq.setArtistName("Pink Floyd");
38 * tq.setAlbumName("The Wall");
39 * tq.setTitleName("^An", true); //true==IS_REG_EXP
40 * </pre>
41 * might return:
42 * <p>
43 * Another Brick In The Wall (Part 1)<br>
44 * Another Brick In The Wall (Part 2)<br>
45 * Another Brick In The Wall (Part 3)<br>
46 * Anybody Out There?<br>
47 * <p>
48 * Note that you can specify whether match will be exact (default) or
49 * a regular expression.
50 *
51 * The regular expression queries are a powerful feature that allow
52 * such things as selecting over a large list. The Rio driver does
53 * this to support queries from the remote:
54 *
55 * <pre>
56 * ^[2abc][5jkl][4ghi].*'
57 * </pre>
58 *
59 * <P>...to find all titles where "2", "a", "b" or "c" is the first letter,
60 * etc.
61 *
62 * <P>Note that the regular-expression capabilities may be limited by
63 * the database. See the MySQL documentation of REGEXP.
64 *
65 * <P>Once you have the artists, albums, genres or titles you want to
66 * play, consult the Tunes.getKeysForQuery() method which is quite
67 * similar to the menu interface, but returns tune src_ids.
68 *
69 *
70 * <b>ENCODING</b>
71 *
72 * Obtain a list of artists, albums, genres or tune titles custom formatted
73 * into a large string for use in a menu.
74 * <p>
75 * You must specify a formatting patthen. For example, when using encodeAlbums:
76 * <pre>
77 * String pattern = "{0,number,#}={1},0,0:{2}\r\n";
78 * </pre>
79 * where {0} will be replaced with the index (starting at begin), {1} will be
80 * replaced with the number of tunes for the artist (as stored in the
81 * database) and {2} is the artist name.
82 *
83 * @author Reed Esau
84 * @version $Revision: 1.7 $ $Date: 2002/12/29 00:44:08 $
85 */
86 public interface Menus extends RpcBase {
87
88 public static final String HANDLER_NAME = "Menus";
89
90 public static final String GET_ARTIST_MENU_RECS = "getArtistMenuRecs";
91 public static final String GET_ALBUM_MENU_RECS = "getAlbumMenuRecs";
92 public static final String GET_GENRE_MENU_RECS = "getGenreMenuRecs";
93 public static final String GET_TITLE_MENU_RECS = "getTitleMenuRecs";
94
95 public static final String ENCODE_ARTISTS = "encodeArtists";
96 public static final String ENCODE_ALBUMS = "encodeAlbums";
97 public static final String ENCODE_GENRES = "encodeGenres";
98 public static final String ENCODE_TITLES = "encodeTitles";
99
100 /**
101 * obtain a list of MenuRecs that specify artist names
102 */
103 public Vector getArtistMenuRecs(TuneQuery tune_query, int driver_id,
104 int rec_offset, int rec_count) throws RpcException;
105
106 /**
107 * obtain a list of MenuRecs that specify album/cd names
108 */
109 public Vector getAlbumMenuRecs(TuneQuery tune_query, int driver_id,
110 int rec_offset, int rec_count) throws RpcException;
111
112 /**
113 * obtain a list of MenuRecs that specify genre names
114 */
115 public Vector getGenreMenuRecs(TuneQuery tune_query, int driver_id,
116 int rec_offset, int rec_count) throws RpcException;
117
118 /**
119 * obtain a list of MenuRecs that specify tune titles
120 */
121 public Vector getTitleMenuRecs(TuneQuery tune_query, int driver_id,
122 int rec_offset, int rec_count) throws RpcException;
123
124 /**
125 * obtain a list of artists, custom formatted, for use in a menu.
126 */
127 public String encodeArtists(TuneQuery tune_query, int driver_id,
128 String pattern,
129 int rec_offset, int rec_count) throws RpcException;
130
131 /**
132 * obtain a list of albums, custom formatted, for use in a menu.
133 */
134 public String encodeAlbums(TuneQuery tune_query, int driver_id,
135 String pattern,
136 int rec_offset, int rec_count) throws RpcException;
137
138 /**
139 * obtain a list of genres, custom formatted, for use in a menu.
140 */
141 public String encodeGenres(TuneQuery tune_query, int driver_id,
142 String pattern,
143 int rec_offset, int rec_count) throws RpcException;
144
145 /**
146 * obtain a list of titles, custom formatted, for use in a menu.
147 */
148 public String encodeTitles(TuneQuery tune_query, int driver_id,
149 String pattern,
150 int rec_offset, int rec_count) throws RpcException;
151 }
152
153 /*
154 JRECEIVER MODIFIED BSD LICENSE
155
156 Copyright (c) 2001-2002, Reed Esau (reed.esau@pobox.com) All rights reserved.
157
158 Redistribution and use in source and binary forms, with or without
159 modification, are permitted provided that the following conditions are
160 met:
161
162 Redistributions of source code must retain the above copyright notice,
163 this list of conditions and the following disclaimer.
164
165 Redistributions in binary form must reproduce the above copyright notice,
166 this list of conditions and the following disclaimer in the documentation
167 and/or other materials provided with the distribution.
168
169 Neither the name of the JReceiver Project
170 (http://jreceiver.sourceforge.net) nor the names of its contributors may
171 be used to endorse or promote products derived from this software without
172 specific prior written permission.
173
174 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
175 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
176 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
177 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
178 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
179 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
180 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
181 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
182 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
183 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
184 POSSIBILITY OF SUCH DAMAGE.
185 */
186