KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sapia > util > cursor > Cursor


1 package org.sapia.util.cursor;
2
3 /**
4  * This class specifies cursor behavior. A <code>Cursor</code> is a sequence
5  * of <code>Batch</code> instances. A cursor instance creates batches through
6  * a <code>CursorFeed</code>.
7  *
8  * @see org.sapia.util.cursor.Batch
9  * @see org.sapia.util.cursor.CursorFeed
10  * @see org.sapia.util.cursor.CursorFactory
11  *
12  * @author Yanick Duchesne
13  *
14  * <dl>
15  * <dt><b>Copyright: </b>
16  * <dd>Copyright &#169; 2002-2004 <a HREF="http://www.sapia-oss.org">Sapia Open
17  * Source Software </a>. All Rights Reserved.</dd>
18  * </dt>
19  * <dt><b>License: </b>
20  * <dd>Read the license.txt file of the jar or visit the <a
21  * HREF="http://www.sapia-oss.org/license.html">license page </a> at the Sapia
22  * OSS web site</dd>
23  * </dt>
24  * </dl>
25  */
26 public interface Cursor {
27
28   /**
29    * Returns the number of items in this cursor. Note that the returned count
30    * should not be necessarily relied upon: a cursor might be fed
31    * asynchronously, and thus the number of items may not be constant over time,
32    * up to a certain limit.
33    *
34    * @return the number of items in this cursor (more precisely: the sum of the
35    * number of items that all batches in this instance hold).
36    */
37   public int getItemCount();
38
39   /**
40    * @return the number of <code>Batch</code> instances held with this
41    * instance.
42    * @see #getItemCount()
43    */
44   public int getBatchCount();
45
46   /**
47    * Returns the "current" batch (or, rather, the last batch that was fetched).
48    *
49    * @return the <code>Batch</code> that is currently pointed to.
50    */
51   public Batch getCurrentBatch();
52
53   /**
54    * @return <code>true</code> if this instance has a batch pending.
55    */
56   public boolean hasNextBatch();
57
58   /**
59    * @return the next <code>Batch</code>
60    */
61   public Batch nextBatch();
62
63   /**
64    * @return <code>true</code> if this instance has a "previous" batch
65    * pending.
66    */
67   public boolean hasPreviousBatch();
68
69   /**
70    * @return the previous <code>Batch</code>
71    */
72   public Batch previousBatch();
73
74   /**
75    * @return the batch size with which this instance was configured.
76    */
77   public int getBatchSize();
78
79   /**
80    * Positions this instance at the beginning of the first batch.
81    *
82    * @return this instance.
83    */
84   public Cursor toFirst();
85
86   /**
87    * Position this instance at the beginning of the last batch.
88    *
89    * @return this instance.
90    */
91   public Cursor toLast();
92
93   /**
94    * This non-blocking method can be polled to inquire about the number of
95    * pending objects in this instance's underlying <code>CursorFeed</code>.
96    * <p>
97    * This method can be used in cases where an <code>hasNext()</code> call has
98    * returned false, and where the underlying feed is asynchronously filled with
99    * data. In such cases, the false <code>hasNext()</code> call may reflect a
100    * temporary situation. This method conveniently allows insuring that indeed
101    * no data is pending.
102    *
103    * @return the number of pending object in the underlying feed.
104    *
105    * @see CursorFeed#available()
106    */
107   public int available();
108   
109   /**
110    * Client applications should call this method when they are finished with this
111    * instance. This allows all resources to be released. In particular, this allows
112    * sparing processing resources in cases where <code>CursorFeed</code>s have an
113    * asynchronous behavior.
114    *
115    * @see CursorFeed#close()
116    */
117   public void close();
118
119 }
120
Popular Tags