Klasse LargeSelect<T>
- Typparameter:
T
- the type of the objects which are returned on a query.
- Alle implementierten Schnittstellen:
Serializable
,Runnable
LargeSelect
is meant to be placed into the Session or User.Temp, so
that it can be used in response to several related requests. Note that in
order to use LargeSelect
you need to be willing to accept the
fact that the result set may become inconsistent with the database if updates
are processed subsequent to the queries being executed. Specifying a memory
page limit of 1 will give you a consistent view of the records but the totals
may not be accurate and the performance will be terrible. In most cases
the potential for inconsistencies data should not cause any serious problems
and performance should be pretty good (but read on for further warnings).
The idea here is that the full query result would consume too much memory and if displayed to a user the page would be too long to be useful. Rather than loading the full result set into memory, a window of data (the memory limit) is loaded and retrieved a page at a time. If a request occurs for data that falls outside the currently loaded window of data then a new query is executed to fetch the required data. Performance is optimized by starting a thread to execute the database query and fetch the results. This will perform best when paging forwards through the data, but a minor optimization where the window is moved backwards by two rather than one page is included for when a user pages past the beginning of the window.
As the query is performed in in steps, it is often the case that the total
number of records and pages of data is unknown. LargeSelect
provides various methods for indicating how many records and pages it is
currently aware of and for presenting this information to users.
LargeSelect
utilizes the Criteria
methods
setOffset()
and setLimit()
to limit the amount of
data retrieved from the database - these values are either passed through to
the DBMS when supported (efficient with the caveat below) or handled by
the Torque API when it is not (not so efficient).
As LargeSelect
must re-execute the query each time the user
pages out of the window of loaded data, you should consider the impact of
non-index sort orderings and other criteria that will require the DBMS to
execute the entire query before filtering down to the offset and limit either
internally or via Torque.
The memory limit defaults to 5 times the page size you specify, but
alternative constructors and the class method setMemoryPageLimit()
allow you to override this for a specific instance of
LargeSelect
or future instances respectively.
Typically you will create a LargeSelect
using your
Criteria
(perhaps created from the results of a search parameter
page), page size, memory page limit, return class name (for which you may
have defined a business object class before hand) and peer class
and place this in user.Temp thus:
data.getUser().setTemp("someName", largeSelect);
In your template you will then use something along the lines of:
#set($largeSelect = $data.User.getTemp("someName")) #set($searchop = $data.Parameters.getString("searchop")) #if($searchop.equals("prev")) #set($recs = $largeSelect.PreviousResults) #else #if($searchop.equals("goto")) #set($recs = $largeSelect.getPage($data.Parameters.getInt("page", 1))) #else #set($recs = $largeSelect.NextResults) #end #end
...to move through the records. LargeSelect
implements a
number of convenience methods that make it easy to add all of the necessary
bells and whistles to your template.
- Version:
- $Id: LargeSelect.java 1917245 2024-04-21 14:06:23Z tv $
- Autor:
- John D. McNally, Scott Eade
- Siehe auch:
-
Feldübersicht
Felder -
Konstruktorübersicht
KonstruktorenKonstruktorBeschreibungLargeSelect
(Criteria criteria, int pageSize, int memoryPageLimit, BasePeerImpl<T> peerImpl) Creates a LargeSelect whose results are returned as aList
containing a maximum ofpageSize
objects of the type T at a time, maintaining a maximum ofmemoryPageLimit
pages of results in memory.LargeSelect
(Criteria criteria, int pageSize, BasePeerImpl<T> peerImpl) Creates a LargeSelect whose results are returned as aList
containing a maximum ofpageSize
objects of the type defined within the class namedreturnBuilderClassName
at a time, maintaining a maximum ofLargeSelect.memoryPageLimit
pages of results in memory. -
Methodenübersicht
Modifizierer und TypMethodeBeschreibungint
Retrieve the number of the current page.Provide access to the results from the current page.int
Provides a count of the number of rows to be displayed on the current page - for the last page this may be less than the configured page size.int
Provide the record number of the first row included on the current page.int
Provide the record number of the last row included on the current page.int
Retrieves the multiplier that will be used to compute the memory limit when a constructor with no memory page limit is used - the memory limit will be this number multiplied by the page size.Gets the next page of rows.boolean
Indicates if further result pages are available.getPage
(int pageNumber) Retrieve a specific page, if it exists.A convenience method that provides text showing progress through the selected rows on a page basis.Retrieve the MessageFormat pattern for the page progress The default isint
Retrieve the page size.boolean
Provide an indication of whether or not paging of results will be required.Gets the previous page of rows.boolean
Indicates if previous results pages are available.A convenience method that provides text showing progress through the selected rows on a record basis.Retrieve the MessageFormat pattern for the record progress The default isgetSearchParam
(String name) Retrieve a search parameter.getSearchParam
(String name, String defaultValue) Retrieve a search parameter.int
Retrieve the total number of pages of search results that are known to exist (this will be the actual value when the query has completeted (seegetQyeryCompleted()
).int
Retrieve the total number of search result records that are known to exist (this will be the actual value when the query has completed (seegetTotalsFinalized()
).boolean
Provide access to indicator that the total values for the number of records and pages are now accurate as opposed to known upper limits.boolean
Indicates if any results are available.void
Clear the query result so that the query is re-executed when the next page is retrieved.void
removeSearchParam
(String name) Remove a value from the search parameters.void
run()
A background thread that retrieves the rows.void
setMemoryPageLimit
(int memoryPageLimit) Sets the multiplier that will be used to compute the memory limit when a constructor with no memory page limit is used - the memory limit will be this number multiplied by the page size.void
setPageProgressTextPattern
(String pageProgressTextPattern) Set the MessageFormat pattern for the page progress.void
setRecordProgressTextPattern
(String recordProgressTextPattern) Set the MessageFormat pattern for the record progress.void
setSearchParam
(String name, String value) Set a search parameter.toString()
Provide something useful for debugging purposes.
-
Felddetails
-
DEFAULT_PAGE_PROGRESS_TEXT_PATTERN
default MessageFormat pattern for the page progress text- Siehe auch:
-
DEFAULT_RECORD_PROGRESS_TEXT_PATTERN
default MessageFormat pattern for the record progress text- Siehe auch:
-
DEFAULT_MEMORY_LIMIT_PAGES
public static final int DEFAULT_MEMORY_LIMIT_PAGESThe default value for the maximum number of pages of data to be retained in memory.- Siehe auch:
-
-
Konstruktordetails
-
LargeSelect
Creates a LargeSelect whose results are returned as aList
containing a maximum ofpageSize
objects of the type defined within the class namedreturnBuilderClassName
at a time, maintaining a maximum ofLargeSelect.memoryPageLimit
pages of results in memory.- Parameter:
criteria
- object used by BasePeer to build the query. In order to allow this class to utilize database server implemented offsets and limits (when available), the provided criteria must not have any limit or offset defined.pageSize
- number of rows to return in one block.peerImpl
- the peer that will be used to do the select operations- Löst aus:
IllegalArgumentException
- ifcriteria
uses one or both of offset and limit, ifpageSize
is less than 1 or the Criteria object does not contain SELECT columns.
-
LargeSelect
Creates a LargeSelect whose results are returned as aList
containing a maximum ofpageSize
objects of the type T at a time, maintaining a maximum ofmemoryPageLimit
pages of results in memory.- Parameter:
criteria
- object used by BasePeerImpl to build the query. In order to allow this class to utilize database server implemented offsets and limits (when available), the provided criteria must not have any limit or offset defined.pageSize
- number of rows to return in one block.memoryPageLimit
- maximum number of pages worth of rows to be held in memory at one time.peerImpl
- the peer that will be used to do the select operations- Löst aus:
IllegalArgumentException
- ifcriteria
uses one or both of offset and limit, ifpageSize
ormemoryLimitPages
are less than 1 or the Criteria object does not contain SELECT columns..
-
-
Methodendetails
-
getPage
Retrieve a specific page, if it exists.- Parameter:
pageNumber
- the number of the page to be retrieved - must be greater than zero. An emptyList
will be returned ifpageNumber
exceeds the total number of pages that exist.- Gibt zurück:
- a
List
of query results containing a maximum ofpageSize
results. - Löst aus:
IllegalArgumentException
- whenpageNo
is not greater than zero.TorqueException
- if a sleep is unexpectedly interrupted.
-
getNextResults
Gets the next page of rows.- Gibt zurück:
- a
List
of query results containing a maximum ofpageSize
results. - Löst aus:
TorqueException
- if a sleep is unexpectedly interrupted.
-
getCurrentPageResults
Provide access to the results from the current page.- Gibt zurück:
- a
List
of query results containing a maximum ofpageSize
results. - Löst aus:
TorqueException
- if a sleep is unexpectedly interrupted.
-
getPreviousResults
Gets the previous page of rows.- Gibt zurück:
- a
List
of query results containing a maximum ofpageSize
results. - Löst aus:
TorqueException
- if a sleep is unexpectedly interrupted.
-
run
public void run()A background thread that retrieves the rows. -
getCurrentPageNumber
public int getCurrentPageNumber()Retrieve the number of the current page.- Gibt zurück:
- the current page number.
-
getTotalRecords
public int getTotalRecords()Retrieve the total number of search result records that are known to exist (this will be the actual value when the query has completed (seegetTotalsFinalized()
). The convenience methodgetRecordProgressText()
may be more useful for presenting to users.- Gibt zurück:
- the number of result records known to exist (not accurate until
getTotalsFinalized()
returnstrue
).
-
getPaginated
public boolean getPaginated()Provide an indication of whether or not paging of results will be required.- Gibt zurück:
true
when multiple pages of results exist.
-
getTotalPages
public int getTotalPages()Retrieve the total number of pages of search results that are known to exist (this will be the actual value when the query has completeted (seegetQyeryCompleted()
). The convenience methodgetPageProgressText()
may be more useful for presenting to users.- Gibt zurück:
- the number of pages of results known to exist (not accurate until
getTotalsFinalized()
returnstrue
).
-
getPageSize
public int getPageSize()Retrieve the page size.- Gibt zurück:
- the number of records returned on each invocation of
getNextResults()
/getPreviousResults()
.
-
getTotalsFinalized
public boolean getTotalsFinalized()Provide access to indicator that the total values for the number of records and pages are now accurate as opposed to known upper limits.- Gibt zurück:
true
when the totals are known to have been fully computed.
-
getPageProgressTextPattern
Retrieve the MessageFormat pattern for the page progress The default is{0} of {1,choice,0#> |1#}{2}
- Gibt zurück:
- the pattern as a string
-
setPageProgressTextPattern
Set the MessageFormat pattern for the page progress. The default is{0} of {1,choice,0#> |1#}{2}
The pattern contains three placeholders
- {0} - the current page
- {1} - 0 if the total number of pages is not yet known, 1 otherwise
- {2} - the total number of pages
Localized example in German:
Seite {0} von {1,choice,0#mehr als |1#}{2}
- Parameter:
pageProgressTextPattern
-
-
getRecordProgressTextPattern
Retrieve the MessageFormat pattern for the record progress The default is{0} - {1} of {2,choice,0#> |1#}{3}
- Gibt zurück:
- the pattern as a string
-
setRecordProgressTextPattern
Set the MessageFormat pattern for the record progress. The default is{0} - {1} of {2,choice,0#> |1#}{3}
The pattern contains four placeholders
- {0} - number of the first record on the page
- {1} - number of the last record on the page
- {2} - 0 if the total number of records is not yet known, 1 otherwise
- {3} - the total number of records
Localized example in German:
Datensätze {0} bis {1} von {2,choice,0#mehr als |1#}{3}
- Parameter:
recordProgressTextPattern
-
-
setMemoryPageLimit
public void setMemoryPageLimit(int memoryPageLimit) Sets the multiplier that will be used to compute the memory limit when a constructor with no memory page limit is used - the memory limit will be this number multiplied by the page size.- Parameter:
memoryPageLimit
- the maximum number of pages to be in memory at one time.
-
getMemoryPageLimit
public int getMemoryPageLimit()Retrieves the multiplier that will be used to compute the memory limit when a constructor with no memory page limit is used - the memory limit will be this number multiplied by the page size.- Gibt zurück:
- memoryPageLimit the maximum number of pages to be in memory at one time.
-
getPageProgressText
A convenience method that provides text showing progress through the selected rows on a page basis.- Gibt zurück:
- progress text in the form of "1 of > 5" where ">" can be
configured using
setMoreIndicator()
.
-
getCurrentPageSize
Provides a count of the number of rows to be displayed on the current page - for the last page this may be less than the configured page size.- Gibt zurück:
- the number of records that are included on the current page of results.
- Löst aus:
TorqueException
- if invoking thepopulateObjects()
method runs into problems or a sleep is unexpectedly interrupted.
-
getFirstRecordNoForPage
public int getFirstRecordNoForPage()Provide the record number of the first row included on the current page.- Gibt zurück:
- The record number of the first row of the current page.
-
getLastRecordNoForPage
Provide the record number of the last row included on the current page.- Gibt zurück:
- the record number of the last row of the current page.
- Löst aus:
TorqueException
- if invoking thepopulateObjects()
method runs into problems or a sleep is unexpectedly interrupted.
-
getRecordProgressText
A convenience method that provides text showing progress through the selected rows on a record basis.- Gibt zurück:
- progress text in the form of "26 - 50 of > 250" where ">"
can be configured using
setMoreIndicator()
. - Löst aus:
TorqueException
- if invoking thepopulateObjects()
method runs into problems or a sleep is unexpectedly interrupted.
-
getNextResultsAvailable
public boolean getNextResultsAvailable()Indicates if further result pages are available.- Gibt zurück:
true
when further results are available.
-
getPreviousResultsAvailable
public boolean getPreviousResultsAvailable()Indicates if previous results pages are available.- Gibt zurück:
true
when previous results are available.
-
hasResultsAvailable
public boolean hasResultsAvailable()Indicates if any results are available.- Gibt zurück:
true
of any results are available.
-
invalidateResult
Clear the query result so that the query is re-executed when the next page is retrieved. You may want to invoke this method if you are returning to a page after performing an operation on an item in the result set.- Löst aus:
TorqueException
- if a sleep is interrupted.
-
getSearchParam
Retrieve a search parameter. This acts as a convenient place to store parameters that relate to the LargeSelect to make it easy to get at them in order to re-populate search parameters on a form when the next page of results is retrieved - they in no way effect the operation of LargeSelect.- Parameter:
name
- the search parameter key to retrieve.- Gibt zurück:
- the value of the search parameter.
-
getSearchParam
Retrieve a search parameter. This acts as a convenient place to store parameters that relate to the LargeSelect to make it easy to get at them in order to re-populate search parameters on a form when the next page of results is retrieved - they in no way effect the operation of LargeSelect.- Parameter:
name
- the search parameter key to retrieve.defaultValue
- the default value to return if the key is not found.- Gibt zurück:
- the value of the search parameter.
-
setSearchParam
Set a search parameter. If the value isnull
then the key will be removed from the parameters.- Parameter:
name
- the search parameter key to set.value
- the value of the search parameter to store.
-
removeSearchParam
Remove a value from the search parameters.- Parameter:
name
- the search parameter key to remove.
-
toString
Provide something useful for debugging purposes.
-