Source code: com/virtuosotechnologies/asaph/model/Song.java
1 /*
2 ================================================================================
3
4 FILE: Song.java
5
6 PROJECT:
7
8 Asaph
9
10 CONTENTS:
11
12 Song interface in an Asaph model
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.model;
43
44 import java.util.Locale;
45 import javax.swing.event.UndoableEditListener;
46
47 import com.virtuosotechnologies.asaph.model.notation.Note;
48
49
50 /**
51 * This is the primary interface to a Song. Songs are obtained from a
52 * SongDatabase. However, Song objects are always "checked-out" copies of
53 * the actual Song data. This lets clients manipulate the Song without
54 * worry about concurrent access. To commit changes, use the commit method
55 * of SongDatabase.
56 */
57 public interface Song
58 {
59 //-------------------------------------------------------------------------
60 // Common field names
61 //-------------------------------------------------------------------------
62
63 /**
64 * Name of main title field. Value is a StringField.
65 */
66 public static final String MAINTITLE_FIELD = "maintitle";
67
68 /**
69 * Name of comment field. Value is a StringField.
70 */
71 public static final String COMMENT_FIELD = "comment";
72
73 /**
74 * Name of alternate titles field. Value is a StringListField.
75 */
76 public static final String ALTERNATETITLELIST_FIELD = "alternatetitlelist";
77
78 /**
79 * Name of author field. Value is a StringField.
80 */
81 public static final String AUTHOR_FIELD = "author";
82
83 /**
84 * Name of copyright field. Value is a StringField.
85 */
86 public static final String COPYRIGHT_FIELD = "copyright";
87
88 /**
89 * Name of keywords field. Value is a StringListField.
90 */
91 public static final String KEYWORDLIST_FIELD = "keywordlist";
92
93 /**
94 * Name of notes field. Value is a StringListField.
95 */
96 public static final String NOTESLIST_FIELD = "noteslist";
97
98
99 //-------------------------------------------------------------------------
100 // Accessor methods
101 //-------------------------------------------------------------------------
102
103 /**
104 * Get the id used to check out the song from its database. Returns null if
105 * this song is not associated with a database.
106 *
107 * @return song id
108 */
109 public SongID getSongID();
110
111
112 /**
113 * Get the locale of the song.
114 *
115 * @return Locale
116 */
117 public Locale getLocale();
118
119
120 /**
121 * Get the number of ChordSets.
122 *
123 * @return number of ChordSets
124 */
125 public int getChordSetCount();
126
127
128 /**
129 * Get the nth ChordSet
130 *
131 * @param n index
132 * @return ChordSet
133 */
134 public ChordSet getNthChordSet(
135 int n);
136
137
138 /**
139 * Get the next chord set following reference.
140 * If reference is null, returns the first chord set.
141 * If reference is the last chord set, returns null;
142 *
143 * @param reference reference ChordSet
144 * @return next chord set
145 * @exception IllegalArgumentException reference is not a member
146 */
147 public ChordSet getNextChordSet(
148 ChordSet reference);
149
150
151 /**
152 * Get the previous chord set preceding reference.
153 * If reference is null, returns the last chord set.
154 * If reference is the first chord set, returns null;
155 *
156 * @param reference reference ChordSet
157 * @return previous chord set
158 * @exception IllegalArgumentException reference is not a member
159 */
160 public ChordSet getPreviousChordSet(
161 ChordSet reference);
162
163
164 /**
165 * Get default chord set. Returns null if there is no default.
166 *
167 * @return default ChordSet
168 */
169 public ChordSet getDefaultChordSet();
170
171
172 /**
173 * Get a ChordSet given a serializable ID. Returns null if there
174 * is no ChordSet with the given ID.
175 *
176 * @param serializableID serializable ID string
177 * @return the ChordSet with the given ID
178 */
179 public ChordSet getChordSetForSerializableID(
180 String serializableID);
181
182
183 /**
184 * Get the number of Variations.
185 *
186 * @return number of Variations
187 */
188 public int getVariationCount();
189
190
191 /**
192 * Get the nth Variation
193 *
194 * @param n index
195 * @return Variation
196 */
197 public Variation getNthVariation(
198 int n);
199
200
201 /**
202 * Get the next variation following reference.
203 * If reference is null, returns the first variation.
204 * If reference is the last variation, returns null;
205 *
206 * @param reference reference Variation
207 * @return next variation
208 * @exception IllegalArgumentException reference is not a member
209 */
210 public Variation getNextVariation(
211 Variation reference);
212
213
214 /**
215 * Get the previous variation preceding reference.
216 * If reference is null, returns the last variation.
217 * If reference is the first variation, returns null;
218 *
219 * @param reference reference Variation
220 * @return previous variation
221 * @exception IllegalArgumentException reference is not a member
222 */
223 public Variation getPreviousVariation(
224 Variation reference);
225
226
227 /**
228 * Get a Variation given a serializable ID. Returns null if there
229 * is no Variation with the given ID.
230 *
231 * @param serializableID serializable ID string
232 * @return the Variation with the given ID
233 */
234 public Variation getVariationForSerializableID(
235 String serializableID);
236
237
238 /**
239 * Get the total number of SongBlocks in the song. This list may not correspond
240 * to any particular variation of the song.
241 *
242 * @return number of SongBlocks
243 */
244 public int getBlockCount();
245
246
247 /**
248 * Get the nth SongBlock
249 *
250 * @param n index
251 * @return SongBlock
252 */
253 public SongBlock getNthBlock(
254 int n);
255
256
257 /**
258 * Get the next block following reference.
259 * If reference is null, returns the first block.
260 * If reference is the last block, returns null;
261 *
262 * @param reference reference SongBlock
263 * @return next block
264 * @exception IllegalArgumentException reference is not a member
265 */
266 public SongBlock getNextBlock(
267 SongBlock reference);
268
269
270 /**
271 * Get the previous block preceding reference.
272 * If reference is null, returns the last block.
273 * If reference is the first block, returns null;
274 *
275 * @param reference reference SongBlock
276 * @return previous block
277 * @exception IllegalArgumentException reference is not a member
278 */
279 public SongBlock getPreviousBlock(
280 SongBlock reference);
281
282
283 /**
284 * Get the number of SongBlocks present for the given variation. Pass null
285 * to specify the default variation.
286 *
287 * @param variation Variation to query, or null for the default variation
288 * @return number of SongBlocks
289 * @exception IllegalArgumentException variation is not a member
290 */
291 public int getBlockCount(
292 Variation variation);
293
294
295 /**
296 * Get the nth SongBlock in the given variation. Pass null to specify the
297 * default variation
298 *
299 * @param n index
300 * @param variation Variation to query, or null for the default variation
301 * @return SongBlock
302 */
303 public SongBlock getNthBlock(
304 int n,
305 Variation variation);
306
307
308 /**
309 * Get the next block following reference, in the given variation.
310 * If reference is null, returns the first block.
311 * If reference is the last block, returns null;
312 * It is legal for reference to not be a member of the given variation. In such
313 * a case, the method will return the next block that is part of this variation.
314 *
315 * @param reference reference SongBlock
316 * @param variation Variation to query, or null for the default variation
317 * @return next block
318 * @exception IllegalArgumentException variation or reference is not a member
319 */
320 public SongBlock getNextBlock(
321 SongBlock reference,
322 Variation variation);
323
324
325 /**
326 * Get the previous block preceding reference, in the given variation.
327 * If reference is null, returns the last block.
328 * If reference is the first block, returns null;
329 * It is legal for reference to not be a member of the given variation. In such
330 * a case, the method will return the previous block that is part of this variation.
331 *
332 * @param reference reference SongBlock
333 * @param variation Variation to query, or null for the default variation
334 * @return previous block
335 * @exception IllegalArgumentException variation or reference is not a member
336 */
337 public SongBlock getPreviousBlock(
338 SongBlock reference,
339 Variation variation);
340
341
342 /**
343 * Get a SongBlock given a serializable ID. Returns null if there
344 * is no SongBlock with the given ID.
345 *
346 * @param serializableID serializable ID string
347 * @return the SongBlock with the given ID
348 */
349 public SongBlock getBlockForSerializableID(
350 String serializableID);
351
352
353 /**
354 * Get the number of fields.
355 *
356 * @return number of FieldStrings
357 */
358 public int getFieldCount();
359
360
361 /**
362 * Get the nth field
363 *
364 * @param n index
365 * @return Field
366 */
367 public Field getNthField(
368 int n);
369
370
371 /**
372 * Get the next field following reference.
373 * If reference is null, returns the first field.
374 * If reference is the last field, returns null;
375 *
376 * @param reference reference Field
377 * @return next field
378 * @exception IllegalArgumentException reference is not a member
379 */
380 public Field getNextField(
381 Field reference);
382
383
384 /**
385 * Get the previous field preceding reference.
386 * If reference is null, returns the last field.
387 * If reference is the first field, returns null;
388 *
389 * @param reference reference Field
390 * @return previous field
391 * @exception IllegalArgumentException reference is not a member
392 */
393 public Field getPreviousField(
394 Field reference);
395
396
397 /**
398 * Search for the field with the given name.
399 * Returns null if there is no such field.
400 * Implementations of this method may be faster than doing a linear
401 * search with getNextField.
402 *
403 * @param name name to search for
404 * @return the field, or null if there is no such field
405 * @exception NullPointerException name is null
406 */
407 public Field getNamedField(
408 String name);
409
410
411 //-------------------------------------------------------------------------
412 // Mutation methods
413 //-------------------------------------------------------------------------
414
415 /**
416 * Clear the song body, removes all titles, keywords, chord sets, fields
417 * and notes, and clears the credits and copyright.
418 *
419 * @param undoListener listener to notify if an undoable edit is generated,
420 * or null to suppress generation of undoable edits
421 */
422 public void clear(
423 UndoableEditListener undoListener);
424
425
426 /**
427 * Add a ChordSet
428 *
429 * @param keyType key type string
430 * @param nativeKeyNote native key Note
431 * @param undoListener listener to notify if an undoable edit is generated,
432 * or null to suppress generation of undoable edits
433 * @return ChordSet for new set
434 * @exception NullPointerException keyType or nativeKeyNode was null
435 */
436 public ChordSet addChordSet(
437 String keyType,
438 Note nativeKeyNote,
439 UndoableEditListener undoListener);
440
441
442 /**
443 * Remove a ChordSet.
444 *
445 * @param cs ChordSet
446 * @param undoListener listener to notify if an undoable edit is generated,
447 * or null to suppress generation of undoable edits
448 * @exception IllegalArgumentException cs is not present
449 * @exception NullPointerException cs was null
450 */
451 public void removeChordSet(
452 ChordSet cs,
453 UndoableEditListener undoListener);
454
455
456 /**
457 * Set a ChordSet as the default. The ChordSet given must be
458 * a member of this song. You may pass null, which sets no default.
459 *
460 * @param cs ChordSet to set as the default.
461 * @param undoListener listener to notify if an undoable edit is generated,
462 * or null to suppress generation of undoable edits
463 * @exception IllegalArgumentException cs is not a member of this song
464 */
465 public void setDefaultChordSet(
466 ChordSet cs,
467 UndoableEditListener undoListener);
468
469
470 /**
471 * Add a Variation
472 *
473 * @param undoListener listener to notify if an undoable edit is generated,
474 * or null to suppress generation of undoable edits
475 * @return added Variation
476 */
477 public Variation addVariation(
478 UndoableEditListener undoListener);
479
480
481 /**
482 * Remove a Variation.
483 *
484 * @param variation Variation
485 * @param undoListener listener to notify if an undoable edit is generated,
486 * or null to suppress generation of undoable edits
487 * @exception IllegalArgumentException variation is not present
488 * @exception NullPointerException variation was null
489 */
490 public void removeVariation(
491 Variation variation,
492 UndoableEditListener undoListener);
493
494
495 /**
496 * Add a SongBlock at the given position in the given variation. If variation
497 * is null, the block added is a StandardSongBlock and is added to the default
498 * song (thus, it is added to all variations.) Otherwise, an AddedSongBlock is
499 * added to the given variation.
500 *
501 * @param before insert before this block, or at the end if null
502 * @param variation Variation to add to, or null to add to all variations.
503 * @param undoListener listener to notify if an undoable edit is generated,
504 * or null to suppress generation of undoable edits
505 * @return added SongBlock
506 * @exception IllegalArgumentException before or variation is not a member
507 */
508 public SongBlock insertBlockBefore(
509 SongBlock before,
510 Variation variation,
511 UndoableEditListener undoListener);
512
513
514 /**
515 * Add a SongBlock at the given position in the given variation. If variation
516 * is null, the block added is a StandardSongBlock and is added to the default
517 * song (thus, it is added to all variations.) Otherwise, an AddedSongBlock is
518 * added to the given variation.
519 *
520 * @param after insert after this block, or at the beginning if null
521 * @param variation Variation to add to, or null to add to all variations.
522 * @param undoListener listener to notify if an undoable edit is generated,
523 * or null to suppress generation of undoable edits
524 * @return added SongBlock
525 * @exception IllegalArgumentException after or variation is not a member
526 */
527 public SongBlock insertBlockAfter(
528 SongBlock after,
529 Variation variation,
530 UndoableEditListener undoListener);
531
532
533 /**
534 * Remove the given SongBlock.
535 *
536 * @param block block to remove
537 * @param undoListener listener to notify if an undoable edit is generated,
538 * or null to suppress generation of undoable edits
539 * @exception IllegalArgumentException block is not present
540 * @exception NullPointerException block was null
541 */
542 public void removeBlock(
543 SongBlock block,
544 UndoableEditListener undoListener);
545
546
547 /**
548 * Add a string field. If a string field with the given name is already present,
549 * sets the value of the field and returns it. If a field of a different type is already
550 * present with the given name, replaces it with a new string field.
551 *
552 * @param name name String. The empty string is not an acceptable name.
553 * @param str value String. The empty string is acceptable.
554 * @param undoListener listener to notify if an undoable edit is generated,
555 * or null to suppress generation of undoable edits
556 * @return StringField
557 * @exception NullPointerException name or str was null
558 * @exception IllegalArgumentException name was the empty string
559 */
560 public StringField addStringField(
561 String name,
562 String str,
563 UndoableEditListener undoListener);
564
565
566 /**
567 * Add a string list field. If a string list field with the given name is already present,
568 * returns the existing field and doesn't modify it. If a field of a different type is already
569 * present with the given name, replaces it with a new string list field.
570 *
571 * @param name name String. The empty string is not an acceptable name.
572 * @param undoListener listener to notify if an undoable edit is generated,
573 * or null to suppress generation of undoable edits
574 * @return StringListField
575 * @exception NullPointerException name or str was null
576 * @exception IllegalArgumentException name was the empty string
577 */
578 public StringListField addStringListField(
579 String name,
580 UndoableEditListener undoListener);
581
582
583 /**
584 * Remove a Field.
585 *
586 * @param field Field to remove
587 * @param undoListener listener to notify if an undoable edit is generated,
588 * or null to suppress generation of undoable edits
589 * @exception IllegalArgumentException field is not present
590 * @exception NullPointerException field was null
591 */
592 public void removeField(
593 Field field,
594 UndoableEditListener undoListener);
595 }