com.virtuosotechnologies.asaph.modelutils
Interface SongUtils

public interface SongUtils

API that includes utilities for manipulating songs.

This API is thread-safe and may be called from any thread.

Method Summary

void	compactLine(SongLine line, UndoableEditListener undoListener) Compact a line-- aggregates any consecutive comment strings or text strings, ensures inserts empty text between adjacent chords in the same chord set, and ensures that the line starts and ends with strings.
void	compactSong(Song song, UndoableEditListener undoListener) Compact a song-- performs compactLine on all lines in the song.
void	copySong(Song source, Song destination) Make one song a copy of another.
BinaryField	forceGetBinaryField(FieldContainer fieldContainer, String fieldName, String defaultType, byte[] defaultValue, UndoableEditListener undoListener) Ensure that a field exists and is a binary field.
BinaryListField	forceGetBinaryListField(FieldContainer fieldContainer, String fieldName, UndoableEditListener undoListener) Ensure that a field exists and is a binary list.
StringField	forceGetStringField(FieldContainer fieldContainer, String fieldName, String defaultStr, UndoableEditListener undoListener) Ensure that a field exists and is a string.
StringListField	forceGetStringListField(FieldContainer fieldContainer, String fieldName, UndoableEditListener undoListener) Ensure that a field exists and is a string list.
String	getFieldValueAsString(FieldContainer fieldContainer, String fieldName) Get a field value as a string.
String[]	getFieldValueAsStringArray(FieldContainer fieldContainer, String fieldName) Get a field value as a string array.
String	getFirstLineAsString(Song song, boolean useVariation, Variation variation) Get the first line of the song as a string.
int	getMemberPosition(SongLineMember member, ChordSet set) Get the index of a line member within its line
String	getMultiLineString(StringList stringList) Get the StringList value as a string with newline delimiters.
String	getSongTextAsString(Song song, boolean useVariation, Variation variation) Get the entire song text as a string.
ChordAnnotation	moveChordAnnotation(ChordAnnotation chord, TextString destinationMember, int destinationPos, ChordSet destinationSet, UndoableEditListener undoListener) Move a chord marking
boolean	prepareSongForEditing(Song song) Normalize a song for editing.
void	removeLineRange(SongLine line, TextString startMember, int startPos, TextString endMember, int endPos, UndoableEditListener undoListener) Remove the given range from a line
void	setMultiLineString(StringList stringList, String value, UndoableEditListener undoListener) Parses the given string into lines and sets the string list value.
SongBlock	splitBlock(SongBlock block, SongLine line, UndoableEditListener undoListener) Split a block in half.
SongLine	splitLine(TextString member, int pos, UndoableEditListener undoListener) Split a line in half.
void	transpose(SongBlock block, ChordSet chordSet, Interval interval, UndoableEditListener undoListener) Transpose chords in the given song block.
void	transpose(Song song, ChordSet chordSet, Interval interval, UndoableEditListener undoListener) Transpose chords in the given song.
void	transpose(SongLine line, ChordSet chordSet, Interval interval, UndoableEditListener undoListener) Transpose chords in the given song line.

Method Detail

copySong

public void copySong(Song source,
                     Song destination)

Make one song a copy of another. Clears out the destination song, and copies the source into it. Does not affect the SongID or owner database of the destination. Also not undoable, so note that it breaks the undo chain.

Parameters:

source - source song

destination - destination song

prepareSongForEditing

public boolean prepareSongForEditing(Song song)

Normalize a song for editing. Involves compacting each line and ensuring that the first and last song line member of each line is a text member. Not undoable, so note that it breaks the undo chain.

Parameters:

song - Song to prepare

Returns:

true if the song appears to have just been created, otherwise false.

compactLine

public void compactLine(SongLine line,
                        UndoableEditListener undoListener)

Compact a line-- aggregates any consecutive comment strings or text strings, ensures inserts empty text between adjacent chords in the same chord set, and ensures that the line starts and ends with strings. After this operation, any old handles to LineMembers may be invalid.

Parameters:

line - SongLine to compact

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

Throws:

NullPointerException - line was null

compactSong

public void compactSong(Song song,
                        UndoableEditListener undoListener)

Compact a song-- performs compactLine on all lines in the song. After this operation, any old handles to LineMembers may be invalid.

Parameters:

song - Song to compact

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

Throws:

NullPointerException - line was null

forceGetStringField

public StringField forceGetStringField(FieldContainer fieldContainer,
                                       String fieldName,
                                       String defaultStr,
                                       UndoableEditListener undoListener)

Ensure that a field exists and is a string. If the field is not present, creates it and assigns the given default value. If the field is present but is a string list, replaces it with a string field set to the given default value.

Parameters:

fieldContainer - FieldContainer to query

fieldName - field name

defaultStr - default value

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

Returns:

field as a StringField

Throws:

NullPointerException - something was null

forceGetStringListField

public StringListField forceGetStringListField(FieldContainer fieldContainer,
                                               String fieldName,
                                               UndoableEditListener undoListener)

Ensure that a field exists and is a string list. If the field is not present, creates an empty string list. If the field is present but is a string, replaces it with an empty string list field.

Parameters:

fieldContainer - FieldContainer to query

fieldName - field name

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

Returns:

field as a StringListField

Throws:

NullPointerException - something was null

forceGetBinaryField

public BinaryField forceGetBinaryField(FieldContainer fieldContainer,
                                       String fieldName,
                                       String defaultType,
                                       byte[] defaultValue,
                                       UndoableEditListener undoListener)

Ensure that a field exists and is a binary field. If the field is not present, creates it and assigns the given default value. If the field is present but is not a binary field, replaces it with a binary field set to the given default value.

Parameters:

fieldContainer - FieldContainer to query

fieldName - field name

defaultType - default data type

defaultValue - default value

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

Returns:

field as a BinaryField

Throws:

NullPointerException - something was null

forceGetBinaryListField

public BinaryListField forceGetBinaryListField(FieldContainer fieldContainer,
                                               String fieldName,
                                               UndoableEditListener undoListener)

Ensure that a field exists and is a binary list. If the field is not present, creates an empty binary list. If the field is present but is not a binary list, replaces it with an empty binary list field.

Parameters:

fieldContainer - FieldContainer to query

fieldName - field name

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

Returns:

field as a BinaryListField

Throws:

NullPointerException - something was null

getFieldValueAsString

public String getFieldValueAsString(FieldContainer fieldContainer,
                                    String fieldName)

Get a field value as a string. If the field is not present, returns the empty string. If the field is a string field, returns its value. If the field is a string list field, returns the values delimited by newlines.

Parameters:

fieldContainer - FieldContainer to query

fieldName - field name

Returns:

field value as a string

Throws:

NullPointerException - something was null

getFieldValueAsStringArray

public String[] getFieldValueAsStringArray(FieldContainer fieldContainer,
                                           String fieldName)

Get a field value as a string array. If the field is not present, returns the zero-length array. If the field is a string field, returns a one-element array with the value. If the field is a string list field, returns the values in an array.

Parameters:

fieldContainer - FieldContainer to query

fieldName - field name

Returns:

field value as a string array

Throws:

NullPointerException - something was null

getMultiLineString

public String getMultiLineString(StringList stringList)

Get the StringList value as a string with newline delimiters.

Parameters:

stringList - StringList to query

Returns:

field value as a string

Throws:

NullPointerException - something was null

setMultiLineString

public void setMultiLineString(StringList stringList,
                               String value,
                               UndoableEditListener undoListener)

Parses the given string into lines and sets the string list value.

Parameters:

stringList - StringList to modify

value - field value as a string with newlines

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

Throws:

NullPointerException - something was null

getSongTextAsString

public String getSongTextAsString(Song song,
                                  boolean useVariation,
                                  Variation variation)

Get the entire song text as a string. Comments are stripped. Lines are delimited by newlines, and blocks by double newlines.

Parameters:

song - song to query

useVariation - true to query a specific variation, specified by the variation parameter, or false to query the entire text (which may not correspond to any actual variation)

variation - variation to get, or null for the default variation. Ignored if useVariation is false

Returns:

a string containing the song body text, sans comments

Throws:

NullPointerException - something was null

getFirstLineAsString

public String getFirstLineAsString(Song song,
                                   boolean useVariation,
                                   Variation variation)

Get the first line of the song as a string. Comments are stripped.

Parameters:

song - song to query

useVariation - true to query a specific variation, specified by the variation parameter, or false to query the entire text (which may not correspond to any actual variation)

variation - variation to get, or null for the default variation. Ignored if useVariation is false

Returns:

a string containing the song body text, sans comments

Throws:

NullPointerException - something was null

removeLineRange

public void removeLineRange(SongLine line,
                            TextString startMember,
                            int startPos,
                            TextString endMember,
                            int endPos,
                            UndoableEditListener undoListener)

Remove the given range from a line

Parameters:

line - line to edit

startMember - Start of the range to remove. Null for the beginning of the line

startPos - position within startMember

endMember - End of the range to remove. Null for the end of the line

endPos - position within endMember

undoListener - listener for undo records, or null to not generate edits

moveChordAnnotation

public ChordAnnotation moveChordAnnotation(ChordAnnotation chord,
                                           TextString destinationMember,
                                           int destinationPos,
                                           ChordSet destinationSet,
                                           UndoableEditListener undoListener)

Move a chord marking

Parameters:

chord - Chord to move. If null, inserts an empty chord.

destinationMember - Text member containing the chord destination

destinationPos - position within destinationMember

destinationSet - ChordSet to move chord to. If null, uses chord's set.

undoListener - listener for undo records, or null to not generate edits

Returns:

the new ChordAnnotation

getMemberPosition

public int getMemberPosition(SongLineMember member,
                             ChordSet set)

Get the index of a line member within its line

Parameters:

member - member to query

set - ChordSet to limit to, or null for entire line

Returns:

position of member

splitLine

public SongLine splitLine(TextString member,
                          int pos,
                          UndoableEditListener undoListener)

Split a line in half.

Parameters:

member - member containing the split position

pos - position within member

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

Throws:

NullPointerException - member was null

splitBlock

public SongBlock splitBlock(SongBlock block,
                            SongLine line,
                            UndoableEditListener undoListener)

Split a block in half.

Parameters:

block - block to split.

line - last line in the first half. The split position will be after this line. Pass null to "split" at the beginning of the block.

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

Throws:

NullPointerException - member was null

transpose

public void transpose(SongLine line,
                      ChordSet chordSet,
                      Interval interval,
                      UndoableEditListener undoListener)

Transpose chords in the given song line.

Parameters:

line - line to transpose

chordSet - chord set to transpose

interval - interval to transpose

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

Throws:

NullPointerException - something was null

transpose

public void transpose(SongBlock block,
                      ChordSet chordSet,
                      Interval interval,
                      UndoableEditListener undoListener)

Transpose chords in the given song block.

Parameters:

block - block to transpose

chordSet - chord set to transpose

interval - interval to transpose

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

Throws:

NullPointerException - something was null

transpose

public void transpose(Song song,
                      ChordSet chordSet,
                      Interval interval,
                      UndoableEditListener undoListener)

Transpose chords in the given song.

Parameters:

song - song to transpose

chordSet - chord set to transpose

interval - interval to transpose

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

Throws:

NullPointerException - something was null