1   /**
2    * Distribution License:
3    * JSword is free software; you can redistribute it and/or modify it under
4    * the terms of the GNU Lesser General Public License, version 2.1 or later
5    * as published by the Free Software Foundation. This program is distributed
6    * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
7    * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
8    * See the GNU Lesser General Public License for more details.
9    *
10   * The License is available on the internet at:
11   *      http://www.gnu.org/copyleft/lgpl.html
12   * or by writing to:
13   *      Free Software Foundation, Inc.
14   *      59 Temple Place - Suite 330
15   *      Boston, MA 02111-1307, USA
16   *
17   * © CrossWire Bible Society, 2013 - 2016
18   *
19   */
20  package org.crosswire.jsword.passage;
21  
22  import org.crosswire.jsword.versification.Versification;
23  
24  /**
25   * A VerseKey indicates that a Key has a Versification reference system.
26   * 
27   * @param <T> The type of VerseKey that reversify returns.
28   *
29   * @see gnu.lgpl.License The GNU Lesser General Public License for details.
30   * @author DM Smith
31   */
32  public interface VerseKey<T extends VerseKey> extends Key {
33      /**
34       * Get the Versification that defines the Verses in this VerseKey.
35       * 
36       * @return this VerseKey Versification.
37       */
38      Versification getVersification();
39  
40      /**
41       * Cast this VerseKey into another Versification. OSIS Sub Identifiers are ignored.
42       * 
43       * <p>
44       * Note: This is dangerous as it does not consider chapter boundaries
45       * or whether the verses in this VerseKey are actually part of the
46       * new versification. It should only be used when the start and end
47       * verses are in both Versifications. You have been warned.
48       * </p>
49       * 
50       * @param newVersification 
51       * @return this VerseKey Versification.
52       */
53      T reversify(Versification newVersification);
54  
55      /**
56       * A VerseKey that does not have an OSIS sub identifier is a whole reference.
57       * 
58       * @return whether this is a whole reference
59       */
60       boolean isWhole();
61  
62      /**
63       * Convert this reference into one without a sub-identifier.
64       * A Verse with an OSIS sub-identifier represents part of a reference.
65       * 
66       * @return a whole reference
67       */
68       T getWhole();
69  
70  }
71