com.bea.content.paging
Interface ICMPagedResult<T>

All Superinterfaces

FilterablePagedResult<T>, PagedResult<T>, Serializable, SortableFilterablePagedResult<T>, SortablePagedResult<T>

public interface ICMPagedResult<T>
extends SortableFilterablePagedResult<T>

An ICMPagedResult represents a collection of query results in a page-based structure. An ICMPagedResult can be constructed from an IPagedList via CMPagedResultFactory.

An overview of capabilities, including sorting and filtering, is provided in the package documentation at com.bea.content.paging.

The number of items per page may be configured via the PAGE_SIZE_KEY context key. The number of items to load at a time may be configured via the ContentListKeys.BATCH_LOADING_SIZE_KEY context key and the getBatchLoadingSize() and setBatchLoadingSize() methods.

For optimal performance, configure the page size and batch loading size ContentContext keys before calling the CM APIs to retrieve the IPagedList.

ICMPagedResult instances may support extra capabilities, such as determining the total number of items, if the batch size is set to ContentListKeys.ALL_ITEMS. You should set this in the ContentContext before calling the CM APIs to retrieve the IPagedList. For memory consumption reasons, this should generally only be used if you expect there to be a limited number of items in the PagedList, or you are using other mechanisms to limit the total number of items retrieved, such as a search max results parameter.

This interface is intended to be implemented only by Oracle Weblogic Portal. Oracle Systems reserves the right to add abstract methods to this interface without notice. Implementations of this interface by other parties must not be expected to compile without change in future versions of Oracle Weblogic Portal.

Field Summary

static ContextKey

PAGE_SIZE_KEY optional CONTEXT KEY which can be placed in the ContentContext -- see ContentContext Specifies the pagesize to use.

Fields inherited from interface com.bea.p13n.pagination.PagedResult

COUNT_UNKNOWN

Fields inherited from interface com.bea.p13n.pagination.PagedResult

COUNT_UNKNOWN

Method Summary

void	close() Close the result and release any resources which it holds.
Iterator<T>	currentPage() Retrieves the current page of items.
int	getBatchLoadingSize() Returns the current batch loading size.
int	getCurrentPageNumber() Get the current page number.
Set<String>	getFilterableProperties() An implementation must report which of its properties can be legaly filtered.
Locale	getFilterLocale() Retrieve the current locale used for filtering.
FilterMethod	getFilterMethod() Retrieve the current state of the filter method (what way the result is currently filtered).
String	getFilterProperty() Retrieve the current state of the property used to filter the result.
String	getFilterString() Retrieve the current state of the string used to filter the result.
int	getFullSize() Finds query results size, regardless of the cost.
Set<String>	getNativeFilterableProperties()
Set<FilterMethod>	getNativeFilterMethods()
Set<String>	getNativeSortableProperties()
Iterator<T>	getPage(int pageNumber) Get the specified page.
int	getPageCount() If the CMPagedResult can efficiently identify the total # of pages in the collection, this method returns the total number of pages in the collection.
int	getPageSize() Get the size of the pages.
Set<String>	getSortableProperties() An implementation must report which of its properties can be legaly sorted.
Locale	getSortLocale() Retrieve the current locale used for sorting.
SortOrder	getSortOrder() Retrieve the current state of the sort order (what order the result is sorted by).
String	getSortProperty() Retrieve the current state of the property used to sort the result.
Set<FilterMethod>	getSupportedFilterMethods() An implementation must report which FilterMethods it supports.
int	getTotalItemCount() If the CMPagedResult can efficiently identify the total # of items in the collection, this method returns the total number of items in the collection.
boolean	hasNextPage() Is there a next page? Will a call to nextPage() succeed?
boolean	hasPage(int pageNumber) Does the given page exist? ICMPagedResult instances currently do not support direct page access, as reported by isGetPageSupported(), so this method always returns false.
boolean	hasPreviousPage() Is there a previous page? Will a call to previousPage() succeed?
boolean	isCompleteResults() Does this result represent a complete set of results? If not, then probably the maximum number of query results was reached and this iterator only represents a subset of the actual query.
boolean	isGetPageSupported() Does this iterator allow random access to pages? This method (vs.
Iterator<T>	nextPage() Get an iterator of the next page full of things.
Iterator<T>	previousPage() Get an iterator of the previous page full of things.
void	reFilter(FilterMethod filterMethod, String filterString, String filterByProperty, Locale filterLocale) Refilter the results.
void	reset()
void	resize(int requestedSize) Set a new page size.
void	reSort(SortOrder sortOrder, String sortByProperty, Locale sortLocale) Resort the results.
void	setBatchLoadingSize(int requestedSize) Updates the batch loading size, and sets the page iterator position to its start position before the first page (just like creating a new PagedResult) The batch loading size specifies how many items are loaded at a time from the backing store when items are retrieved.

Field Detail

PAGE_SIZE_KEY

static final ContextKey PAGE_SIZE_KEY

optional CONTEXT KEY which can be placed in the ContentContext -- see ContentContext Specifies the pagesize to use. Page size must be positive.

Method Detail

getPageSize

int getPageSize()

Description copied from interface: PagedResult

Get the size of the pages. Each call to, for example, nextPage, should return (aproximately) this many items. Do not rely on this number to iterate thru the items, as some pages (like the last page) may have fewer.

Specified by:

getPageSize in interface PagedResult<T>

getTotalItemCount

int getTotalItemCount()
                      throws RepositoryRuntimeException

If the CMPagedResult can efficiently identify the total # of items in the collection, this method returns the total number of items in the collection.

CMPagedResults with a batch size of ContentListKeys.ALL_ITEMS can efficiently determine the total number of items in the collection. You can set the batch size in the ContentContext before retrieving the IPagedList from the CM API.

It may also be possible to efficiently determine the total # of items if one has advanced to the last page.

If the CMPagedResult cannot efficiently identify the total # of items in the collection, this method may return PagedResult.COUNT_UNKNOWN.

Specified by:

getTotalItemCount in interface PagedResult<T>

Throws

RepositoryRuntimeException

getFullSize

int getFullSize()
                throws RepositoryRuntimeException

Finds query results size, regardless of the cost. This method behaves the same as getTotalItemCount(), except that it never returns PagedResult.COUNT_UNKNOWN.

NOTE: this method is potentially very expensive, as expensive as accessing every item, since in some cases, the query results size cannot be determined efficiently. For this reason, it is generally preferable to call getTotalItemCount() instead.

Throws

RepositoryRuntimeException

getPageCount

int getPageCount()
                 throws RepositoryRuntimeException

If the CMPagedResult can efficiently identify the total # of pages in the collection, this method returns the total number of pages in the collection.

CMPagedResults with a batch size of ContentListKeys.ALL_ITEMS can efficiently determine the total number of pages in the collection. You can set the batch size in the ContentContext before retrieving the IPagedList from the CM API.

It may also be possible to efficiently determine the total # of pages if one has advanced to the last page.

If the CMPagedResult cannot efficiently identify the total # of pages in the collection, this method may return PagedResult.COUNT_UNKNOWN.

Specified by:

getPageCount in interface PagedResult<T>

Throws

RepositoryRuntimeException

isCompleteResults

boolean isCompleteResults()
                          throws RepositoryRuntimeException

Description copied from interface: PagedResult

Does this result represent a complete set of results? If not, then probably the maximum number of query results was reached and this iterator only represents a subset of the actual query.

Specified by:

isCompleteResults in interface PagedResult<T>

Throws

RepositoryRuntimeException

getCurrentPageNumber

int getCurrentPageNumber()
                         throws RepositoryRuntimeException

Description copied from interface: PagedResult

Get the current page number. This will be the number of the page retrieved by the last call to nextPage, previousPage, or getPage. If none of those methods have yet been called, it should return -1 (because the next page will be page 0, the first page).

Specified by:

getCurrentPageNumber in interface PagedResult<T>

Throws

RepositoryRuntimeException

hasPreviousPage

boolean hasPreviousPage()
                        throws RepositoryRuntimeException

Description copied from interface: PagedResult

Is there a previous page? Will a call to previousPage() succeed?

Specified by:

hasPreviousPage in interface PagedResult<T>

Throws

RepositoryRuntimeException

hasNextPage

boolean hasNextPage()
                    throws RepositoryRuntimeException

Description copied from interface: PagedResult

Is there a next page? Will a call to nextPage() succeed?

Specified by:

hasNextPage in interface PagedResult<T>

Throws

RepositoryRuntimeException

isGetPageSupported

boolean isGetPageSupported()
                           throws RepositoryRuntimeException

Description copied from interface: PagedResult

Does this iterator allow random access to pages? This method (vs. hasPage) can be used by a GUI to decide if presenting a "go to page" button or field is appropriate.

Specified by:

isGetPageSupported in interface PagedResult<T>

Throws

RepositoryRuntimeException

hasPage

boolean hasPage(int pageNumber)
                throws RepositoryRuntimeException

Does the given page exist? ICMPagedResult instances currently do not support direct page access, as reported by isGetPageSupported(), so this method always returns false. To check if a page exists, advance to the page. If the batch loading size is set to ContentListKeys.ALL_ITEMS, then all results will be stored in memory and this can be done quickly.

Specified by:

hasPage in interface PagedResult<T>

Throws

RepositoryRuntimeException

previousPage

Iterator<T> previousPage()
                         throws NoSuchElementException,
                                RepositoryRuntimeException

Description copied from interface: PagedResult

Get an iterator of the previous page full of things.

Specified by:

previousPage in interface PagedResult<T>

Throws

NoSuchElementException - if there is no previous page.

RepositoryRuntimeException

currentPage

Iterator<T> currentPage()
                        throws NoSuchElementException,
                               RepositoryRuntimeException

Retrieves the current page of items. Note: For a brand-new PagedResult, you need to advance to the first page (by calling hasNextPage/nextPage) in order to retrieve the first set of items.

Throws

NoSuchElementException

RepositoryRuntimeException

nextPage

Iterator<T> nextPage()
                     throws NoSuchElementException,
                            RepositoryRuntimeException

Description copied from interface: PagedResult

Get an iterator of the next page full of things.

Specified by:

nextPage in interface PagedResult<T>

Throws

NoSuchElementException - if there is no next page.

RepositoryRuntimeException

getPage

Iterator<T> getPage(int pageNumber)

Get the specified page. ICMPagedResult instances currently do not support direct page access, as reported by isGetPageSupported(), so this method always throws an UnsupportedOperationException.

Specified by:

getPage in interface PagedResult<T>

close

void close()

Description copied from interface: PagedResult

Close the result and release any resources which it holds. Users must call this when finished using this object.

Specified by:

close in interface PagedResult<T>

reset

void reset()
           throws RepositoryRuntimeException

Throws

RepositoryRuntimeException

resize

void resize(int requestedSize)
            throws RepositoryRuntimeException

Description copied from interface: PagedResult

Set a new page size. When a new page size is set, a PageIterator is REQUIRED to reset itself to "before" page one, so that nextPage will then return a new first page with the new sizing.

Specified by:

resize in interface PagedResult<T>

Throws

RepositoryRuntimeException

getSortOrder

SortOrder getSortOrder()

Description copied from interface: SortablePagedResult

Retrieve the current state of the sort order (what order the result is sorted by).

Specified by:

getSortOrder in interface SortablePagedResult<T>

getSortProperty

String getSortProperty()

Description copied from interface: SortablePagedResult

Retrieve the current state of the property used to sort the result. This property should match one of the java bean properties of the type being sorted. Might be null if the sortOrder is UNSORTED. Some implementations may ignore this property if the results (T) are single-valued (i.e. Strings usually).

Specified by:

getSortProperty in interface SortablePagedResult<T>

getSortLocale

Locale getSortLocale()

Description copied from interface: SortablePagedResult

Retrieve the current locale used for sorting. Null means that Locale is not considered when sorting. Even if set, the implementation might ignore the locale for some sort properties (i.e. numbers, which sort the same in any locale).

Specified by:

getSortLocale in interface SortablePagedResult<T>

reSort

void reSort(SortOrder sortOrder,
            String sortByProperty,
            Locale sortLocale)
            throws UnsupportedOperationException,
                   RepositoryRuntimeException

Description copied from interface: SortablePagedResult

Resort the results. This should result in resetting the PagedResult's current page to "before page one", since the results will be quite different. It should also reset the internal state of sortOrder, sortProperty, and sortLocale to that indicated by the reSort.

Most implementations should not simply reorder the current data, but should rather reissue page queries to retrieve sorted results.

Specified by:

reSort in interface SortablePagedResult<T>

Parameters

sortOrder - the new order to use for sorting. Null is not allowed.

sortByProperty - the property of the result to use for sorting. If sortOrder is UNSORTED, this property is probably ignored (and reSort is not actually required to do anything at all). Must not be null or empty, unless sortOrder is UNSORTED or the implementation chooses to ignore it. Otherwise this must be one of the properties reported by getSortableProperties.

sortLocale - locale used to sort. Null implies that sorting should not be based on Locale. Might be ignored if the bean or property being sorted does not support locale-based sorting (i.e. the property is an Integer).

Throws

UnsupportedOperationException - if the sort can not be performed on the given property.

RepositoryRuntimeException

getFilterMethod

FilterMethod getFilterMethod()
                             throws RepositoryRuntimeException

Description copied from interface: FilterablePagedResult

Retrieve the current state of the filter method (what way the result is currently filtered).

Specified by:

getFilterMethod in interface FilterablePagedResult<T>

Throws

RepositoryRuntimeException

getFilterString

String getFilterString()
                       throws RepositoryRuntimeException

Description copied from interface: FilterablePagedResult

Retrieve the current state of the string used to filter the result. Might be null if the filterMethod is UNFILTERED.

Specified by:

getFilterString in interface FilterablePagedResult<T>

Throws

RepositoryRuntimeException

getFilterProperty

String getFilterProperty()
                         throws RepositoryRuntimeException

Description copied from interface: FilterablePagedResult

Retrieve the current state of the property used to filter the result. Generally, must match one of the values returned by getFilterableProperties, however it might be null if the filterMethod is UNFILTERED. Some implementations may ignore this property if the results (T) are single-valued (i.e. Strings usually). In this case getFilterableProperties should return an empty array.

Specified by:

getFilterProperty in interface FilterablePagedResult<T>

Throws

RepositoryRuntimeException

getFilterLocale

Locale getFilterLocale()
                       throws RepositoryRuntimeException

Description copied from interface: FilterablePagedResult

Retrieve the current locale used for filtering. Null means that Locale is not considered when filtering. Even if set, the implementation might ignore the locale for some properties. In order for locale-based filtering to make sense, the filter property will need different values for various locales.

Specified by:

getFilterLocale in interface FilterablePagedResult<T>

Throws

RepositoryRuntimeException

reFilter

void reFilter(FilterMethod filterMethod,
              String filterString,
              String filterByProperty,
              Locale filterLocale)
              throws UnsupportedOperationException,
                     IllegalArgumentException,
                     RepositoryRuntimeException

Description copied from interface: FilterablePagedResult

Refilter the results. This should result in resetting the PagedResult's current page to "before page one", since the results will be quite different. It should also reset the internal state of filterMethod, filterExpression, filterProperty, and filterLocale to those indicated by the reFilter arguments. Most implementations should not simply subset the current data, but should rather reissue page queries to retrieve filtered results.

Specified by:

reFilter in interface FilterablePagedResult<T>

Parameters

filterMethod - the new method to use for filtering. Null is not allowed.

filterString - the string to use for filtering. If filterMethod is UNFILTERED, this is probably ignored, but reFilter should then reissue the query to return a full unfiltered set of results. May not be null or empty, unlesss filterMethod is UNFILTERED.

filterByProperty - the property of the result to use for filtering. If filterMethod is UNFILTERED, this property is probably ignored (and reFilter simply resets to the full result set). Must not be null or empty, unless filterMethod is UNFILTERED or the implementation chooses to ignore it. Oherwise this should match one of the names returned by getFilterableProperties.

filterLocale - locale used to filter. Null implies that filtering should not be based on Locale. Might be ignored if the bean or property being filtered does not support locale-based filtering (i.e. the property is an Integer or has no associated localized content).

Throws

UnsupportedOperationException - if filtering can not be performed for the given property or method.

IllegalArgumentException - if filterMethod is null, or if the filterExpression or filterPropery are null or empty string when filterMethod is anything other than UNFILTERED.

RepositoryRuntimeException

getNativeSortableProperties

Set<String> getNativeSortableProperties()
                                        throws RepositoryRuntimeException

Throws

RepositoryRuntimeException

getNativeFilterMethods

Set<FilterMethod> getNativeFilterMethods()
                                         throws RepositoryRuntimeException

Throws

RepositoryRuntimeException

getNativeFilterableProperties

Set<String> getNativeFilterableProperties()
                                          throws RepositoryRuntimeException

Throws

RepositoryRuntimeException

getSortableProperties

Set<String> getSortableProperties()
                                  throws RepositoryRuntimeException

Description copied from interface: SortablePagedResult

An implementation must report which of its properties can be legaly sorted.

Specified by:

getSortableProperties in interface SortablePagedResult<T>

Returns

a set of strings naming sortable properties which can be used with reSort's sortProperty. May not be null, if no properties are sortable this method should return an empty set.

Throws

RepositoryRuntimeException

getSupportedFilterMethods

Set<FilterMethod> getSupportedFilterMethods()
                                            throws RepositoryRuntimeException

Description copied from interface: FilterablePagedResult

An implementation must report which FilterMethods it supports. All implementations must support UNFILTERED, but some may, for example, only be able to support EQUALS and/or BEGINS_WITH. This method should return the set of supported methods. It must not be null, and needs not include UNFILTERED (but may), as this is implicitly required. Most implementations will probably return something like EnumSet.allOf( FilterMethod.class ).

Specified by:

getSupportedFilterMethods in interface FilterablePagedResult<T>

Throws

RepositoryRuntimeException

getFilterableProperties

Set<String> getFilterableProperties()
                                    throws RepositoryRuntimeException

Description copied from interface: FilterablePagedResult

An implementation must report which of its properties can be legaly filtered.

Specified by:

getFilterableProperties in interface FilterablePagedResult<T>

Returns

a set of strings naming filterable properties which can be used with reFilter's filterProperty. May not be null, if the result type (T) is single-vauled (i.e. a String), and does not filter based on properties, then this method should return an empty set.

Throws

RepositoryRuntimeException

getBatchLoadingSize

int getBatchLoadingSize()
                        throws RepositoryRuntimeException

Returns the current batch loading size. The batch loading size specifies how many items are loaded at a time from the backing store when items are retrieved. This method may return the special batch loading size ContentListKeys.ALL_ITEMS

Throws

RepositoryRuntimeException

setBatchLoadingSize

void setBatchLoadingSize(int requestedSize)
                         throws RepositoryRuntimeException

Updates the batch loading size, and sets the page iterator position to its start position before the first page (just like creating a new PagedResult) The batch loading size specifies how many items are loaded at a time from the backing store when items are retrieved.

The batch loading size must be either equal to the page size, or the special ContentListKeys.ALL_ITEMS size

NOTE: This method should only be called before calling nextPage(). If this method is called after calling nextPage(), a RepositoryRuntimeException will be thrown

NOTE: For performance reasons, rather than calling this method, it is preferable to configure the batch size in the ContentContext (using ContentListKeys.BATCH_LOADING_SIZE_KEY) before calling the CM API to retrieve a PagedList.

Throws

RepositoryRuntimeException