Coverage Report

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

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.IOException;
 import java.io.Reader;
 import java.io.Writer;
 import java.util.Iterator;
 
 /**
  * A Passage is a specialized Collection of Verses. The additions are:
  * <ul>
  * <li>List blurring
  * <li>Range Counting and iteration (in addition to Verse counting etc)
  * <li>List change notification, so you can register to update yourself, and
  * this goes hand in hand with a added thread-safe contract.
  * <li>getName() to be more VerseBase like.
  * <li>Human readable serialization. So we can read and write to and from OLB
  * style Passage files.
  * </ul>
  * 
  * <p>
  * Passage no longer extends the Collection interface to avoid J2SE 1.1/1.2
  * portability problems, and because many of the things that a Passage does rely
  * on consecutive Verses which are an alien concept to Collections. So users
  * would have to use the Passage interface anyway.
  * 
  * <p>
  * Other arguments for and against.
  * <ul>
  * <li>The generic version will postpone some type errors to runtime. Is this a
  * huge problem? Are there many syntax errors that would be lost? Probably not.
  * <li>The specific version would stop enhancements like add("Gen 1:1"); (But
  * this is just syntactical sugar anyway).
  * <li>The specific version allows functionality by is-a as well as has-a. But a
  * Passage is fundamentally different so this is not that much use.
  * <li>At the end of the day I expect people to use getName() instead of
  * toString() and blur(), both of which are Passage things not Collection
  * things. So the general use of these classes is via a Passage interface not a
  * Collections one.
  * <li>Note that the implementations of Passage could not adhere strictly to the
  * Collections interface in returning false from add(), remove() etc, to specify
  * if the Collection was changed. Given ranges and the like this can get very
  * time consuming and complex.
  * </ul>
  * 
  * <p>
  * The upshot of all this is that I am removing the Collections interface from
  * Passage.
  * 
  * <p>
  * I considered giving Passages names to allow for a CLI that could use named
  * RangedPassages, however that is perhaps better left to another class.
  * 
  * @see gnu.lgpl.License The GNU Lesser General Public License for details.
  * @author Joe Walker
  */
 public interface Passage extends VerseKey<Passage> {
     /**
      * A summary of the verses in this Passage For example
      * "10 verses in 4 books"
      * 
      * @return a String containing an overview of the verses
      */
     String getOverview();
 
     /**
      * Returns the number of verses in this collection. Like Collection.size()
      * This does not mean the Passage needs to use Verses, just that it
      * understands the concept.
      * 
      * @return the number of Verses in this collection
      * @see Verse
      */
     int countVerses();
 
     /**
      * Determine whether there are two or more ranges.
      * 
      * @param restrict
      *            Do we break ranges at chapter/book boundaries
      * @return whether there are two or more ranges
      * @see VerseRange
      */
     boolean hasRanges(RestrictionType restrict);
 
     /**
      * Like countVerses() that counts VerseRanges instead of Verses Returns the
      * number of fragments in this collection. This does not mean the Passage
      * needs to use VerseRanges, just that it understands the concept.
      * 
      * @param restrict
      *            Do we break ranges at chapter/book boundaries
      * @return the number of VerseRanges in this collection
      * @see VerseRange
      */
     int countRanges(RestrictionType restrict);
 
     /**
      * Ensures that there are a maximum of <code>count</code> Verses in this
      * Passage. If there were more than <code>count</code> Verses then a new
      * Passage is created containing the Verses from <code>count</code>+1
      * onwards. If there was not greater than <code>count</code> in the Passage,
      * then the passage remains unchanged, and null is returned.
      * 
      * @param count
      *            The maximum number of Verses to allow in this collection
      * @return A new Passage containing the remaining verses or null
      * @see Verse
      */
     Passage trimVerses(int count);
 
     /**
      * Ensures that there are a maximum of <code>count</code> VerseRanges in
      * this Passage. If there were more than <code>count</code> VerseRanges then
      * a new Passage is created containing the VerseRanges from
      * <code>count</code>+1 onwards. If there was not greater than
      * <code>count</code> in the Passage, then the passage remains unchanged,
      * and null is returned.
      * 
      * @param count
      *            The maximum number of VerseRanges to allow in this collection
      * @param restrict
      *            Do we break ranges at chapter/book boundaries
      * @return A new Passage containing the remaining verses or null
      * @see VerseRange
      */
     Passage trimRanges(int count, RestrictionType restrict);
 
     /**
      * How many books are there in this Passage
      * 
      * @return The number of distinct books
      */
     int booksInPassage();
 
     /**
      * Get a specific Verse from this collection
      * 
      * @param offset
      *            The verse offset (legal values are 0 to countVerses()-1)
      * @return The Verse
      * @throws ArrayIndexOutOfBoundsException
      *             If the offset is out of range
      */
     Verse getVerseAt(int offset) throws ArrayIndexOutOfBoundsException;
 
     /**
      * Get a specific VerseRange from this collection
      * 
      * @param offset
      *            The verse range offset (legal values are 0 to countRanges()-1)
      * @param restrict
      *            Do we break ranges at chapter/book boundaries
      * @return The Verse Range
      * @throws ArrayIndexOutOfBoundsException
      *             If the offset is out of range
      */
     VerseRange getRangeAt(int offset, RestrictionType restrict) throws ArrayIndexOutOfBoundsException;
 
     /**
      * Like iterator() that iterates over VerseRanges instead of Verses.
      * Exactly the same data will be traversed, however using rangeIterator()
      * will usually give fewer iterations (and never more)
      * 
      * @param restrict
      *            Do we break ranges over chapters
      * @return A list enumerator
      */
     Iterator<VerseRange> rangeIterator(RestrictionType restrict);
 
     /**
      * Returns true if this collection contains all the specified Verse
      * 
      * @param that
      *            Verse or VerseRange that may exist in this Passage
      * @return true if this collection contains that
      */
     boolean contains(Key that);
 
     /**
      * Add this Verse/VerseRange to this Passage
      * 
      * @param that
      *            The Verses to be added from this Passage
      */
     void add(Key that);
 
     /**
      * Remove this Verse/VerseRange from this Passage
      * 
      * @param that
      *            The Verses to be removed from this Passage
      */
     void remove(Key that);
 
     /**
      * Returns true if this Passage contains all of the verses in that Passage
      * 
      * @param that
      *            Passage to be checked for containment in this collection.
      * @return true if this reference contains all of the Verses in that Passage
      */
     boolean containsAll(Passage that);
 
     /**
      * To be compatible with humans we read/write ourselves to a file that a
      * human can read and even edit. OLB verse.lst integration is a good goal
      * here.
      * 
      * @param in
      *            The stream to read from
      * @exception java.io.IOException
      *                If the file/network etc breaks
      * @exception NoSuchVerseException
      *                If the file was invalid
      */
     void readDescription(Reader in) throws IOException, NoSuchVerseException;
 
     /**
      * To be compatible with humans we read/write ourselves to a file that a
      * human can read and even edit. OLB verse.lst integration is a good goal
      * here.
      * 
      * @param out
      *            The stream to write to
      * @exception java.io.IOException
      *                If the file/network etc breaks
      */
     void writeDescription(Writer out) throws IOException;
 
     /**
      * For performance reasons we may well want to hint to the Passage that we
      * have done editing it for now and that it is safe to cache certain values
      * to speed up future reads. Any action taken by this method will be undone
      * simply by making a future edit, and the only loss in calling
      * optimizeReads() is a loss of time if you then persist in writing to the
      * Passage.
      */
     void optimizeReads();
 
     /**
      * Event Listeners - Add Listener
      * 
      * @param li
      *            The listener to add
      */
     void addPassageListener(PassageListener li);
 
     /**
      * Event Listeners - Remove Listener
      * 
      * @param li
      *            The listener to remove
      */
     void removePassageListener(PassageListener li);
 }

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.IOException;
23		import java.io.Reader;
24		import java.io.Writer;
25		import java.util.Iterator;
26
27		/**
28		* A Passage is a specialized Collection of Verses. The additions are:
29		* <ul>
30		* <li>List blurring
31		* <li>Range Counting and iteration (in addition to Verse counting etc)
32		* <li>List change notification, so you can register to update yourself, and
33		* this goes hand in hand with a added thread-safe contract.
34		* <li>getName() to be more VerseBase like.
35		* <li>Human readable serialization. So we can read and write to and from OLB
36		* style Passage files.
37		* </ul>
38		*
39		* <p>
40		* Passage no longer extends the Collection interface to avoid J2SE 1.1/1.2
41		* portability problems, and because many of the things that a Passage does rely
42		* on consecutive Verses which are an alien concept to Collections. So users
43		* would have to use the Passage interface anyway.
44		*
45		* <p>
46		* Other arguments for and against.
47		* <ul>
48		* <li>The generic version will postpone some type errors to runtime. Is this a
49		* huge problem? Are there many syntax errors that would be lost? Probably not.
50		* <li>The specific version would stop enhancements like add("Gen 1:1"); (But
51		* this is just syntactical sugar anyway).
52		* <li>The specific version allows functionality by is-a as well as has-a. But a
53		* Passage is fundamentally different so this is not that much use.
54		* <li>At the end of the day I expect people to use getName() instead of
55		* toString() and blur(), both of which are Passage things not Collection
56		* things. So the general use of these classes is via a Passage interface not a
57		* Collections one.
58		* <li>Note that the implementations of Passage could not adhere strictly to the
59		* Collections interface in returning false from add(), remove() etc, to specify
60		* if the Collection was changed. Given ranges and the like this can get very
61		* time consuming and complex.
62		* </ul>
63		*
64		* <p>
65		* The upshot of all this is that I am removing the Collections interface from
66		* Passage.
67		*
68		* <p>
69		* I considered giving Passages names to allow for a CLI that could use named
70		* RangedPassages, however that is perhaps better left to another class.
71		*
72		* @see gnu.lgpl.License The GNU Lesser General Public License for details.
73		* @author Joe Walker
74		*/
75		public interface Passage extends VerseKey<Passage> {
76		/**
77		* A summary of the verses in this Passage For example
78		* "10 verses in 4 books"
79		*
80		* @return a String containing an overview of the verses
81		*/
82		String getOverview();
83
84		/**
85		* Returns the number of verses in this collection. Like Collection.size()
86		* This does not mean the Passage needs to use Verses, just that it
87		* understands the concept.
88		*
89		* @return the number of Verses in this collection
90		* @see Verse
91		*/
92		int countVerses();
93
94		/**
95		* Determine whether there are two or more ranges.
96		*
97		* @param restrict
98		* Do we break ranges at chapter/book boundaries
99		* @return whether there are two or more ranges
100		* @see VerseRange
101		*/
102		boolean hasRanges(RestrictionType restrict);
103
104		/**
105		* Like countVerses() that counts VerseRanges instead of Verses Returns the
106		* number of fragments in this collection. This does not mean the Passage
107		* needs to use VerseRanges, just that it understands the concept.
108		*
109		* @param restrict
110		* Do we break ranges at chapter/book boundaries
111		* @return the number of VerseRanges in this collection
112		* @see VerseRange
113		*/
114		int countRanges(RestrictionType restrict);
115
116		/**
117		* Ensures that there are a maximum of <code>count</code> Verses in this
118		* Passage. If there were more than <code>count</code> Verses then a new
119		* Passage is created containing the Verses from <code>count</code>+1
120		* onwards. If there was not greater than <code>count</code> in the Passage,
121		* then the passage remains unchanged, and null is returned.
122		*
123		* @param count
124		* The maximum number of Verses to allow in this collection
125		* @return A new Passage containing the remaining verses or null
126		* @see Verse
127		*/
128		Passage trimVerses(int count);
129
130		/**
131		* Ensures that there are a maximum of <code>count</code> VerseRanges in
132		* this Passage. If there were more than <code>count</code> VerseRanges then
133		* a new Passage is created containing the VerseRanges from
134		* <code>count</code>+1 onwards. If there was not greater than
135		* <code>count</code> in the Passage, then the passage remains unchanged,
136		* and null is returned.
137		*
138		* @param count
139		* The maximum number of VerseRanges to allow in this collection
140		* @param restrict
141		* Do we break ranges at chapter/book boundaries
142		* @return A new Passage containing the remaining verses or null
143		* @see VerseRange
144		*/
145		Passage trimRanges(int count, RestrictionType restrict);
146
147		/**
148		* How many books are there in this Passage
149		*
150		* @return The number of distinct books
151		*/
152		int booksInPassage();
153
154		/**
155		* Get a specific Verse from this collection
156		*
157		* @param offset
158		* The verse offset (legal values are 0 to countVerses()-1)
159		* @return The Verse
160		* @throws ArrayIndexOutOfBoundsException
161		* If the offset is out of range
162		*/
163		Verse getVerseAt(int offset) throws ArrayIndexOutOfBoundsException;
164
165		/**
166		* Get a specific VerseRange from this collection
167		*
168		* @param offset
169		* The verse range offset (legal values are 0 to countRanges()-1)
170		* @param restrict
171		* Do we break ranges at chapter/book boundaries
172		* @return The Verse Range
173		* @throws ArrayIndexOutOfBoundsException
174		* If the offset is out of range
175		*/
176		VerseRange getRangeAt(int offset, RestrictionType restrict) throws ArrayIndexOutOfBoundsException;
177
178		/**
179		* Like iterator() that iterates over VerseRanges instead of Verses.
180		* Exactly the same data will be traversed, however using rangeIterator()
181		* will usually give fewer iterations (and never more)
182		*
183		* @param restrict
184		* Do we break ranges over chapters
185		* @return A list enumerator
186		*/
187		Iterator<VerseRange> rangeIterator(RestrictionType restrict);
188
189		/**
190		* Returns true if this collection contains all the specified Verse
191		*
192		* @param that
193		* Verse or VerseRange that may exist in this Passage
194		* @return true if this collection contains that
195		*/
196		boolean contains(Key that);
197
198		/**
199		* Add this Verse/VerseRange to this Passage
200		*
201		* @param that
202		* The Verses to be added from this Passage
203		*/
204		void add(Key that);
205
206		/**
207		* Remove this Verse/VerseRange from this Passage
208		*
209		* @param that
210		* The Verses to be removed from this Passage
211		*/
212		void remove(Key that);
213
214		/**
215		* Returns true if this Passage contains all of the verses in that Passage
216		*
217		* @param that
218		* Passage to be checked for containment in this collection.
219		* @return true if this reference contains all of the Verses in that Passage
220		*/
221		boolean containsAll(Passage that);
222
223		/**
224		* To be compatible with humans we read/write ourselves to a file that a
225		* human can read and even edit. OLB verse.lst integration is a good goal
226		* here.
227		*
228		* @param in
229		* The stream to read from
230		* @exception java.io.IOException
231		* If the file/network etc breaks
232		* @exception NoSuchVerseException
233		* If the file was invalid
234		*/
235		void readDescription(Reader in) throws IOException, NoSuchVerseException;
236
237		/**
238		* To be compatible with humans we read/write ourselves to a file that a
239		* human can read and even edit. OLB verse.lst integration is a good goal
240		* here.
241		*
242		* @param out
243		* The stream to write to
244		* @exception java.io.IOException
245		* If the file/network etc breaks
246		*/
247		void writeDescription(Writer out) throws IOException;
248
249		/**
250		* For performance reasons we may well want to hint to the Passage that we
251		* have done editing it for now and that it is safe to cache certain values
252		* to speed up future reads. Any action taken by this method will be undone
253		* simply by making a future edit, and the only loss in calling
254		* optimizeReads() is a loss of time if you then persist in writing to the
255		* Passage.
256		*/
257		void optimizeReads();
258
259		/**
260		* Event Listeners - Add Listener
261		*
262		* @param li
263		* The listener to add
264		*/
265		void addPassageListener(PassageListener li);
266
267		/**
268		* Event Listeners - Remove Listener
269		*
270		* @param li
271		* The listener to remove
272		*/
273		void removePassageListener(PassageListener li);
274		}