org.crosswire.jsword.versification

## Class VersificationsMapper

- java.lang.Object
- - org.crosswire.jsword.versification.VersificationsMapper

-     public final class VersificationsMapper
      extends Object

  VersificationMapper maps a Verse or a Passage in one Versification (v11n) to another, using the KJV v11n as an intermediary.

  Practically speaking, a Verse in one v11n may map:

  - to the same verse in another v11n. This is the typical case.
  - to another verse in the same chapter. This is common and typically by one, shifting following verses.
  - to another verse in a different chapter. This is fairly common.
  - to two other verses. This is common in the Psalms and a few places elsewhere.

  The internal details of the mapping can be found in VersificationToKJVMapper.

  This transitive relationship is not perfect. It assumes that verses outside of the KJV versification map 1:1 between the source and target Versifications. That it uses the KJV as an intermediary is an implementation detail that may change. Do not rely on it.

  Author:
    Chris Burrell
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static VersificationsMapper` | `instance`
    `private static Versification` | `KJV`
    `private static org.slf4j.Logger` | `LOGGER`
    `private static Map<Versification,VersificationToKJVMapper>` | `MAPPERS`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `VersificationsMapper()` Prevent instantiation

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private void` | `ensure(Versification versification)` Reads the mapping from file if it does not exist
    `void` | `ensureMappingDataLoaded(Versification versification)` Call this to ensure mapping data is loaded (maybe for newly installed books).
    `private VerseKey` | `getKeyFromQualifiedKeys(Versification versification, List<QualifiedKey> kjvVerses)`
    `private VerseKey` | `guessKeyFromKjvVerses(Versification targetVersification, List<QualifiedKey> kjvVerses)` This is a last attempt at trying to get something, on the basis that something is better than nothing.
    `static VersificationsMapper` | `instance()`
    `Passage` | `map(Passage key, Versification target)` Maps a whole passage, and does so verse by verse.
    `VerseKey` | `mapVerse(Verse v, Versification targetVersification)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### instance

          private static volatile VersificationsMapper instance

    - #### KJV

          private static final Versification KJV

    - #### MAPPERS

          private static final Map<Versification,VersificationToKJVMapper> MAPPERS

    - #### LOGGER

          private static final org.slf4j.Logger LOGGER

  - ### Constructor Detail

    - #### VersificationsMapper

          private VersificationsMapper()

      Prevent instantiation

  - ### Method Detail

    - #### instance

          public static VersificationsMapper instance()

      Returns:
        a singleton instance of the mapper -

    - #### map

          public Passage map(Passage key,
                    Versification target)

      Maps a whole passage, and does so verse by verse. We can't do any better, since, we may for example have: Ps.1.1-Ps.1.10 => Ps.1.2-Ps.1.11 so one would think we can simply map each of the start and end verses. However, this would be inaccurate since verse 9 might map to verse 12, 13, etc.
      Parameters:
        `key` - the key if the source versification
        `target` - the target versification
      Returns:
        the new key in the new versification

    - #### mapVerse

          public VerseKey mapVerse(Verse v,
                          Versification targetVersification)

      Parameters:
        `v` - the verse
        `targetVersification` - the final versification that we want
      Returns:
        the key for the verse

    - #### guessKeyFromKjvVerses

          private VerseKey guessKeyFromKjvVerses(Versification targetVersification,
                                       List<QualifiedKey> kjvVerses)

      This is a last attempt at trying to get something, on the basis that something is better than nothing.
      Parameters:
        `targetVersification` - the target versification
        `kjvVerses` - the verses in the KJV versification.
      Returns:
        the possible verses in the target versification, no guarantees made

    - #### getKeyFromQualifiedKeys

          private VerseKey getKeyFromQualifiedKeys(Versification versification,
                                         List<QualifiedKey> kjvVerses)

      Parameters:
        `kjvVerses` - the list of keys
      Returns:
        the aggregate key

    - #### ensureMappingDataLoaded

          public void ensureMappingDataLoaded(Versification versification)

      Call this to ensure mapping data is loaded (maybe for newly installed books). Should normally be called from a background thread, not the ui thread.
      Parameters:
        `versification` - the versification we want to load mapping data for

    - #### ensure

          private void ensure(Versification versification)

      Reads the mapping from file if it does not exist
      Parameters:
        `versification` - the versification we want to load