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, 2005 - 2016
18   *
19   */
20  package org.crosswire.jsword.passage;
21  
22  import java.io.Serializable;
23  
24  /**
25   * A Key is a Key that can contain other Keys.
26   * 
27   * The interface is modeled on the java.util.Set interface customized because
28   * KeyLists can only store other Keys and simplified by making add() and
29   * remove() return void and not a boolean.
30   * 
31   * @see gnu.lgpl.License The GNU Lesser General Public License for details.
32   * @author Joe Walker
33   */
34  public interface Key extends Comparable<Key>, Iterable<Key>, Cloneable, Serializable {
35      /**
36       * A Human readable version of the Key. For Biblical passages this uses
37       * short books names, and the shortest sensible rendering, for example
38       * "Mat 3:1-4" and "Mar 1:1, 3, 5" and "3Jo, Jude"
39       * 
40       * @return a String containing a description of the Key
41       */
42      String getName();
43  
44      /**
45       * Translate the Key into a human readable string, with the assumption that
46       * the specified Key has just been output, so if we are in the same region,
47       * we do not need to display the region name, and so on.
48       * 
49       * @param base
50       *            The key to use to cut down unnecessary output.
51       * @return The string representation
52       */
53      String getName(Key base);
54  
55      /**
56       * A Human readable version of the Key's top level name. For Biblical
57       * passages this uses short books names. For a dictionary it might return
58       * A-Z.
59       * 
60       * @return a String containing a description of the Key
61       */
62      String getRootName();
63  
64      /**
65       * The OSIS defined reference specification for this Key. When the key is a
66       * single element, it is an OSIS book name with '.' separating the parts.
67       * When the key is multiple elements, it uses a range notation. Note, this
68       * will create a comma separated list of ranges, which is improper OSIS.
69       * 
70       * @return a String containing the OSIS description of the verses
71       */
72      String getOsisRef();
73  
74      /**
75       * The OSIS defined id specification for this Key. When the key is a single
76       * element, it is an OSIS book name with '.' separating the parts. When the
77       * key is multiple elements, it uses a space to separate each.
78       * 
79       * @return a String containing the OSIS description of the verses
80       */
81      String getOsisID();
82  
83      /**
84       * All keys have parents unless they are the root of a Key.
85       * 
86       * @return The parent of this tree, or null if this Key is the root.
87       */
88      Key getParent();
89  
90      /**
91       * Returns false if the receiver is a leaf node and can not have children.
92       * Any attempt to add()/remove() will throw
93       * 
94       * @return true if the key can have children
95       */
96      boolean canHaveChildren();
97  
98      /**
99       * Returns the number of children that this node has. Leaf nodes return 0.
100      * 
101      * @return the number of children for the node
102      */
103     int getChildCount();
104 
105     /**
106      * Returns the number of elements in this set (its cardinality). If this set
107      * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
108      * <tt>Integer.MAX_VALUE</tt>.
109      * <p>
110      * This method is potentially expensive, as it often requires cycling through all the keys in the set.</p>
111      * @return the number of elements in this set (its cardinality).
112      */
113     int getCardinality();
114 
115     /**
116      * Does this Key have 0 members
117      * 
118      * @return <tt>true</tt> if this set contains no elements.
119      */
120     boolean isEmpty();
121 
122     /**
123      * Returns <tt>true</tt> if this set contains the specified element.
124      * 
125      * @param key
126      *            element whose presence in this set is to be tested.
127      * @return <tt>true</tt> if this set contains the specified element.
128      */
129     boolean contains(Key key);
130 
131     /**
132      * Adds the specified element to this set if it is not already present.
133      * 
134      * @param key
135      *            element to be added to this set.
136      * @throws NullPointerException
137      *             if the specified element is null
138      */
139     void addAll(Key key);
140 
141     /**
142      * Removes the specified elements from this set if it is present.
143      * 
144      * @param key
145      *            object to be removed from this set, if present.
146      * @throws NullPointerException
147      *             if the specified element is null
148      */
149     void removeAll(Key key);
150 
151     /**
152      * Removes all but the specified element from this set.
153      * 
154      * @param key
155      *            object to be left in this set.
156      * @throws NullPointerException
157      *             if the specified element is null
158      */
159     void retainAll(Key key);
160 
161     /**
162      * Removes all of the elements from this set (optional operation). This set
163      * will be empty after this call returns (unless it throws an exception).
164      */
165     void clear();
166 
167     /**
168      * Gets a key from a specific point in this list of children.
169      * 
170      * @param index
171      *            The index of the Key to retrieve
172      * @return The specified key
173      * @throws IndexOutOfBoundsException
174      */
175     Key get(int index);
176 
177     /**
178      * Reverse a Key into the position the key holds in the list of children
179      * 
180      * @param that
181      *            The Key to find
182      * @return The index of the key or &lt; 0 if the key is not in the list
183      */
184     int indexOf(Key that);
185 
186     /**
187      * Widen the range of the verses/keys in this list. This is primarily for
188      * "find x within n verses of y" type applications.
189      * 
190      * @param by
191      *            The number of verses/keys to widen by
192      * @param restrict
193      *            How should we restrict the blurring?
194      * @see Passage
195      */
196     void blur(int by, RestrictionType restrict);
197 
198     /**
199      * This needs to be declared here so that it is visible as a method on a
200      * derived Key.
201      * 
202      * @return A complete copy of ourselves
203      */
204     Key clone();
205 
206     /**
207      * This needs to be declared here so that it is visible as a method on a
208      * derived Key.
209      * 
210      * @param obj 
211      * @return true if equal
212      */
213     boolean equals(Object obj);
214 
215     /**
216      * This needs to be declared here so that it is visible as a method on a
217      * derived Key.
218      * 
219      * @return the hashcode
220      */
221     int hashCode();
222 }
223