Source code: com/virtuosotechnologies/asaph/standardmodel/StandardModelFactory.java
1 /*
2 ================================================================================
3
4 FILE: StandardModelFactory.java
5
6 PROJECT:
7
8 Asaph
9
10 CONTENTS:
11
12 API for StandardModel
13
14 PROGRAMMERS:
15
16 Daniel Azuma (DA) <dazuma@kagi.com>
17
18 COPYRIGHT:
19
20 Copyright (C) 2003 Daniel Azuma (dazuma@kagi.com)
21
22 This program is free software; you can redistribute it and/or
23 modify it under the terms of the GNU General Public License as
24 published by the Free Software Foundation; either version 2
25 of the License, or (at your option) any later version.
26
27 This program is distributed in the hope that it will be useful,
28 but WITHOUT ANY WARRANTY; without even the implied warranty of
29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30 GNU General Public License for more details.
31
32 You should have received a copy of the GNU General Public
33 License along with this program; if not, write to
34 Free Software Foundation, Inc.
35 59 Temple Place, Suite 330
36 Boston, MA 02111-1307 USA
37
38 ================================================================================
39 */
40
41
42 package com.virtuosotechnologies.asaph.standardmodel;
43
44
45 import java.io.Reader;
46 import java.io.Writer;
47 import java.io.OutputStream;
48 import java.io.IOException;
49 import java.util.Locale;
50 import org.xml.sax.Attributes;
51 import org.xml.sax.ErrorHandler;
52 import org.xml.sax.SAXException;
53
54 import com.virtuosotechnologies.lib.util.StringID;
55 import com.virtuosotechnologies.lib.xml.XMLUnparser;
56
57 import com.virtuosotechnologies.asaph.model.Song;
58 import com.virtuosotechnologies.asaph.model.SongID;
59 import com.virtuosotechnologies.asaph.model.SongDatabase;
60 import com.virtuosotechnologies.asaph.model.SongIDResultSet;
61
62
63 /**
64 * API for StandardModel
65 */
66 public interface StandardModelFactory
67 {
68 /**
69 * Name of this API
70 */
71 public static final String API_NAME = "com.virtuosotechnologies.asaph.standardmodel.StandardModelFactory";
72
73
74 /**
75 * Create a standard SongIDResultSet implementation.
76 *
77 * @param database database that owns the result set
78 * @return an empty SongIDResultSet
79 */
80 public SongIDResultSet createSongIDResultSet(
81 SongDatabase database);
82
83
84 /**
85 * Create a standard Song implementation.
86 *
87 * @param id SongID for the song, or null to create a standalone song
88 * @param locale Locale for the song, or null to use the default locale
89 * @return an empty Song
90 */
91 public Song createSong(
92 SongID id,
93 Locale locale);
94
95
96 /**
97 * Parse a Song from the given XML document.
98 *
99 * @param reader Reader to parse from
100 * @param id SongID for the song, or null to parse a standalone song
101 * @param errorHandler handler for error messages
102 * @return a new Song
103 * @exception IOException fatal i/o error
104 * @exception SAXException fatal parse error
105 */
106 public Song parseSong(
107 Reader reader,
108 SongID id,
109 ErrorHandler errorHandler)
110 throws
111 IOException,
112 SAXException;
113
114
115 /**
116 * Returns true if the given Song is a StandardModel implementation of Song.
117 * This means the song unparse operations provided by this API may be performed.
118 *
119 * @param song Song to test
120 * @return true if the Song is a StandardModel Song.
121 */
122 public boolean isStandardModelSong(
123 Song song);
124
125
126 /**
127 * Unparse the given Song to an OutputStream as a standalone XML file.
128 * The Song must be a StandardModel Song.
129 *
130 * @param song Song to unparse
131 * @param stream OutputStream to write to
132 * @param encodingName character encoding being used
133 * @exception IOException i/o error
134 * @exception IllegalArgumentException the song isn't a StandardModel song
135 */
136 public void unparseSong(
137 Song song,
138 OutputStream stream,
139 String encodingName)
140 throws
141 IOException;
142
143
144 /**
145 * Unparse the given Song to an OutputStream as a standalone XML file.
146 * The Song must be a StandardModel Song.
147 * Does not check to ensure the given writer's encoding matches the encoding string.
148 *
149 * @param song Song to unparse
150 * @param writer Writer to write to
151 * @param encodingName character encoding being used
152 * @exception IOException i/o error
153 * @exception IllegalArgumentException the song isn't a StandardModel song
154 */
155 public void unparseSong(
156 Song song,
157 Writer writer,
158 String encodingName)
159 throws
160 IOException;
161
162
163 /**
164 * Unparse the given Song to an OutputStream as an element within a larger XML document.
165 * The Song must be a StandardModel Song.
166 *
167 * @param song Song to unparse
168 * @param unparser XMLUnparser to use
169 * @exception IOException i/o error
170 * @exception IllegalArgumentException the song isn't a StandardModel song
171 */
172 public void unparseSongElement(
173 Song song,
174 XMLUnparser unparser)
175 throws
176 IOException;
177
178
179 /**
180 * Get the version string for the given Song.
181 * The Song must be a StandardModel Song.
182 *
183 * @param song Song to query
184 * @return version string
185 * @exception IllegalArgumentException the song isn't a StandardModel song
186 */
187 public StringID getSongVersion(
188 Song song);
189
190
191 /**
192 * Set the version string for the given Song.
193 * The Song must be a StandardModel Song.
194 *
195 * @param song Song to query
196 * @param version version string
197 * @exception IllegalArgumentException the song isn't a StandardModel song
198 */
199 public void setSongVersion(
200 Song song,
201 StringID version);
202
203
204 /**
205 * Create a simple SongDatabase implementation.
206 *
207 * @return an empty simple SongDatabase
208 */
209 public SongDatabase createSimpleSongDatabase();
210
211
212 /**
213 * Parse a simple SongDatabase from the given XML document.
214 *
215 * @param reader Reader to parse from
216 * @param errorHandler handler for error messages
217 * @param writable should the database be writable
218 * @return a new simple SongDatabase
219 * @exception IOException fatal i/o error
220 * @exception SAXException fatal parse error
221 */
222 public SongDatabase parseSimpleSongDatabase(
223 Reader reader,
224 ErrorHandler errorHandler,
225 boolean writable)
226 throws
227 IOException,
228 SAXException;
229
230
231 /**
232 * Returns true if the given Song is a simple implementation of SongDatabase.
233 * This means the song database unparse operations provided by this API may be performed.
234 *
235 * @param database SongDatabase to test
236 * @return true if the Song is a simple SongDatabase.
237 */
238 public boolean isSimpleSongDatabase(
239 SongDatabase database);
240
241
242 /**
243 * Unparse the given SongDatabase to an OutputStream as a standalone XML file.
244 * The database must be a simple SongDatabase.
245 *
246 * @param database SongDatabase to unparse
247 * @param stream OutputStream to write to
248 * @param encodingName character encoding being used
249 * @exception IOException i/o error
250 * @exception IllegalArgumentException the song isn't a simple SongDatabase
251 */
252 public void unparseSimpleSongDatabase(
253 SongDatabase database,
254 OutputStream stream,
255 String encodingName)
256 throws
257 IOException;
258
259
260 /**
261 * Unparse the given SongDatabase to an OutputStream as a standalone XML file.
262 * The database must be a simple SongDatabase.
263 * Does not check to ensure the given writer's encoding matches the encoding string.
264 *
265 * @param database SongDatabase to unparse
266 * @param writer Writer to write to
267 * @param encodingName character encoding being used
268 * @exception IOException i/o error
269 * @exception IllegalArgumentException the song isn't a simple SongDatabase
270 */
271 public void unparseSimpleSongDatabase(
272 SongDatabase database,
273 Writer writer,
274 String encodingName)
275 throws
276 IOException;
277 }