com.bowstreet.builders.webapp.methods
Class PagingAssistant

java.lang.Object
  com.bowstreet.builders.webapp.methods.PagingAssistant

All Implemented Interfaces:

com.bowstreet.webapp.RequestCompleteListener, java.io.Serializable

public class PagingAssistant
extends java.lang.Object
implements java.io.Serializable, com.bowstreet.webapp.RequestCompleteListener

Linked Java Object to aid paged access to tabular data. Created by the Paging Assistant builder.

Note: if you have model actions or custom LJO code that calls one or more of the methods defined below, then you need to call the setWebAppAccess method first with the non-null WebAppAccess instance for the current request. This will ensure that the Paging Assistant methods you are calling have access to the current webApp instance of your model. You only need to call setWebAppAccess once per request; you may call it multiple times per request with the same WebAppAccess instance, but it must be done at least once, typically from an action or LJO code that is executed before any calls are made the methods below.

See Also:

Serialized Form

Field Summary

static java.lang.String	DEFAULT_COLUMN_TAG
static java.lang.String	DEFAULT_ROW_TAG
static java.lang.String	DEFAULT_TOP_LEVEL_TAG
static int	SHOW_ALL_ROWS If this value is passed to setRowsPerPage(), it will cause the assistant to show all pages unless the DataRetriever doesn't know how many total rows there are, in which case it will show a reasonable subset.
static java.lang.String	USE_REQUEST_DATA_CACHE_PROPERTY if this is set on variable, clear cached data on each request

Constructor Summary

PagingAssistant()
Default constructor - need to call setDataRetriever() to complete initialization.

PagingAssistant(DataRetriever retriever)
Create a paging assistant which will use the given data retriever.

Method Summary

boolean	canSort()
void	disableLookaheadCaching() Prevent the LJO from caching data fetched by hasNextPage when it probes the data retriever to detect additional pages of data.
void	enableLookaheadCaching() Allow the LJO to cache data fetched by hasNextPage when it probes the data retriever to detect additional pages of data.
static DataRetriever	findDataRetriever(WebAppAccess webAppAccess, java.lang.Object ref, boolean doInit) Given the name of a variable, find/construct a DataRetriever for it.
static DataRetriever	findDataRetriever(WebAppAccess webAppAccess, java.lang.Object ref, boolean doInit, boolean checkForNewData) Given the name of a variable, find/construct a DataRetriever for it.
void	firstPage() Go to the first page.
java.lang.String	formatRangeText(java.lang.String formatString) Insert the current page/record/count values into a string with the placeholders {start} = first displayed record, {end} = last displayed record, {count} = total records, {page} = current page, {page_count} = total pages.
java.lang.String	formatRangeTextForLocale(java.lang.String formatString, java.util.Locale locale) Insert the current page/record/count values into a string with the placeholders {start} = first displayed record, {end} = last displayed record, {count} = total records, {page} = current page, {page_count} = total pages.
java.util.Collection	getCollection()
int	getCurrentPage() Get the zero-based number of the current page.
int	getCurrentRow() Return the zero-based index of the current row.
IXml	getData() Get the current data.
DataRetriever	getDataRetriever() Return the current DataRetriever.
int	getDisplayPage() Return the one-based page number of the current page.
java.lang.String	getDisplayRange() Return indication of current records for display.
int	getFirstDisplayRow() Get the one-based number of the first row to be displayed.
int	getLastDisplayPage() Return one-based indication of last page available for display.
int	getLastDisplayRow() Get the one-based number of the last row currently available for display.
int	getLastPage() Get the zero-based index of the last page.
java.lang.String	getName() Get the name of this LJO.
java.lang.String	getPageDisplayRange() Return one-based indication of pages available for display.
java.lang.String	getRangeFormat() Get the format of the range specifier used in getDisplayRange().
int	getRowCount() Get total rows.
int	getRowsPerPage() Get the number of rows per page.
java.lang.String	getTopLevelTagName() Return the toplevel tag name
java.util.Collection	getUpdatedCollection(WebAppAccess webAppAccess) Get the current collection, checking for changes in underlying collection first - if changes found, a reset is done.
IXml	getUpdatedData(WebAppAccess webAppAccess) Get the current data, checking for changes in underlying data source first - if changes found, a reset is done.
boolean	hasNextPage() Is there a next page?
boolean	hasPreviousPage() Is there a previous page?
boolean	hasSorted()
static boolean	isPagingVariable(WebAppAccess webAppAccess, java.lang.String ref) Return true if this variable is under the control of a Paging Assistant.
boolean	isRowCountKnown()
void	lastPage() Go to the last page.
void	nextPage() Advance to the next page.
void	notifyRequestComplete() RequestCompleteListener implementation: this is called automatically by the runtime when the overall request is finished.
void	preserveLocation(boolean preserve) Set whether the reset() method should set the current page to 0.
void	previousPage() Go back to the previous page
void	reset(WebAppAccess webAppAccess) Reset the connection with the retriever: go to the first page and free any cached data.
void	setCurrentPage(int pg) Set the zero-based number of the current page.
void	setDataRetriever(DataRetriever retriever) Set the current DataRetriever.
void	setName(java.lang.String name) Tell this LJO the name of its corresponding Variable.
void	setRangeFormat(java.lang.String fmt) Set the format of the range specifier used in getDisplayRange().
void	setRowsPerPage(int rows) Set the rows per page.
void	setTopLevelTagName(java.lang.String tagName) Specify a tag name to use for the data's top-level element.
void	setWebAppAccess(WebAppAccess webAppAccess) Specify the WebAppAccess implementation to use.
boolean	sort(java.lang.String sortBy, java.lang.String sortType) Sort data according to the text of the given column.
boolean	sort(java.lang.String sortBy, java.lang.String sortType, boolean bAscending) Sort data according to the text of the given column.
static boolean	sortPagingVariable(WebAppAccess webAppAccess, java.lang.String dataRef, java.lang.String sortBy, java.lang.String sortType, java.lang.String dateFormat) Sort data according to the text of the given column.
static boolean	sortPagingVariable(WebAppAccess webAppAccess, java.lang.String dataRef, java.lang.String sortBy, java.lang.String sortType, java.lang.String dateFormat, boolean bAscending) Sort data according to the text of the given column.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_COLUMN_TAG

public static final java.lang.String DEFAULT_COLUMN_TAG

See Also:

Constant Field Values

DEFAULT_ROW_TAG

public static final java.lang.String DEFAULT_ROW_TAG

See Also:

Constant Field Values

DEFAULT_TOP_LEVEL_TAG

public static final java.lang.String DEFAULT_TOP_LEVEL_TAG

See Also:

Constant Field Values

SHOW_ALL_ROWS

public static final int SHOW_ALL_ROWS

If this value is passed to setRowsPerPage(), it will cause the assistant to show all pages unless the DataRetriever doesn't know how many total rows there are, in which case it will show a reasonable subset.

See Also:

Constant Field Values

USE_REQUEST_DATA_CACHE_PROPERTY

public static final java.lang.String USE_REQUEST_DATA_CACHE_PROPERTY

if this is set on variable, clear cached data on each request

See Also:

Constant Field Values

Constructor Detail

PagingAssistant

public PagingAssistant()

Default constructor - need to call setDataRetriever() to complete initialization.

PagingAssistant

public PagingAssistant(DataRetriever retriever)

Create a paging assistant which will use the given data retriever.

Method Detail

canSort

public boolean canSort()

disableLookaheadCaching

public void disableLookaheadCaching()

Prevent the LJO from caching data fetched by hasNextPage when it probes the data retriever to detect additional pages of data. Disabling this caching may result in additional queries to the data retriever and it's back-end server, but it will also reduce by 30% the amount of data cached by this PagingAssistant.

enableLookaheadCaching

public void enableLookaheadCaching()

Allow the LJO to cache data fetched by hasNextPage when it probes the data retriever to detect additional pages of data. Enabling this caching will prevent additional queries to the data retriever and it's back-end server, but it will also increase by 30% the amount of data cached by this PagingAssistant. The number of extra rows in the cache will depend upon the fetch size of the data retriever.

findDataRetriever

public static DataRetriever findDataRetriever(WebAppAccess webAppAccess,
                                              java.lang.Object ref,
                                              boolean doInit)

Given the name of a variable, find/construct a DataRetriever for it.

findDataRetriever

public static DataRetriever findDataRetriever(WebAppAccess webAppAccess,
                                              java.lang.Object ref,
                                              boolean doInit,
                                              boolean checkForNewData)

Given the name of a variable, find/construct a DataRetriever for it.

firstPage

public void firstPage()

Go to the first page.

formatRangeText

public java.lang.String formatRangeText(java.lang.String formatString)

Insert the current page/record/count values into a string with the placeholders {start} = first displayed record, {end} = last displayed record, {count} = total records, {page} = current page, {page_count} = total pages. The default locale is used to format the various range numbers.

Parameters:

formatString - The range text format.

formatRangeTextForLocale

public java.lang.String formatRangeTextForLocale(java.lang.String formatString,
                                                 java.util.Locale locale)

Insert the current page/record/count values into a string with the placeholders {start} = first displayed record, {end} = last displayed record, {count} = total records, {page} = current page, {page_count} = total pages.

Parameters:

formatString - The range text format.

locale - The locale to be used when formatting the range text. The default locale will be used if null.

getCollection

public java.util.Collection getCollection()

getCurrentPage

public int getCurrentPage()

Get the zero-based number of the current page.

getCurrentRow

public int getCurrentRow()

Return the zero-based index of the current row.

getData

public IXml getData()

Get the current data.

getDataRetriever

public DataRetriever getDataRetriever()

Return the current DataRetriever.

getDisplayPage

public int getDisplayPage()

Return the one-based page number of the current page.

getDisplayRange

public java.lang.String getDisplayRange()

Return indication of current records for display. These row numbers are one-based, suitable for display.

getFirstDisplayRow

public int getFirstDisplayRow()

Get the one-based number of the first row to be displayed.

getLastDisplayPage

public int getLastDisplayPage()

Return one-based indication of last page available for display.

getLastDisplayRow

public int getLastDisplayRow()

Get the one-based number of the last row currently available for display.

getLastPage

public int getLastPage()

Get the zero-based index of the last page.

getName

public java.lang.String getName()

Get the name of this LJO.

getPageDisplayRange

public java.lang.String getPageDisplayRange()

Return one-based indication of pages available for display.

getRangeFormat

public java.lang.String getRangeFormat()

Get the format of the range specifier used in getDisplayRange().

getRowCount

public int getRowCount()

Get total rows.

getRowsPerPage

public int getRowsPerPage()

Get the number of rows per page.

getTopLevelTagName

public java.lang.String getTopLevelTagName()

Return the toplevel tag name

getUpdatedCollection

public java.util.Collection getUpdatedCollection(WebAppAccess webAppAccess)

Get the current collection, checking for changes in underlying collection first - if changes found, a reset is done.

getUpdatedData

public IXml getUpdatedData(WebAppAccess webAppAccess)

Get the current data, checking for changes in underlying data source first - if changes found, a reset is done.

hasNextPage

public boolean hasNextPage()

Is there a next page?

hasPreviousPage

public boolean hasPreviousPage()

Is there a previous page?

hasSorted

public boolean hasSorted()

isPagingVariable

public static boolean isPagingVariable(WebAppAccess webAppAccess,
                                       java.lang.String ref)

Return true if this variable is under the control of a Paging Assistant.

isRowCountKnown

public boolean isRowCountKnown()

lastPage

public void lastPage()

Go to the last page.

nextPage

public void nextPage()

Advance to the next page.

notifyRequestComplete

public void notifyRequestComplete()

RequestCompleteListener implementation: this is called automatically by the runtime when the overall request is finished.

Specified by:

notifyRequestComplete in interface com.bowstreet.webapp.RequestCompleteListener

preserveLocation

public void preserveLocation(boolean preserve)

Set whether the reset() method should set the current page to 0. Otherwise, it does not set the value, and we try to keep or position. getDataFromCache() takes care of the start>rows case.

previousPage

public void previousPage()

Go back to the previous page

reset

public void reset(WebAppAccess webAppAccess)

Reset the connection with the retriever: go to the first page and free any cached data.

setCurrentPage

public void setCurrentPage(int pg)

Set the zero-based number of the current page.

setDataRetriever

public void setDataRetriever(DataRetriever retriever)

Set the current DataRetriever.

setName

public void setName(java.lang.String name)

Tell this LJO the name of its corresponding Variable.

setRangeFormat

public void setRangeFormat(java.lang.String fmt)

Set the format of the range specifier used in getDisplayRange().

setRowsPerPage

public void setRowsPerPage(int rows)

Set the rows per page. Note that changing this value will cause a reset.

setTopLevelTagName

public void setTopLevelTagName(java.lang.String tagName)

Specify a tag name to use for the data's top-level element.

setWebAppAccess

public void setWebAppAccess(WebAppAccess webAppAccess)

Specify the WebAppAccess implementation to use. This is called automatically by event handlers used by the paging buttons and links builders, and generally does not need to be called directly.

sort

public boolean sort(java.lang.String sortBy,
                    java.lang.String sortType)

Sort data according to the text of the given column. If this method returns true, then sorted data will be available next time it is fetched from the data source; a return of false indicates that the data source does not know how to sort the data itself.

Parameters:

sortBy - name of the column whose data controls sort order

sortType - how to interpret and compare the data - NUMBERS, DATES, CASE_INSENSITIVE or DEFAULT_TYPE

sort

public boolean sort(java.lang.String sortBy,
                    java.lang.String sortType,
                    boolean bAscending)

Sort data according to the text of the given column. If this method returns true, then sorted data will be available next time it is fetched from the data source; a return of false indicates that the data source does not know how to sort the data itself.

Parameters:

sortBy - name of the column whose data controls sort order

sortType - how to interpret and compare the data - NUMBERS, DATES, CASE_INSENSITIVE or DEFAULT_TYPE

bAscending - do you want to sort ascending

sortPagingVariable

public static boolean sortPagingVariable(WebAppAccess webAppAccess,
                                         java.lang.String dataRef,
                                         java.lang.String sortBy,
                                         java.lang.String sortType,
                                         java.lang.String dateFormat)

Sort data according to the text of the given column. If this method returns true, then sorted data will be available next time it is fetched from the data source; a return of false indicates that this variable is not associated with data paging or the underlying data source does not know how to sort the data itself.

Parameters:

dataRef - the name of the Variable or the indirect reference holding the potentially paged data

sortBy - name of the column whose data controls sort order

sortType - how to interpret and compare the data - NUMBERS, DATES, CASE_INSENSITIVE or DEFAULT_TYPE

dateFormat - if sorting as dates, use this pattern to parse the date strings, as in SimpleDateFormat

sortPagingVariable

public static boolean sortPagingVariable(WebAppAccess webAppAccess,
                                         java.lang.String dataRef,
                                         java.lang.String sortBy,
                                         java.lang.String sortType,
                                         java.lang.String dateFormat,
                                         boolean bAscending)

Sort data according to the text of the given column. If this method returns true, then sorted data will be available next time it is fetched from the data source; a return of false indicates that this variable is not associated with data paging or the underlying data source does not know how to sort the data itself.

Parameters:

dataRef - the name of the Variable or the indirect reference holding the potentially paged data

sortBy - name of the column whose data controls sort order

sortType - how to interpret and compare the data - NUMBERS, DATES, CASE_INSENSITIVE or DEFAULT_TYPE

dateFormat - if sorting as dates, use this pattern to parse the date strings, as in SimpleDateFormat

bAscending - do you want to sort ascending