1 package com.atlassian.user.search.page;
2
3 /**
4 * Will page through results in a database, LDAP system, etc., as required by the iterator it hands out.
5 *
6 * The purpose of the pager is to preload a {@link List} of results, hand out on a single iterator which
7 * can walk the results and transform each one, and transparently reconnect to the
8 * remote system when more data is required.
9 *
10 * Clients can use the call to iterator directly or can rely upon reading the current page and calling nextPage().
11 */
12
13 import java.util.Iterator;
14 import java.util.List;
15 import java.util.Collections;
16
17 public interface Pager<T> extends Iterable<T>
18 {
19 final Pager EMPTY_PAGER = DefaultPager.emptyPager();
20
21 /**
22 * Maximum number of elements to hold in memory at a given moment.
23 */
24 final int PRELOAD_LIMIT = 100;
25 final int NO_POSITION = -1;
26
27 boolean isEmpty();
28
29 /**
30 * Use this if you want a typical iterator over the entire data.
31 *
32 * @return an {@link Iterator} for the entire result set.
33 */
34 Iterator<T> iterator();
35
36 /**
37 * @return a single, preloaded page.
38 */
39 List<T> getCurrentPage();
40
41 void nextPage();
42
43 boolean onLastPage();
44
45 /**
46 * Will run the index up to this point. Calling {@link Pager#getCurrentPage()} will
47 * then return a page holding this index.
48 *
49 * @param index the zero-based index of the item to skip to.
50 * @throws PagerException - if the number of items in the backing data is exceeded by the index.
51 */
52 void skipTo(int index) throws PagerException;
53
54 /**
55 * @return the current index position of the pager
56 */
57 int getIndex();
58
59 /**
60 * @return the index of the first item in the current page, relative to the start of the set
61 */
62 int getIndexOfFirstItemInCurrentPage();
63 }