Coverage Report

Coverage Report - org.crosswire.jsword.passage.Key

Classes in this File

 /**
  * Distribution License:
  * JSword is free software; you can redistribute it and/or modify it under
  * the terms of the GNU Lesser General Public License, version 2.1 or later
  * as published by the Free Software Foundation. This program is distributed
  * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  * See the GNU Lesser General Public License for more details.
  *
  * The License is available on the internet at:
  *      http://www.gnu.org/copyleft/lgpl.html
  * or by writing to:
  *      Free Software Foundation, Inc.
  *      59 Temple Place - Suite 330
  *      Boston, MA 02111-1307, USA
  *
  * © CrossWire Bible Society, 2005 - 2016
  *
  */
 package org.crosswire.jsword.passage;
 
 import java.io.Serializable;
 
 /**
  * A Key is a Key that can contain other Keys.
  * 
  * The interface is modeled on the java.util.Set interface customized because
  * KeyLists can only store other Keys and simplified by making add() and
  * remove() return void and not a boolean.
  * 
  * @see gnu.lgpl.License The GNU Lesser General Public License for details.
  * @author Joe Walker
  */
 public interface Key extends Comparable<Key>, Iterable<Key>, Cloneable, Serializable {
     /**
      * A Human readable version of the Key. For Biblical passages this uses
      * short books names, and the shortest sensible rendering, for example
      * "Mat 3:1-4" and "Mar 1:1, 3, 5" and "3Jo, Jude"
      * 
      * @return a String containing a description of the Key
      */
     String getName();
 
     /**
      * Translate the Key into a human readable string, with the assumption that
      * the specified Key has just been output, so if we are in the same region,
      * we do not need to display the region name, and so on.
      * 
      * @param base
      *            The key to use to cut down unnecessary output.
      * @return The string representation
      */
     String getName(Key base);
 
     /**
      * A Human readable version of the Key's top level name. For Biblical
      * passages this uses short books names. For a dictionary it might return
      * A-Z.
      * 
      * @return a String containing a description of the Key
      */
     String getRootName();
 
     /**
      * The OSIS defined reference specification for this Key. When the key is a
      * single element, it is an OSIS book name with '.' separating the parts.
      * When the key is multiple elements, it uses a range notation. Note, this
      * will create a comma separated list of ranges, which is improper OSIS.
      * 
      * @return a String containing the OSIS description of the verses
      */
     String getOsisRef();
 
     /**
      * The OSIS defined id specification for this Key. When the key is a single
      * element, it is an OSIS book name with '.' separating the parts. When the
      * key is multiple elements, it uses a space to separate each.
      * 
      * @return a String containing the OSIS description of the verses
      */
     String getOsisID();
 
     /**
      * All keys have parents unless they are the root of a Key.
      * 
      * @return The parent of this tree, or null if this Key is the root.
      */
     Key getParent();
 
     /**
      * Returns false if the receiver is a leaf node and can not have children.
      * Any attempt to add()/remove() will throw
      * 
      * @return true if the key can have children
      */
     boolean canHaveChildren();
 
     /**
      * Returns the number of children that this node has. Leaf nodes return 0.
      * 
      * @return the number of children for the node
      */
     int getChildCount();
 
     /**
      * Returns the number of elements in this set (its cardinality). If this set
      * contains more than <tt>Integer.MAX_VALUE</tt> elements, returns
      * <tt>Integer.MAX_VALUE</tt>.
      * <p>
      * This method is potentially expensive, as it often requires cycling through all the keys in the set.</p>
      * @return the number of elements in this set (its cardinality).
      */
     int getCardinality();
 
     /**
      * Does this Key have 0 members
      * 
      * @return <tt>true</tt> if this set contains no elements.
      */
     boolean isEmpty();
 
     /**
      * Returns <tt>true</tt> if this set contains the specified element.
      * 
      * @param key
      *            element whose presence in this set is to be tested.
      * @return <tt>true</tt> if this set contains the specified element.
      */
     boolean contains(Key key);
 
     /**
      * Adds the specified element to this set if it is not already present.
      * 
      * @param key
      *            element to be added to this set.
      * @throws NullPointerException
      *             if the specified element is null
      */
     void addAll(Key key);
 
     /**
      * Removes the specified elements from this set if it is present.
      * 
      * @param key
      *            object to be removed from this set, if present.
      * @throws NullPointerException
      *             if the specified element is null
      */
     void removeAll(Key key);
 
     /**
      * Removes all but the specified element from this set.
      * 
      * @param key
      *            object to be left in this set.
      * @throws NullPointerException
      *             if the specified element is null
      */
     void retainAll(Key key);
 
     /**
      * Removes all of the elements from this set (optional operation). This set
      * will be empty after this call returns (unless it throws an exception).
      */
     void clear();
 
     /**
      * Gets a key from a specific point in this list of children.
      * 
      * @param index
      *            The index of the Key to retrieve
      * @return The specified key
      * @throws IndexOutOfBoundsException
      */
     Key get(int index);
 
     /**
      * Reverse a Key into the position the key holds in the list of children
      * 
      * @param that
      *            The Key to find
      * @return The index of the key or &lt; 0 if the key is not in the list
      */
     int indexOf(Key that);
 
     /**
      * Widen the range of the verses/keys in this list. This is primarily for
      * "find x within n verses of y" type applications.
      * 
      * @param by
      *            The number of verses/keys to widen by
      * @param restrict
      *            How should we restrict the blurring?
      * @see Passage
      */
     void blur(int by, RestrictionType restrict);
 
     /**
      * This needs to be declared here so that it is visible as a method on a
      * derived Key.
      * 
      * @return A complete copy of ourselves
      */
     Key clone();
 
     /**
      * This needs to be declared here so that it is visible as a method on a
      * derived Key.
      * 
      * @param obj 
      * @return true if equal
      */
     boolean equals(Object obj);
 
     /**
      * This needs to be declared here so that it is visible as a method on a
      * derived Key.
      * 
      * @return the hashcode
      */
     int hashCode();
 }

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		}