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 * © 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 < 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