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