Package org.jjazz.song.api

Class Song

java.lang.Object
org.jjazz.song.api.Song
All Implemented Interfaces:
PropertyChangeListener, Serializable, EventListener, ClsChangeListener, SgsChangeListener
public class Song extends Object implements Serializable, ClsChangeListener, SgsChangeListener, PropertyChangeListener
The song object.

Contents are a chord leadsheet, the related song structure, some parameters and some optional client properties.
Songs can be created using the SongFactory methods.

See Also:

  • Field Details

    • PROP_NAME

      public static final String PROP_NAME
      See Also:

    • PROP_COMMENTS

      public static final String PROP_COMMENTS
      See Also:

    • PROP_TAGS

      public static final String PROP_TAGS
      See Also:

    • PROP_TEMPO

      public static final String PROP_TEMPO
      See Also:

    • PROP_VETOABLE_PHRASE_NAME

      public static final String PROP_VETOABLE_PHRASE_NAME
      See Also:

    • PROP_SIZE_IN_BARS

      public static final String PROP_SIZE_IN_BARS
      newValue = new size in bars. OldValue=old size in bars
      See Also:

    • PROP_VETOABLE_USER_PHRASE

      public static final String PROP_VETOABLE_USER_PHRASE
      If a user phrase is removed: oldValue=name_of_removed_phrase and newValue=removed_phrase.
      If a user phrase is added, oldValue=null and newValue=name_of_new_phrase
      See Also:

    • PROP_VETOABLE_USER_PHRASE_CONTENT

      public static final String PROP_VETOABLE_USER_PHRASE_CONTENT
      An existing phrase was replaced by another. oldValue=old_phrase, newValue=name_of_phrase.
      See Also:

    • PROP_CLOSED

      public static final String PROP_CLOSED
      Fired when the close() method is called.
      See Also:

    • PROP_MODIFIED_OR_SAVED_OR_RESET

      public static final String PROP_MODIFIED_OR_SAVED_OR_RESET
      This property changes each time the song is modified (oldValue=false, newValue=true), or saved (oldValue=true, newValue=false) or Song.setSaveNeeded(false) is called (oldValue=null, newValue=false)
      See Also:

    • PROP_MUSIC_GENERATION

      public static final String PROP_MUSIC_GENERATION
      Fired each time the musical content of the song is modified.

      OldValue=the property name or ClsActionEvent/SgsActionEvent actionId that triggered the musical change.
      NewValue=the optional associated data

      Use PROP_MODIFIED_OR_SAVED_OR_RESET to get notified of any song change, including non-musical ones like tempo change, phrase name change, etc.

      See Also:

  • Method Details

    • getClientProperties

      public StringProperties getClientProperties()

    • renameUserPhrase

      public void renameUserPhrase(String name, String newName)
      Rename a user phrase.

      Fire a PROP_VETOABLE_PHRASE_NAME change event (actually this property change event should never been vetoed, but this allows caller to use a single vetoable listener for all user phrase events).

      Parameters:
      name - Must be the name of an existing phrase
      newName -

    • setUserPhrase

      public void setUserPhrase(String name, Phrase p) throws PropertyVetoException
      Set the user phrase for the specified name.

      If a user phrase was already associated to name, it's replaced. Fire a VeotableChange PROP_VETOABLE_USER_PHRASE if no phrase is replaced, otherwise use PROP_VETOABLE_USER_PHRASE_CONTENT. Actually the possibility of a veto is only when a new phrase is added (e.g. if MidiMix does not have an available Midi channel). Other user phrase PROP_ events for simplicity only (one listener required).

      This song will listen to p's changes and fire a PROP_MODIFIED_OR_SAVED_OR_RESET change event when a non-adjusting change is made.

      Parameters:
      name - Can't be blank.
      p - Can't be null. No defensive copy is done, p is directly reused. No control is done on the phrase consistency Vs the song.
      Throws:
      PropertyVetoException - If no Midi channel available for the user phrase
      See Also:

    • removeUserPhrase

      public Phrase removeUserPhrase(String name)
      Remove the user phrase associated to name.

      Fire a PROP_VETOABLE_USER_PHRASE event.

      Parameters:
      name -
      Returns:
      The removed phrase or null

    • getUserPhraseNames

      public Set<String> getUserPhraseNames()
      Get all the names of the user phrases.
      Returns:
      Can't be null.

    • getUserPhrase

      public Phrase getUserPhrase(String name)
      Get the user phrase associated to specified name.

      Returned phrase might be longer than the song.

      The song listens to the returned phrase so that if a significant change (non-adusting) is made to it, the song will fire a PROP_MODIFIED_OR_SAVED_OR_RESET change event.

      Parameters:
      name -
      Returns:
      Null if no phrase associated to name. The Phrase channel should be ignored.

    • getChordLeadSheet

      public ChordLeadSheet getChordLeadSheet()

    • getSongStructure

      public SongStructure getSongStructure()

    • getSize

      public int getSize()
      Convenience method which delegates to getSongStructure().getSizeInBars().
      Returns:

    • getTempo

      public int getTempo()
      Get the preferred tempo for this song.
      Returns:

    • setTempo

      public final void setTempo(int newTempo)
      Set the preferred tempo for this song.

      Fire a PROP_TEMPO property change event.

      Parameters:
      newTempo -

    • setTags

      public void setTags(List<String> newTags)
      Set the list of String tags associated to this song, e.g. "rock", "dance-oriented", etc...

      Fire a PROP_TAGS property change events.

      Parameters:
      newTags - Must not be null but can be an empty list. Tags are space-trimmed and converted to lower case.

    • getTags

      public List<String> getTags()
      Returns:
      List can be empty if not tags. Tags are lowercase.

    • getName

      public String getName()
      The song name.
      Returns:

    • setName

      public final void setName(String newName)
      Set the song name.

      Fire a PROP_NAME property change event.

      Parameters:
      newName - A non-empty string.

    • close

      public void close(boolean releaseRhythmResources)
      To be called to cleanup the song when song will not be used anymore.

      Fire a PROP_CLOSED property change event.

      Parameters:
      releaseRhythmResources - True if the method should also call releaseResources() for each used rhythm.

    • isClosed

      public boolean isClosed()
      Returns:
      True if close() has been called.

    • getComments

      public String getComments()
      The comments associated to this song.
      Returns:
      Can be an empty String.

    • setComments

      public void setComments(String newComments)
      Set the comments.

      Fire the PROP_COMMENTS change event.

      Parameters:
      newComments -

    • getFile

      public File getFile()
      The file where this song is stored.
      Returns:
      Can be null for example if it's a builtin song or created programmatically.

    • setFile

      public void setFile(File f)
      Set the file from which the song can be read/written.
      Parameters:
      f - Can be null.

    • saveToFileNotify

      public boolean saveToFileNotify(File f, boolean isCopy)
      Same as SaveToFile but notify user if problem.

      Parameters:
      f -
      isCopy -
      Returns:
      False if problem

    • saveToFile

      public void saveToFile(File songFile, boolean isCopy) throws IOException
      Save this song to a file (XML format).

      Song's file and name is set to f and f's name. Fire a PROP_MODIFIED_OR_SAVED_OR_RESET property change event with oldValue=true and newValue=false.

      Parameters:
      songFile -
      isCopy - Indicate that the save operation if for a copy, ie just perform the save operation and do nothing else (song name is not set, etc.)
      Throws:
      IOException
      See Also:

    • isSaveNeeded

      public boolean isSaveNeeded()
      Returns:
      True if song has some unsaved changes.

    • setSaveNeeded

      public void setSaveNeeded(boolean b)
      Set the value of the saveNeeded property.

      Fire a PROP_MODIFIED_OR_SAVED_OR_RESET change event.

      Parameters:
      b -

    • addUndoableEditListener

      public void addUndoableEditListener(UndoableEditListener l)

    • removeUndoableEditListener

      public void removeUndoableEditListener(UndoableEditListener l)

    • addPropertyChangeListener

      public void addPropertyChangeListener(PropertyChangeListener l)

    • addPropertyChangeListener

      public void addPropertyChangeListener(String propertyName, PropertyChangeListener l)

    • removePropertyChangeListener

      public void removePropertyChangeListener(PropertyChangeListener l)

    • removePropertyChangeListener

      public void removePropertyChangeListener(String propertyName, PropertyChangeListener l)

    • addVetoableChangeListener

      public void addVetoableChangeListener(VetoableChangeListener listener)

    • removeVetoableChangeListener

      public void removeVetoableChangeListener(VetoableChangeListener listener)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • propertyChange

      public void propertyChange(PropertyChangeEvent e)
      Specified by:
      propertyChange in interface PropertyChangeListener

    • authorizeChange

      public void authorizeChange(ClsChangeEvent e) throws UnsupportedEditException
      Description copied from interface: ClsChangeListener
      Some change events might need to be authorized by all listeners before being processed by chordLeadSheetChanged().
      Specified by:
      authorizeChange in interface ClsChangeListener
      Parameters:
      e - The change to authorize.
      Throws:
      UnsupportedEditException - Listener shall throw this exception if change is not acceptable. Exception message might be shown to user to explain the problem.

    • chordLeadSheetChanged

      public void chordLeadSheetChanged(ClsChangeEvent event)
      Description copied from interface: ClsChangeListener
      Process the change.

      Note that this method might be called outside of the EDT.

      Specified by:
      chordLeadSheetChanged in interface ClsChangeListener

    • authorizeChange

      public void authorizeChange(SgsChangeEvent e) throws UnsupportedEditException
      Description copied from interface: SgsChangeListener
      Some change events might need to be authorized by all listeners before being processed by songStructureChanged().
      Specified by:
      authorizeChange in interface SgsChangeListener
      Parameters:
      e - The change to authorize.
      Throws:
      UnsupportedEditException - Listener shall throw this exception if change is not acceptable. Exception message might be shown to user to explain the problem.

    • songStructureChanged

      public void songStructureChanged(SgsChangeEvent e)
      Description copied from interface: SgsChangeListener
      Process the change.

      Note that this method might be called outside of the EDT.

      Specified by:
      songStructureChanged in interface SgsChangeListener