com.sun.data.provider
Interface TableDataSorter

All Known Implementing Classes:

BasicTableDataSorter

public interface TableDataSorter

The TableDataSorter interface defines a sort criteria and mechanism for sorting the contents of a TableDataProvider. The sort criteria is stored in an array of SortCriteria objects, and the sort operation is invoked via the sort(TableDataProvider,RowKey[]) method.

NOTE: If a component is bound to a TableDataProvider and a TableDataSorter which are the *same* instance, the sort(...) method is never called. The sort order is assumed to be intrinsic in the row order of the TableDataProvider, based on the currently set sort criteria.

Author:

Joe Nuxoll

See Also:

TableDataProvider, SortCriteria

Method Summary

SortCriteria[]	getSortCriteria() Returns the current sort criteria on this data sorter.
java.util.Locale	getSortLocale() Gets the sort locale used when comparing objects.
void	setSortCriteria(SortCriteria[] sortCriteria) Sets the sort criteria on this data sorter.
void	setSortLocale(java.util.Locale locale) Sets the sort locale to use when comparing objects.
RowKey[]	sort(TableDataProvider provider, RowKey[] rows) Sorts the rows from the specified TableDataProvider based on the current sort criteria, and returns an array of RowKeys representing the sorted row order.

Method Detail

setSortCriteria

public void setSortCriteria(SortCriteria[] sortCriteria)

Sets the sort criteria on this data sorter.

Parameters:

sortCriteria - An array of SortCriteria objects defining the sort order on this TableDataSorter

getSortCriteria

public SortCriteria[] getSortCriteria()

Returns the current sort criteria on this data sorter.

Returns:

SortCriteria[] defining the sort order on this TableDataSorter

setSortLocale

public void setSortLocale(java.util.Locale locale)

Sets the sort locale to use when comparing objects. If none is set, the default locale should be used via Locale.getDefault().

Parameters:

locale - The desired Locale to use for sort comparisons

getSortLocale

public java.util.Locale getSortLocale()

Gets the sort locale used when comparing objects. If none is set, the default locale should be used via Locale.getDefault().

Returns:

The Locale used for comparing objects, or null if the default Locale is used.

sort

public RowKey[] sort(TableDataProvider provider,
                     RowKey[] rows)
              throws DataProviderException

Sorts the rows from the specified TableDataProvider based on the current sort criteria, and returns an array of RowKeys representing the sorted row order. Any excluded rows from the return value of sort(...) should be considered unsortable, and thus should be displayed at the end of whatever UI is presenting these items.

NOTE: If a component is bound to a TableDataProvider and an TableDataSorter, which are the *same* instance, this method is never called. The sort order is assumed to be intrinsic in the row key order of the TableDataProvider, based on the currently set sort criteria.

Parameters:

provider - The TableDataProvider to sort

rows - The array of RowKeys to sort. If this is null then the return value should be null or an empty array of RowKeys.

Returns:

An array of RowKeys representing the sorted rows from the specified TableDataProvider. Any excluded rows from the return value of this method should be considered unsortable, and thus should be displayed at the end of whatever UI is presenting these items. null may be returned to indicate that sorting is not possible.

Throws:

DataProviderException - Implementations may wish to surface internal exceptions (nested in DataProviderException) rather than simply returning null or an empty array. A DPE may also indicate that the passed TableDataProvider or RowKeys are not valid. Consult the documentation of the specific TableDataSorter implementation for details on what exceptions might be wrapped by a DPE.