| Key.java |
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