org.dasein.util
Class BrowseIterator<T>

java.lang.Object
  org.dasein.util.BrowseIterator<T>

Type Parameters:

T - the type of object being iterated over

All Implemented Interfaces:

Serializable, Iterator<T>

public class BrowseIterator<T>
extends Object
implements Serializable, Iterator<T>

Iterates through a multi-page list of items. The iterator makes a small violation of the Iterator contract by returning false for next() even when more elements exist. The list is specifically exhausted when both next() and hasMorePages() return false.

This iterator divides a list into pages of a specified page size. When no page size is specified, the value from DEFAULT_PAGE_SIZE is used. You can specify a Comparator to perform sorts on the list prior to pagination.

This class also will store an ID field to help you create unique identifiers for the list for temporary storage and reference. You can ignore this value if you have no use for it.

Typical use of this iterator will be to display a list of items one page at a time via a web interface. When you first get the list and display the first page, you might have the following code (functions in italics are dependent on your implementation environment):

Collection<MyItem> items = someItemListing();
int page_size = 20;
BrowseIterator<MyItem> it;

it = new BrowseIterator<MyItem>(1, items, 20, null);
storeList(1, it);
while( it.hasNext() ) {
MyItem ob = it.next();

// display object in your list
}

When the user clicks the next button, your UI can respond:

long id = readValueFromParameters();
BrowseIterator<MyItem> it = lookupList(id);

it.nextPage();
while( it.hasNext() ) {
MyItem ob = it.next();

// display object in your list
}

Last modified: $Date: 2005/09/26 14:15:05 $

Version:

$Revision: 1.4 $

Author:

George Reese

See Also:

Serialized Form

Field Summary

static int

DEFAULT_PAGE_SIZE Default page size when none is specified.

Constructor Summary

BrowseIterator(Collection<T> items)
Constructs a new, unsorted browse iterator with the default page size having the specified items.

BrowseIterator(Collection<T> items, int ps)
Constructs a new, unsorted browse iterator with the specified page size having the specified items.

BrowseIterator(Collection<T> items, int ps, Comparator<T> sort)
Constructs a new iterator with items sorted by the specified sorter.

BrowseIterator(long lid, Collection<T> items, int ps)
Constructs an iterator having the specified unique ID.

BrowseIterator(long lid, Collection<T> items, int ps, Comparator<T> sort)
Constructs an iterator having the specified unique ID with specific sorting rules and page size.

Method Summary

void	firstPage() Sets the iterator to the first page in the iterator.
int	getItemCount()
long	getListId() Provides an application-defined unique identifier for this iterator.
int	getPage()
int	getPageCount()
int	getPageSize()
Comparator<T>	getSorter()
boolean	hasMorePages()
boolean	hasNext()
void	lastPage() Navigates to the last page in the iterator.
T	next()
boolean	nextPage() Navigates to the next page in the iterator.
boolean	previousPage() Navigates to the previous page in the iterator.
void	remove() Throws an UnsupportedOperationException always.
void	reset() Resets the list to the beginning of the iterator.
boolean	setPage(int p) Navigates to the specified page number with 0 being the first page.
void	setPageSize(int ps) Changes the page size of the list and reforms the list.
void	sort(Comparator<T> sort) Re-sorts the list according to the specified sorter.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_PAGE_SIZE

public static final int DEFAULT_PAGE_SIZE

Default page size when none is specified.

See Also:

Constant Field Values

Constructor Detail

BrowseIterator

public BrowseIterator(Collection<T> items)

Constructs a new, unsorted browse iterator with the default page size having the specified items.

Parameters:

items - The items to be iterated over.

BrowseIterator

public BrowseIterator(Collection<T> items,
                      int ps)

Constructs a new, unsorted browse iterator with the specified page size having the specified items.

Parameters:

items - the items to iterate over

ps - the page size for each page in the iterator

BrowseIterator

public BrowseIterator(Collection<T> items,
                      int ps,
                      Comparator<T> sort)

Constructs a new iterator with items sorted by the specified sorter.

Parameters:

items - the items to be iterated over

ps - the page size for each page in the iterator

sort - the rules for sorting the items

BrowseIterator

public BrowseIterator(long lid,
                      Collection<T> items,
                      int ps)

Constructs an iterator having the specified unique ID.

Parameters:

lid - the unique ID to be used to reference this list

items - the items to iterate over

ps - the page size for each page in the iterator

BrowseIterator

public BrowseIterator(long lid,
                      Collection<T> items,
                      int ps,
                      Comparator<T> sort)

Constructs an iterator having the specified unique ID with specific sorting rules and page size.

Parameters:

lid - the unique ID for this iterator

items - the list of items to iterate over

ps - the page size for each page in the iterator

sort - the rules for sorting the items

Method Detail

firstPage

public void firstPage()

Sets the iterator to the first page in the iterator.

getItemCount

public int getItemCount()

Returns:

the number of items in the list on all pages

getListId

public long getListId()

Provides an application-defined unique identifier for this iterator. Some applications may need to store browse iterators for asynchronous access at a later time. The application can create a unique ID value to associate with this list and use the unique ID to store the iterator. If no application-specified value is set, this method will return -1L.

Returns:

the unique list identifier

getPage

public int getPage()

Returns:

the current page number

getPageCount

public int getPageCount()

Returns:

the number of pages in this browse iterator

getPageSize

public int getPageSize()

Returns:

the size of each page

getSorter

public Comparator<T> getSorter()

Returns:

the sorter being used to sort elements in the iterator

hasMorePages

public boolean hasMorePages()

Returns:

true if there are more pages to navigate

hasNext

public boolean hasNext()

Specified by:

hasNext in interface Iterator<T>

Returns:

true if there are more elements in this page

lastPage

public void lastPage()

Navigates to the last page in the iterator.

next

public T next()

Specified by:

next in interface Iterator<T>

Returns:

the next element in the iterator

nextPage

public boolean nextPage()

Navigates to the next page in the iterator.

Returns:

true if it navigated to a new page, false if there are no more pages

previousPage

public boolean previousPage()

Navigates to the previous page in the iterator.

Returns:

true if it navigated to a new page, false if there are no previous pages

remove

public void remove()

Throws an UnsupportedOperationException always.

Specified by:

remove in interface Iterator<T>

reset

public void reset()

Resets the list to the beginning of the iterator.

setPage

public boolean setPage(int p)

Navigates to the specified page number with 0 being the first page.

Parameters:

p - the page number to navigate to

Returns:

true if the page was successfully navigated to

setPageSize

public void setPageSize(int ps)

Changes the page size of the list and reforms the list. May cause unexpected behavior in terms of what is considered the "current page" after resizing.

Parameters:

ps - the new page size

sort

public void sort(Comparator<T> sort)

Re-sorts the list according to the specified sorter.

Parameters:

sort - the sorter to sort the list with

toString

public String toString()

Overrides:

toString in class Object

Returns:

a string depiction of the list