org.hd.d.pg2k.webSvr.catalogue
Class PaginationBeanBase

java.lang.Object
  org.hd.d.pg2k.webSvr.catalogue.PaginationBeanBase

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

PaginationBeanNumeric, PaginationBeanTree

public abstract class PaginationBeanBase
extends java.lang.Object
implements java.io.Serializable

Base bean to help with the pagination for otherwise large pages. This can parse an input argument indicating the desired page, and work out which page is meant and return it as an int for the page logic to use.

This can also generate the labels/values for one or more HTML form submit buttons to help generate the HTML page.

This implementation generates sequential page labels for buttons in its simplest form, but if there are too many buttons to show this then generates a sparser set that ensures that a user can navigate in few clicks to any page and especially so to nearby pages as they home in on a target.

This class is designed to be extended by classes that can put arbitrary labels on the buttons, for example words to help the user go directly to the desired page.

If given an unparseable page number as input, this and deriving implementations should always return a valid page number, returning the "safe" page number of 1 if they cannot deduce the correct page or a near one.

This bases its pagination on the properties in WebConsts dictating the maximum number of items to show on a page and the maximum number of page-choice buttons to show to a user.

This needs to be told the number of entries to be paginated; deriving classes may accept other or extra information in lieu.

This does its basic pagination based on the number of items to be paginated and the WebConsts that dictate maximum items per page and maximum pages or choices of pages to go to at once. In principle these might be user-settable rather than constants.

This is designed to be used as a bean at page or request scope in a JSP, though may be usable outside that environment. It may not be usefully serialisable.

THIS CLASS IS NOT THREAD SAFE since its usual environment and indeed lifetime is within the thread of a single servlet/JSP page service and thread-safety is an unnecessary overhead. Its methods are not synchronized, and if it is necessary to share one instance between threads they must hold a lock on the instance.

This Serializable so as to be able to be stored in a servlet session; nothing especially long-lived or sensitive.

TODO: Should do validation on deserialisation.

See Also:

Serialized Form

numberOfItems

private int numberOfItems

Number of items to be paginated; non-negative. Defaults to zero meaning no items to paginate; any attempt to set it to a negative number sets it to zero.

pg

private int pg

The page number of the current page; strictly positive. Defaults to 1; any attempt to set it to an invalid value will set it to 1, which is always safe.

The page number must be positive and less than numberOfPages() unless numberOfPages is 0, in which case the page number must be exactly 1.

This property matches the property named by WebConsts.PAGE_NUMBER_PARAMETER to allow for easy setting of the property from a JSP.

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID generated by http://random.hd.org/.

See Also:

Constant Field Values

PaginationBeanBase

public PaginationBeanBase()

getNumberOfItems

public final int getNumberOfItems()

Get number of items to be paginated; non-negative. Defaults to zero meaning no items to paginate.

setNumberOfItems

public void setNumberOfItems(int numberOfItems)

Set number of items to be paginated; non-negative. Defaults to zero meaning no items to paginate; any attempt to set it to a negative number sets it to zero.

getNumberOfPages

public final int getNumberOfPages()

Compute the number of pages based on the numberOfItems to be paginated. Is zero if there are no items, else strictly positive.

Uses the WebConsts.MAX_RESULTS_PER_PAGE to determine how many pages will be needed.

setPg

public void setPg(int pg)

Set the page number of the current page; strictly positive. Defaults to 1; any attempt to set it to an invalid value will set it to 1, which is always safe.

The page number must be positive and less than numberOfPages() unless numberOfPages is 0, in which case the page number must be exactly 1.

This property name matches the property named by WebConsts.PAGE_NUMBER_PARAMETER to allow for easy setting of the property from a JSP.

setPg

public void setPg(java.lang.String s)

Set the page number as a String; if invalid (eg badly-formatted input or null) set page number to 1. It must always be possible to parse the label for any page whatever set getPageLabels() returns.

A deriving class must override this for specialised parses.

getPageNumber

public abstract int getPageNumber(java.lang.String s)

Find out what page number a given label indicates. This should be the reverse of getPageLabel().

On badly-formed or otherwise-unparsable input this should return 1.

getPg

public final int getPg()

Get the page number of the current page; strictly positive. Defaults to 1.

getStartIndex

public final int getStartIndex()

Get (index of) lowest-numbered item to display; non-negative. If numberOfItems() is zero this returns zero, else this returns less than numberOfItems().

Computed from the page number and the WebConsts.MAX_RESULTS_PER_PAGE value.

getEndIndex

public final int getEndIndex()

Get (index of) one beyond highest-numbered item to display; non-negative. Exactly numberOfItems() for the last page, else exactly one page more than getStartIndex().

Computed from the page number and the WebConsts.MAX_RESULTS_PER_PAGE value.

getPageLabel

public abstract java.lang.String getPageLabel(int pageNum)

Return the page label for the given page (1 upwards), never null; the page must be in range else the result is undefined. This will commonly be overridden in deriving classes.

The label generated must be deterministic and depend only on the attributes set for the bean, and the same as getPageLabels() would have generated for this given page. The value for a label must not depend on the current page value, and it must always be possible to parse the label for any page whatever set getPageLabels() returns.

In many cases getPageLabels() can simply be implemented in terms of getPageLabel() though sometimes efficiency considerations (for example) may preclude that.

getPageNumbers

public int[] getPageNumbers()

Get an ordered array of page numbers that correspond index-by-index to the page labels returned by getPageLabels(). If there are no more than MAX_RESULTS_PAGES in total than a contigious set of pages from 1 up to the getNumberOfPages() is returned, else some subset of pages is returned usually including the first and last items and the current page and its neighbours, in ascending order.

The array returned is private to the caller.

This can be overridden to vary the page distribution details though the general contract must be maintained.

getPageLabels

public java.util.List<java.lang.String> getPageLabels()

Gets ordered (unmodifiable) List of String labels/tokens for page buttons. Computes a set of pages and returns String values to use as the values (and legends) for submit buttons for this class to parse with the setPg(String) routine.

These labels have to be accepted by setPg(String).

The labels are unique and identify pages in monotonically-increasing order as you iterate through the List.

The labels generated must be deterministic and depend only on the attributes set for the bean, possibly including the current page.

Usually the first and last items in the List a labels for the first and last pages in the range.

Usually labels for the current page and those immediately before and after it are in the result list.

The base implementation calls getPageLabel() to generate the individual labels, so it may often be sufficient to override getPageLabel() only in a derived class.

This will commonly be overridden in deriving classes but the general contract must be maintained.