01: /*
02: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
03: */
04: package javax.jcr;
05:
06: import java.util.Iterator;
07:
08: /**
09: * Extends <code>Iterator</code> with the <code>skip</code>, <code>getSize</code>
10: * and <code>getPosition</code> methods. The base interface of all type-specific
11: * iterators in the <code>javax.jcr</code> and its subpackages.
12: */
13: public interface RangeIterator extends Iterator {
14:
15: /**
16: * Skip a number of elements in the iterator.
17: *
18: * @param skipNum the non-negative number of elements to skip
19: * @throws java.util.NoSuchElementException
20: * if skipped past the last element in the iterator.
21: */
22: public void skip(long skipNum);
23:
24: /**
25: * Returns the total number of of items available through this iterator.
26: * For example, for some node <code>N</code>, <code>N.getNodes().getSize()</code>
27: * returns the number of child nodes of <code>N</code> visible through the
28: * current <code>Session</code>. In some implementations precise information
29: * about the number of elements may not be available. In such cases this
30: * method must return -1. API clients will then be able to use
31: * <code>RangeIterator.getNumberRemaining</code> to get an estimate on the
32: * number of elements.
33: *
34: * @return a long
35: */
36: public long getSize();
37:
38: /**
39: * Returns the current position within the iterator. The number
40: * returned is the 0-based index of the next element in the iterator,
41: * i.e. the one that will be returned on the subsequent <code>next</code> call.
42: * <p/>
43: * Note that this method does not check if there is a next element,
44: * i.e. an empty iterator will always return 0.
45: *
46: * @return a long
47: */
48: public long getPosition();
49:
50: /**
51: * Returns the number of subsequent <code>next</code> calls that can be
52: * successfully performed on this iterator. This is the number of items
53: * still available through this iterator. For example, for some node
54: * <code>N</code>, <code>N.getNodes().getSize()</code> returns the number
55: * of child nodes of <code>N</code> visible through the current
56: * <code>Session</code> that have not yet been returned. In some
57: * implementations precise information about the number of remaining
58: * elements may not be available. In such cases this method should return
59: * a reasonable upper bound on the number if such an estimate is available
60: * and -1 if it is not.
61: *
62: * @return a long
63: * @since JCR 2.0
64: */
65: public long getNumberRemaining();
66: }
|