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

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

All Implemented Interfaces:

java.io.Serializable

public final class PaginationBeanNumeric
extends PaginationBeanBase

Bean to help with the pagination for otherwise large pages; this generates numeric labels. This can parse an input argument indicating the desired page, or find it directly in an incoming HttpRequest, 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-numbering 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 arbitraty 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 enviroment 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.

See Also:

Serialized Form

pageLabels1Upwards

private static final java.util.List<java.lang.String> pageLabels1Upwards

Immutable List of String labels containing decimal integers from 1 to WebConsts.MAX_RESULTS_PAGES. Note that the label at index i is the value of i+1, eg at index 0 is "1".

Used to cover the most common cases without needing to generate lots of new objects each time.

serialVersionUID

private static final long serialVersionUID

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

See Also:

Constant Field Values

PaginationBeanNumeric

public PaginationBeanNumeric()

getPageNumber

public int getPageNumber(java.lang.String s)

Get the page number as a from the String label; in case of bad input return 1. This parses using Integer.parseInt("string", 10).

A deriving class may override this for more sophisticated or specialised parses.

Specified by:

getPageNumber in class PaginationBeanBase

getPageLabels

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

Gets ordered (unmodifiable) List of String labels/tokens for page buttons. This implementation makes the labels numeric and optimises the case of returning contigious labels starting at "1" to minimise object churn.

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.

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 returns numeric labels, but this 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.

Overrides:

getPageLabels in class PaginationBeanBase

getPageLabel

public 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.

Specified by:

getPageLabel in class PaginationBeanBase

generateNumericPageLabels1Upwards

private static java.util.List<java.lang.String> generateNumericPageLabels1Upwards(int nPages)

Return an immutable List of contigious String (int-valued) labels for page buttons from 1 upwards. In the case where the top value is no more than WebConsts.MAX_RESULTS_PAGES we return a sub-list of a static singleton immutable List covering this range without synchronsiation or (significant) object creation for efficiency.

Parameters:

nPages - requests list of String labels for buttons for the decimal integers from "1" upwards so a value of 3 would return the list "1", "2", "3" for example; the argument must be non-negative

generateNewNumericPageLabels1Upwards

private static final java.util.List<java.lang.String> generateNewNumericPageLabels1Upwards(int nPages)

Generate a new immutable List of pageLabels from "1" upwards each time; argument must be non-negative. We String.intern() the first few labels for maximum memory efficiency!