com.bea.p13n.pagination
Interface FilterablePagedResult<T>

All Superinterfaces
PagedResult<T>, Serializable
All Known Subinterfaces:
ICMPagedResult<T>, SortableFilterablePagedResult<T>

public interface FilterablePagedResult<T>
extends PagedResult<T>

A PagedResult which can be filtered. Filter is like "lite" search, but is used to restrict a returned set of PagedResults to some subset.

It is generally expected that most implementations will be backed by something like database queries, and should be optimized for paganated access. That is, rather than retrieving a full set of results into memory and filtering (subsetting) those results, the implementation should retrieve results, filtered by the database, a page (or a few pages) at a time, and return those via the PagedResults interface.

The filter criteria is described by a FilterMethod and a string, which matches a named property of the result (T).


Field Summary
 
Fields inherited from interface com.bea.p13n.pagination.PagedResult
COUNT_UNKNOWN
 
Method Summary
 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.
 Set<FilterMethod> getSupportedFilterMethods()
          An implementation must report which FilterMethods it supports.
 void reFilter(FilterMethod filterMethod, String filterString, String filterProperty, Locale filterLocale)
          Refilter the results.
 
Methods inherited from interface com.bea.p13n.pagination.PagedResult
close, getCurrentPageNumber, getPage, getPageCount, getPageSize, getTotalItemCount, hasNextPage, hasPage, hasPreviousPage, isCompleteResults, isGetPageSupported, nextPage, previousPage, resize
 

Method Detail

getSupportedFilterMethods

Set<FilterMethod> getSupportedFilterMethods()
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 ).


getFilterableProperties

Set<String> getFilterableProperties()
An implementation must report which of its properties can be legaly filtered.

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.

getFilterMethod

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


getFilterString

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


getFilterProperty

String getFilterProperty()
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.


getFilterLocale

Locale getFilterLocale()
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.


reFilter

void reFilter(FilterMethod filterMethod,
              String filterString,
              String filterProperty,
              Locale filterLocale)
              throws UnsupportedOperationException,
                     IllegalArgumentException
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.

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


Copyright © 2000, 2008, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.