Package org.jjazz.rhythmdatabase.api

Interface RhythmDatabase

public interface RhythmDatabase
The RhythmDatabase is the central place to get information about installed rhythms and get Rhythm instances.

Implementation should populate the database upon creation.

RhythmInfo instances are used to describe the available rhythms. They can be serialized by a Rhythmdatabase implementation in a cache file to avoid requesting all the Rhythm instances upon each startup -this is very time consuming when hundreds of rhythm files are used. Use getRhythmInstance(RhythmInfo) to get the Rhythm instance.

  • Method Details

    • getDefault

      static RhythmDatabase getDefault()
      Use the first implementation present in the global lookup.

      If nothing found, use the default one.

      Returns:

    • getUnitTestDefault

      static RhythmDatabase getUnitTestDefault()
      Get a special RhythmDatabase instance for unit tests.
      Returns:

    • getRhythmInstance

      Rhythm getRhythmInstance(String rhythmId) throws UnavailableRhythmException
      Get a rhythm instance from its id.

      If rhythmId contains 2 instances of the AdaptedRhythm.RHYTHM_ID_DELIMITER, then this id represents an AdaptedRhythm which is created on demand, see AdaptedRhythm.getUniqueId(). The rhythm provider, the original rhythm and the time signature are obtained from rhythmId, and the returned rhythm instance is obtained by calling RhythmProvider.getAdaptedRhythmInstance(Rhythm, TimeSignature). Rhythm instances are cached.

      Parameters:
      rhythmId - A unique id
      Returns:
      The rhythm whose uniqueSerialId matches the specified id
      Throws:
      UnavailableRhythmException

    • getRhythmInstance

      Rhythm getRhythmInstance(RhythmInfo rhythmInfo) throws UnavailableRhythmException
      Get a rhythm instance from a RhythmInfo.

      This might result in a lengthy operation (e.g. because of file reading). Rhythm instances are cached.

      Parameters:
      rhythmInfo -
      Returns:
      Throws:
      UnavailableRhythmException

    • getRhythm

      RhythmInfo getRhythm(String rhythmId)
      Get the RhythmInfo instance from the specified rhythm unique id.

      RhyhmtInfo instances are cached.

      Parameters:
      rhythmId -
      Returns:
      Can be null if not found.

    • getAdaptedRhythmInstance

      AdaptedRhythm getAdaptedRhythmInstance(Rhythm r, TimeSignature ts)
      Try to provide the rhythm instance which is an adapted version of r for a different time signature.

      If the adapted rhythm could be obtained it is added in the database. AdaptedRhythm instances are cached.

      Parameters:
      r -
      ts -
      Returns:
      Can be null if no adapted rhythm is available.
      Throws:
      IllegalArgumentException - If ts is the time signature of r, or if r is not a rhythm of this database.

    • getRhythms

      List<RhythmInfo> getRhythms(Predicate<RhythmInfo> tester)
      Get the rhythms which are tested OK.
      Parameters:
      tester -
      Returns:

    • getRhythms

      List<RhythmInfo> getRhythms(TimeSignature ts)
      Get the rhythms which match the specified time signature.
      Parameters:
      ts - TimeSignature
      Returns:
      All rhythms corresponding to TimeSignature ts.

    • getRhythms

      List<RhythmInfo> getRhythms(RhythmProvider rp)
      The rhythms associated to the specified RhythmProvider
      Parameters:
      rp -
      Returns:
      Throws:
      IllegalArgumentException - If rp is not a RhythmProvider available.

    • getSimilarRhythm

      RhythmInfo getSimilarRhythm(RhythmInfo ri)
      Try to find a rhythm in the database which is "similar" to the specified rhythm info.

      "Similar" means at least share the same time signature. The implementation could for example use RhythmFeatures.getMatchingScore() to help identify the most similar rhythm.

      Parameters:
      ri -
      Returns:
      A "similar" rhythm which at least share the same timesignature. Null if nothing relevant found.

    • getRhythms

      List<RhythmInfo> getRhythms()
      Returns:
      All rhythms stored in the database.

    • getRhythmProvider

      RhythmProvider getRhythmProvider(Rhythm rhythm)
      Parameters:
      rhythm -
      Returns:
      The RhythmProvider of the specified rhythm. Null if not found.

    • getRhythmProvider

      RhythmProvider getRhythmProvider(RhythmInfo ri)
      Get the RhythmProvider for specified RhythmInfo.
      Parameters:
      ri -
      Returns:
      The RhythmProvider of the specified RhythmInfo. Can be null.

    • getRhythmProvider

      RhythmProvider getRhythmProvider(String rpId)
      Get the RhythmProviderId which matchs the specified unique id.
      Parameters:
      rpId -
      Returns:

    • getRhythmProviders

      List<RhythmProvider> getRhythmProviders()
      The RhythmProviders instances currently available, sorted by name.
      Returns:

    • getTimeSignatures

      List<TimeSignature> getTimeSignatures()
      Returns:
      The list of TimeSignature for which we have at least 1 rhythm in the database

    • getDefaultRhythm

      RhythmInfo getDefaultRhythm(TimeSignature ts)
      Get the default Rhythm for TimeSignature ts.
      Parameters:
      ts - TimeSignature
      Returns:
      Can not be null, but there is no guarantee that getRhythmInstance() on the returned value will work (e.g. if this RhythmInfo depends on a file which is no more available).

    • getDefaultStubRhythmInstance

      Rhythm getDefaultStubRhythmInstance(TimeSignature ts)
      Get the default stub rhythm for the specified TimeSignature.
      Parameters:
      ts -
      Returns:
      Can't be null.

    • setDefaultRhythm

      void setDefaultRhythm(TimeSignature ts, RhythmInfo ri)
      Set the default rhythm for this TimeSignature.
      Parameters:
      ts - TimeSignature
      ri -
      Throws:
      IllegalArgumentException - If rhythm is not part of this database or if ri is an AdaptedRhythm

    • size

      int size()
      Returns:
      The number of rhythms in the database.

    • forceRescan

      void forceRescan(boolean immediate)
      Force a rescan of all the RhythmProviders available in the lookup to add rhythms in the database.

      Rescan is programmed to be performed at next application startup. It might be done immediatly if the immediate parameter is true and if the implementation supports it.

      Note: once added in the database, a RhythmProvider and its Rhythms can't be removed (until program restarts).
      Fire a change event if database has changed after the forceRescanUponStartup.

      Parameters:
      immediate - If true try to rescan immediatly (without waiting for a restart).

    • addExtraRhythms

      int addExtraRhythms(List<RhythmDatabase.RpRhythmPair> pairs)
      Add extra rhythms to the database.

      Add new rhythms to a populated database. Fire a change event after rhythms have been added.

      Parameters:
      pairs -
      Returns:
      The nb of rhythms actually added.

    • addChangeListener

      void addChangeListener(ChangeListener l)
      Listeners are notified when the rhythm database has changed.

      Note that listeners might be notified out of the Event Dispatch Thread.

      Parameters:
      l -

    • removeChangeListener

      void removeChangeListener(ChangeListener l)