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