Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.crosswire.jsword.versification
Class VersificationToKJVMapper

    java.lang.Object
      org.crosswire.jsword.versification.VersificationToKJVMapper

    public class VersificationToKJVMapper

extends Object

A Versification mapper allows you to a map a given verse to the KJV versification, or unmap it from the KJV versification into your own versification.

A properties-like file will contain the non-KJV versification as they key, and the KJV versification value as the target value... Duplicate keys are allowed.

i.e. Gen.1.1=Gen.1.2 means Gen.1.1 in X versification is Gen.1.2 in the KJV versification

You can specify a range on either side. If a range is present on both sides, they have to have the same number of verses, i.e. verses are mapped verse by verse to each other
Gen.1.1-Gen.1.2=Gen.1.2-Gen.1.3 means Gen.1.1=Gen.1.2 and Gen.1.2=Gen.1.3
Note: if the cardinality of the left & KJV sides are different by only one, the algorithm makes the assumption that verse 0 should be disregarded in both ranges.

Mappings can be specified by offset. In this case, be aware this maps verse 0 as well. So for example:

Ps.19-Ps.20=-1 means Ps.19.0=Ps.18.50, Ps.19.1=Ps.19.0, Ps.19.2=Ps.19.1, etc.
It does not make much sense to have an offset for a single verse, so this is not supported. Offsetting for multiple ranges however does, and operates range by range, i.e. each range is calculated separately. Offsetting is somewhat equivalent to specifying ranges, and as a result, the verse 0 behaviour is identical.

You can use part-mappings. This is important if you want to preserve transformations from one side to another without losing resolution of the verse.

For example,
if V1 defines Gen.1.1=Gen.1.1, Gen.1.2=Gen1.1
if V2 defines Gen.1.1=Gen.1.1, Gen.1.2=Gen.1.1
then, mapping from V1=>KJV and KJV=>V2 gives you Gen.1.1=>Gen.1.1=>Gen.1.1-Gen.1.2 which is inaccurate if in fact V1(Gen.1.1) actually equals V2(Gen.1.1). So instead, we use a split on the right hand-side:

For example,
V1 defines Gen.1.1=Gen1.1!a, Gen.1.2=Gen.1.1!b
V2 defines Gen.1.1=Gen1.1!a, Gen.1.2=Gen.1.1!b
then, mapping from V1=>KJV and KJV=>V2 gives you Gen.1.1=>Gen.1.1!a=>Gen.1.1, which is now accurate. A part is a string fragment placed after the end of a key reference. We cannot use # because that is commonly known as a comment in real properties-file. Using a marker, means we can have meaningful part names if we so choose. Parts of ranges are not supported.

Note: splits should never be seen by a user. The mapping from one versification to another is abstracted such that the user can simply request the mapping between 2 verse (ranges).

Unmapped verses can be specified by inventing ids, either for whole sections, or verse by verse (this would come in handy if two versifications have the same content, but the KJV doesn't). A section must be preceded with a '?' character indicating that there will be no need to try and look up a reference. Gen.1.1=?NewPassage

Since not specifying a verse mappings means there is a 1-2-1 unchanged mapping, we need a way of specifying absent verses altogether:
?=Gen.1.1
?=Gen.1.5
means that the non-KJV book simply does not contain verses Gen.1.1 and Gen.1.5 and therefore can't be mapped.

We allow some global flags (one at present):
!zerosUnmapped : means that any mapping to or from a zero verse

TODO(CJB): think about whether when returning, we should clone, or make things immutable.

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

Field Summary
`private Passage` | `absentVerses`
`private Map<QualifiedKey,Passage>` | `fromKJVMappings`
`private boolean` | `hasErrors`
`private static Versification` | `KJV`
`private static org.slf4j.Logger` | `LOGGER`
`private Versification` | `nonKjv`
`private OsisParser` | `osisParser`
`private Map<VerseKey,List<QualifiedKey>>` | `toKJVMappings`

Constructor Summary
`VersificationToKJVMapper(Versification nonKjv, FileVersificationMapping mapping)`

Method Summary
`private void` | `add1ToManyMappings(Verse leftHand, QualifiedKey kjvHand)` A simple two way entry between 2 1-1 entries.
`private void` | `addForwardMappingFromSingleKeyToRange(Verse leftHand, QualifiedKey kjvHand)` Adds a forward mappings from left to KJV.
`private void` | `addKJVToMapping(QualifiedKey kjvVerses, Verse leftKey)` If leftKey is non-null (i.e.
`private void` | `addManyToMany(QualifiedKey leftHand, QualifiedKey kjvVerses)` Adds a many to many mapping, mappings all the verses on the left hand side to all the verses on the right hand side.
`private void` | `addMappings(QualifiedKey leftHand, QualifiedKey kjvVerses)` Adds a 1-Many mapping, by simply listing out all the properties.
`private void` | `addReverse1ToManyMappings(Verse leftHand, QualifiedKey kjvHand)` Adds the data into the reverse mappings.
`private Passage` | `createEmptyPassage(Versification versification)` Simplify creation of an empty passage object of the default type, with the required v11n.
`void` | `dump(PrintStream out)` Dump a debug representation of this map to the output stream.
`private QualifiedKey` | `getAbsentQualifiedKey(Versification versification, String versesKey)` Deals with absent markers, whether absent in the KJV or absent in the current versification.
`private QualifiedKey` | `getExistingQualifiedKey(Versification versification, String versesKey)` Deals with real keys found in the versification.
`private VerseKey` | `getNonEmptyKey(Map<QualifiedKey,Passage> mappings, QualifiedKey key)` Gets a non-empty key list, either new or the one existing in the map already.
`private
`<T,S> List<S>`
` | `getNonEmptyMappings(Map<T,List<S>> mappings, T key)` Gets a non-empty list, either new or the one existing in the map already
`private QualifiedKey` | `getOffsetQualifiedKey(Versification versification, String versesKey, VerseKey offsetBasis)` Deals with offset markers, indicating a passage is +x or -x verses from this one.
`private List<QualifiedKey>` | `getQualifiedKeys(Key leftKey)`
`private QualifiedKey` | `getRange(Versification versification, String versesKey, VerseKey offsetBasis)` Expands a reference to all its verses
`(package private) boolean` | `hasErrors()` Returns whether we initialised with errors
`List<QualifiedKey>` | `map(QualifiedKey qualifiedKey)` Maps the full qualified key to its proper equivalent in the KJV.
`private void` | `processEntry(KeyValuePair entry)`
`private void` | `processMappings(FileVersificationMapping mappings)` This is the crux of the decoding facility.
`private void` | `reportCardinalityError(VerseKey leftKeys, VerseKey kjvKeys)` If for some reason cardinalities of keys are different, we report it.
`private void` | `trace()` Outputs the mappings for debug purposes to the log file.
`VerseKey` | `unmap(QualifiedKey kjvVerse)` Converts a KJV verse to the target versification, from a qualified key, rather than a real key

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### nonKjv

    private Versification nonKjv

### absentVerses

    private Passage absentVerses

### toKJVMappings

    private Map<VerseKey,List<QualifiedKey>> toKJVMappings

### fromKJVMappings

    private Map<QualifiedKey,Passage> fromKJVMappings

### hasErrors

    private boolean hasErrors

### osisParser

    private OsisParser osisParser

### KJV

    private static final Versification KJV

### LOGGER

    private static final org.slf4j.Logger LOGGER

Constructor Detail

### VersificationToKJVMapper

    public VersificationToKJVMapper(Versification nonKjv,
                                    FileVersificationMapping mapping)

Parameters:
  `nonKjv` - a versification that is not the KJV
  `mapping` - the mappings from one versification to another

Method Detail

### processMappings

    private void processMappings(FileVersificationMapping mappings)

  This is the crux of the decoding facility. The properties are expanded.

  Parameters:
    `mappings` - the input mappings, in a contracted, short-hand form

### processEntry

    private void processEntry(KeyValuePair entry)
                       throws NoSuchKeyException

  Throws:
    `NoSuchKeyException`

### addMappings

    private void addMappings(QualifiedKey leftHand,
                             QualifiedKey kjvVerses)
                      throws NoSuchVerseException

  Adds a 1-Many mapping, by simply listing out all the properties. There is probably a better way for storing this, perhaps in a tree - but for simplicity, we're going to list them out.

  Parameters:
    `leftHand` - the left hand side operand
    `kjvVerses` - the verses that are mapped by the left hand side
  Throws:
    `NoSuchVerseException`

### addManyToMany

    private void addManyToMany(QualifiedKey leftHand,
                               QualifiedKey kjvVerses)

  Adds a many to many mapping, mappings all the verses on the left hand side to all the verses on the right hand side. We support 2 types: Many-to-1 and Many-to-Many.

  Parameters:
    `leftHand` - is assumed to be many
    `kjvVerses` - could be 1 or many

### reportCardinalityError

    private void reportCardinalityError(VerseKey leftKeys,
                                        VerseKey kjvKeys)

  If for some reason cardinalities of keys are different, we report it.

  Parameters:
    `leftKeys` - the left hand key
    `kjvKeys` - the kjv qualified key

### addKJVToMapping

    private void addKJVToMapping(QualifiedKey kjvVerses,
                                 Verse leftKey)

  If leftKey is non-null (i.e. not attached to a simple specifier, then adds to the kjvTo mappings

  Parameters:
    `kjvVerses` - the kjv verses
    `leftKey` - the left-hand key, possibly null.

### add1ToManyMappings

    private void add1ToManyMappings(Verse leftHand,
                                    QualifiedKey kjvHand)
                             throws NoSuchVerseException

  A simple two way entry between 2 1-1 entries.

  Parameters:
    `leftHand` - the verse on the left side, left is assumed to be 1 verse only
    `kjvHand` - the KJV reference
  Throws:
    `NoSuchVerseException`

### addReverse1ToManyMappings

    private void addReverse1ToManyMappings(Verse leftHand,
                                           QualifiedKey kjvHand)

  Adds the data into the reverse mappings. Caters for 1-2-1 and 1-2-Many mappings

  Parameters:
    `leftHand` - the reference of the left hand reference
    `kjvHand` - the kjv reference/key, qualified with the part

### addForwardMappingFromSingleKeyToRange

    private void addForwardMappingFromSingleKeyToRange(Verse leftHand,
                                                       QualifiedKey kjvHand)

  Adds a forward mappings from left to KJV.

  Parameters:
    `leftHand` - the left hand reference (corresponding to a non-kjv versification)
    `kjvHand` - the kjv reference (with part if applicable).

### getNonEmptyKey

    private VerseKey getNonEmptyKey(Map<QualifiedKey,Passage> mappings,
                                    QualifiedKey key)

  Gets a non-empty key list, either new or the one existing in the map already.

  Parameters:
    `mappings` - the map from key to list of values
    `key` - the key
  Returns:
    the non-empty mappings list

### getNonEmptyMappings

    private <T,S> List<S> getNonEmptyMappings(Map<T,List<S>> mappings,
                                              T key)

  Gets a non-empty list, either new or the one existing in the map already

  Type Parameters:
    `T` - the type of the key
    `S` - the type of the value
  Parameters:
    `mappings` - the map from key to list of values
    `key` - the key
  Returns:
    the separate list of verses

### getRange

    private QualifiedKey getRange(Versification versification,
                                  String versesKey,
                                  VerseKey offsetBasis)
                           throws NoSuchKeyException

  Expands a reference to all its verses

  Parameters:
    `versesKey` - the verses
  Returns:
    the separate list of verses
  Throws:
    `NoSuchKeyException`

### getOffsetQualifiedKey

    private QualifiedKey getOffsetQualifiedKey(Versification versification,
                                               String versesKey,
                                               VerseKey offsetBasis)
                                        throws NoSuchKeyException

  Deals with offset markers, indicating a passage is +x or -x verses from this one.

  Parameters:
    `versification` - the versification of the passed in key
    `versesKey` - the text of the reference we are trying to parse
  Returns:
    the qualified key representing this
  Throws:
    `NoSuchKeyException`

### getExistingQualifiedKey

    private QualifiedKey getExistingQualifiedKey(Versification versification,
                                                 String versesKey)

  Deals with real keys found in the versification.

  Parameters:
    `versification` - the versification of the passed in key
    `versesKey` - the text of the reference we are trying to parse
  Returns:
    the qualified key representing this

### getAbsentQualifiedKey

    private QualifiedKey getAbsentQualifiedKey(Versification versification,
                                               String versesKey)

  Deals with absent markers, whether absent in the KJV or absent in the current versification.

  Parameters:
    `versification` - the versification of the passed in key
    `versesKey` - the text of the reference we are trying to parse
  Returns:
    the qualified key representing this

### getQualifiedKeys

    private List<QualifiedKey> getQualifiedKeys(Key leftKey)

  Returns:
    the qualified keys associated with the input key.

### map

    public List<QualifiedKey> map(QualifiedKey qualifiedKey)

  Maps the full qualified key to its proper equivalent in the KJV.

  Parameters:
    `qualifiedKey` - the qualified key
  Returns:
    the list of matching qualified keys in the KJV versification.

### unmap

    public VerseKey unmap(QualifiedKey kjvVerse)

  Converts a KJV verse to the target versification, from a qualified key, rather than a real key

  Parameters:
    `kjvVerse` - the verse from the KJV
  Returns:
    the key in the left-hand versification

### trace

    private void trace()

  Outputs the mappings for debug purposes to the log file.

### dump

    public void dump(PrintStream out)

  Dump a debug representation of this map to the output stream.

  Parameters:
    `out` -

### hasErrors

    boolean hasErrors()

  Returns whether we initialised with errors

### createEmptyPassage

    private Passage createEmptyPassage(Versification versification)

  Simplify creation of an empty passage object of the default type, with the required v11n.

  Parameters:
    `versification` - required v11n for new Passage
  Returns:
    empty Passage

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Copyright ¨ 2003-2015
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD