com.virtuosotechnologies.asaph.model
Interface Song

All Superinterfaces:

FieldContainer

public interface Song

extends FieldContainer

This is the primary interface to a Song. Songs are obtained from a SongDatabase. However, Song objects are always "checked-out" copies of the actual Song data. This lets clients manipulate the Song without worry about concurrent access. To commit changes, use the commit method of SongDatabase.

Field Summary

static String	ALTERNATETITLELIST_FIELD Name of alternate titles field.
static String	AUTHOR_FIELD Name of author field.
static String	COMMENT_FIELD Name of comment field.
static String	COPYRIGHT_FIELD Name of copyright field.
static String	KEYWORDLIST_FIELD Name of keywords field.
static String	MAINTITLE_FIELD Name of main title field.
static String	NOTESLIST_FIELD Name of notes field.

Method Summary

ChordSet	addChordSet(Locale locale, Note nativeKeyNote, UndoableEditListener undoListener) Add a ChordSet
Variation	addVariation(UndoableEditListener undoListener) Add a Variation
void	clear(UndoableEditListener undoListener) Clear the song body and remove all chord sets, variations, and fields.
void	detach() Detach this song from its database if it is associated with a database.
int	getBlockCount() Get the total number of SongBlocks in the song.
int	getBlockCount(Variation variation) Get the number of SongBlocks present for the given variation.
SongBlock	getBlockForSerializableID(String serializableID) Get a SongBlock given a serializable ID.
int	getChordSetCount() Get the number of ChordSets.
ChordSet	getChordSetForSerializableID(String serializableID) Get a ChordSet given a serializable ID.
ChordSet	getDefaultChordSet() Get default chord set.
Locale	getLocale() Get the locale of the song.
SongBlock	getNextBlock(SongBlock reference) Get the next block following reference.
SongBlock	getNextBlock(SongBlock reference, Variation variation) Get the next block following reference, in the given variation.
ChordSet	getNextChordSet(ChordSet reference) Get the next chord set following reference.
Variation	getNextVariation(Variation reference) Get the next variation following reference.
SongBlock	getNthBlock(int n) Get the nth SongBlock
SongBlock	getNthBlock(int n, Variation variation) Get the nth SongBlock in the given variation.
ChordSet	getNthChordSet(int n) Get the nth ChordSet
Variation	getNthVariation(int n) Get the nth Variation
SongBlock	getPreviousBlock(SongBlock reference) Get the previous block preceding reference.
SongBlock	getPreviousBlock(SongBlock reference, Variation variation) Get the previous block preceding reference, in the given variation.
ChordSet	getPreviousChordSet(ChordSet reference) Get the previous chord set preceding reference.
Variation	getPreviousVariation(Variation reference) Get the previous variation preceding reference.
SongID	getSongID() Get the id used to check out the song from its database.
int	getVariationCount() Get the number of Variations.
Variation	getVariationForSerializableID(String serializableID) Get a Variation given a serializable ID.
SongBlock	insertBlockAfter(SongBlock after, Variation variation, UndoableEditListener undoListener) Add a SongBlock at the given position in the given variation.
SongBlock	insertBlockBefore(SongBlock before, Variation variation, UndoableEditListener undoListener) Add a SongBlock at the given position in the given variation.
void	removeBlock(SongBlock block, UndoableEditListener undoListener) Remove the given SongBlock.
void	removeChordSet(ChordSet cs, UndoableEditListener undoListener) Remove a ChordSet.
void	removeVariation(Variation variation, UndoableEditListener undoListener) Remove a Variation.
void	setDefaultChordSet(ChordSet cs, UndoableEditListener undoListener) Set a ChordSet as the default.

Methods inherited from interface com.virtuosotechnologies.asaph.model.FieldContainer

addBinaryField, addBinaryListField, addStringField, addStringListField, getFieldCount, getNamedField, getNextField, getNthField, getPreviousField, removeField

Field Detail

MAINTITLE_FIELD

public static final String MAINTITLE_FIELD

Name of main title field. Value is a StringField.

See Also:

Constant Field Values

COMMENT_FIELD

public static final String COMMENT_FIELD

Name of comment field. Value is a StringField.

See Also:

Constant Field Values

ALTERNATETITLELIST_FIELD

public static final String ALTERNATETITLELIST_FIELD

Name of alternate titles field. Value is a StringListField.

See Also:

Constant Field Values

AUTHOR_FIELD

public static final String AUTHOR_FIELD

Name of author field. Value is a StringField.

See Also:

Constant Field Values

COPYRIGHT_FIELD

public static final String COPYRIGHT_FIELD

Name of copyright field. Value is a StringField.

See Also:

Constant Field Values

KEYWORDLIST_FIELD

public static final String KEYWORDLIST_FIELD

Name of keywords field. Value is a StringListField.

See Also:

Constant Field Values

NOTESLIST_FIELD

public static final String NOTESLIST_FIELD

Name of notes field. Value is a StringListField.

See Also:

Constant Field Values

Method Detail

getSongID

public SongID getSongID()

Get the id used to check out the song from its database. Returns null if this song is not associated with a database.

Returns:

song id

getLocale

public Locale getLocale()

Get the locale of the song.

Returns:

Locale

getChordSetCount

public int getChordSetCount()

Get the number of ChordSets.

Returns:

number of ChordSets

getNthChordSet

public ChordSet getNthChordSet(int n)

Get the nth ChordSet

Parameters:

n - index

Returns:

ChordSet

getNextChordSet

public ChordSet getNextChordSet(ChordSet reference)

Get the next chord set following reference. If reference is null, returns the first chord set. If reference is the last chord set, returns null;

Parameters:

reference - reference ChordSet

Returns:

next chord set

Throws:

IllegalArgumentException - reference is not a member

getPreviousChordSet

public ChordSet getPreviousChordSet(ChordSet reference)

Get the previous chord set preceding reference. If reference is null, returns the last chord set. If reference is the first chord set, returns null;

Parameters:

reference - reference ChordSet

Returns:

previous chord set

Throws:

IllegalArgumentException - reference is not a member

getDefaultChordSet

public ChordSet getDefaultChordSet()

Get default chord set. Returns null if there is no default.

Returns:

default ChordSet

getChordSetForSerializableID

public ChordSet getChordSetForSerializableID(String serializableID)

Get a ChordSet given a serializable ID. Returns null if there is no ChordSet with the given ID.

Parameters:

serializableID - serializable ID string

Returns:

the ChordSet with the given ID

getVariationCount

public int getVariationCount()

Get the number of Variations.

Returns:

number of Variations

getNthVariation

public Variation getNthVariation(int n)

Get the nth Variation

Parameters:

n - index

Returns:

Variation

getNextVariation

public Variation getNextVariation(Variation reference)

Get the next variation following reference. If reference is null, returns the first variation. If reference is the last variation, returns null;

Parameters:

reference - reference Variation

Returns:

next variation

Throws:

IllegalArgumentException - reference is not a member

getPreviousVariation

public Variation getPreviousVariation(Variation reference)

Get the previous variation preceding reference. If reference is null, returns the last variation. If reference is the first variation, returns null;

Parameters:

reference - reference Variation

Returns:

previous variation

Throws:

IllegalArgumentException - reference is not a member

getVariationForSerializableID

public Variation getVariationForSerializableID(String serializableID)

Get a Variation given a serializable ID. Returns null if there is no Variation with the given ID.

Parameters:

serializableID - serializable ID string

Returns:

the Variation with the given ID

getBlockCount

public int getBlockCount()

Get the total number of SongBlocks in the song. This list may not correspond to any particular variation of the song.

Returns:

number of SongBlocks

getNthBlock

public SongBlock getNthBlock(int n)

Get the nth SongBlock

Parameters:

n - index

Returns:

SongBlock

getNextBlock

public SongBlock getNextBlock(SongBlock reference)

Get the next block following reference. If reference is null, returns the first block. If reference is the last block, returns null;

Parameters:

reference - reference SongBlock

Returns:

next block

Throws:

IllegalArgumentException - reference is not a member

getPreviousBlock

public SongBlock getPreviousBlock(SongBlock reference)

Get the previous block preceding reference. If reference is null, returns the last block. If reference is the first block, returns null;

Parameters:

reference - reference SongBlock

Returns:

previous block

Throws:

IllegalArgumentException - reference is not a member

getBlockCount

public int getBlockCount(Variation variation)

Get the number of SongBlocks present for the given variation. Pass null to specify the default variation.

Parameters:

variation - Variation to query, or null for the default variation

Returns:

number of SongBlocks

Throws:

IllegalArgumentException - variation is not a member

getNthBlock

public SongBlock getNthBlock(int n,
                             Variation variation)

Get the nth SongBlock in the given variation. Pass null to specify the default variation

Parameters:

n - index

variation - Variation to query, or null for the default variation

Returns:

SongBlock

getNextBlock

public SongBlock getNextBlock(SongBlock reference,
                              Variation variation)

Get the next block following reference, in the given variation. If reference is null, returns the first block. If reference is the last block, returns null; It is legal for reference to not be a member of the given variation. In such a case, the method will return the next block that is part of this variation.

Parameters:

reference - reference SongBlock

variation - Variation to query, or null for the default variation

Returns:

next block

Throws:

IllegalArgumentException - variation or reference is not a member

getPreviousBlock

public SongBlock getPreviousBlock(SongBlock reference,
                                  Variation variation)

Get the previous block preceding reference, in the given variation. If reference is null, returns the last block. If reference is the first block, returns null; It is legal for reference to not be a member of the given variation. In such a case, the method will return the previous block that is part of this variation.

Parameters:

reference - reference SongBlock

variation - Variation to query, or null for the default variation

Returns:

previous block

Throws:

IllegalArgumentException - variation or reference is not a member

getBlockForSerializableID

public SongBlock getBlockForSerializableID(String serializableID)

Get a SongBlock given a serializable ID. Returns null if there is no SongBlock with the given ID.

Parameters:

serializableID - serializable ID string

Returns:

the SongBlock with the given ID

clear

public void clear(UndoableEditListener undoListener)

Clear the song body and remove all chord sets, variations, and fields.

Parameters:

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

detach

public void detach()

Detach this song from its database if it is associated with a database. Does nothing if this song is already detached. After this method completes, calling getSongID() will return null. This method is not undoable.

addChordSet

public ChordSet addChordSet(Locale locale,
                            Note nativeKeyNote,
                            UndoableEditListener undoListener)

Add a ChordSet

Parameters:

locale - Locale for the ChordSet, or null to use the Song's default.

nativeKeyNote - native key Note

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Returns:

ChordSet for new set

Throws:

NullPointerException - keyType or nativeKeyNode was null

removeChordSet

public void removeChordSet(ChordSet cs,
                           UndoableEditListener undoListener)

Remove a ChordSet.

Parameters:

cs - ChordSet

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Throws:

IllegalArgumentException - cs is not present

NullPointerException - cs was null

setDefaultChordSet

public void setDefaultChordSet(ChordSet cs,
                               UndoableEditListener undoListener)

Set a ChordSet as the default. The ChordSet given must be a member of this song. You may pass null, which sets no default.

Parameters:

cs - ChordSet to set as the default.

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Throws:

IllegalArgumentException - cs is not a member of this song

addVariation

public Variation addVariation(UndoableEditListener undoListener)

Add a Variation

Parameters:

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Returns:

added Variation

removeVariation

public void removeVariation(Variation variation,
                            UndoableEditListener undoListener)

Remove a Variation.

Parameters:

variation - Variation

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Throws:

IllegalArgumentException - variation is not present

NullPointerException - variation was null

insertBlockBefore

public SongBlock insertBlockBefore(SongBlock before,
                                   Variation variation,
                                   UndoableEditListener undoListener)

Add a SongBlock at the given position in the given variation. If variation is null, the block added is a StandardSongBlock and is added to the default song (thus, it is added to all variations.) Otherwise, an AddedSongBlock is added to the given variation.

Parameters:

before - insert before this block, or at the end if null

variation - Variation to add to, or null to add to all variations.

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Returns:

added SongBlock

Throws:

IllegalArgumentException - before or variation is not a member

insertBlockAfter

public SongBlock insertBlockAfter(SongBlock after,
                                  Variation variation,
                                  UndoableEditListener undoListener)

Add a SongBlock at the given position in the given variation. If variation is null, the block added is a StandardSongBlock and is added to the default song (thus, it is added to all variations.) Otherwise, an AddedSongBlock is added to the given variation.

Parameters:

after - insert after this block, or at the beginning if null

variation - Variation to add to, or null to add to all variations.

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Returns:

added SongBlock

Throws:

IllegalArgumentException - after or variation is not a member

removeBlock

public void removeBlock(SongBlock block,
                        UndoableEditListener undoListener)

Remove the given SongBlock.

Parameters:

block - block to remove

undoListener - listener to notify if an undoable edit is generated, or null to suppress generation of undoable edits

Throws:

IllegalArgumentException - block is not present

NullPointerException - block was null