 java.lang.Object

 javax.swing.RowSorter<M>

 javax.swing.DefaultRowSorter<M,I>

 Type Parameters:
M
 the type of the modelI
 the type of the identifier passed to theRowFilter
 Direct Known Subclasses:
TableRowSorter
public abstract class DefaultRowSorter<M,I> extends RowSorter<M>
An implementation ofRowSorter
that provides sorting and filtering around a gridbased data model. Beyond creating and installing aRowSorter
, you very rarely need to interact with one directly. Refer toTableRowSorter
for a concrete implementation ofRowSorter
forJTable
.Sorting is done based on the current
SortKey
s, in order. If two objects are equal (theComparator
for the column returns 0) the nextSortKey
is used. If noSortKey
s remain or the order isUNSORTED
, then the order of the rows in the model is used.Sorting of each column is done by way of a
Comparator
that you can specify using thesetComparator
method. If aComparator
has not been specified, theComparator
returned byCollator.getInstance()
is used on the results of callingtoString
on the underlying objects. TheComparator
is never passednull
. Anull
value is treated as occurring before a nonnull
value, and twonull
values are considered equal.If you specify a
Comparator
that casts its argument to a type other than that provided by the model, aClassCastException
will be thrown when the data is sorted.In addition to sorting,
DefaultRowSorter
provides the ability to filter rows. Filtering is done by way of aRowFilter
that is specified using thesetRowFilter
method. If no filter has been specified all rows are included.By default, rows are in unsorted order (the same as the model) and every column is sortable. The default
Comparator
s are documented in the subclasses (for example,TableRowSorter
).If the underlying model structure changes (the
modelStructureChanged
method is invoked) the following are reset to their default values:Comparator
s by column, current sort order, and whether each column is sortable. To find the defaultComparator
s, see the concrete implementation (for example,TableRowSorter
). The default sort order is unsorted (the same as the model), and columns are sortable by default.DefaultRowSorter
is an abstract class. Concrete subclasses must provide access to the underlying data by invokingsetModelWrapper
. ThesetModelWrapper
method must be invoked soon after the constructor is called, ideally from within the subclass's constructor. Undefined behavior will result if you use aDefaultRowSorter
without specifying aModelWrapper
.DefaultRowSorter
has two formal type parameters. The first type parameter corresponds to the class of the model, for exampleDefaultTableModel
. The second type parameter corresponds to the class of the identifier passed to theRowFilter
. Refer toTableRowSorter
andRowFilter
for more details on the type parameters. Since:
 1.6
 See Also:
TableRowSorter
,DefaultTableModel
,Collator


Nested Class Summary
Nested Classes Modifier and Type Class Description protected static class
DefaultRowSorter.ModelWrapper<M,I>
DefaultRowSorter.ModelWrapper
is responsible for providing the data that gets sorted byDefaultRowSorter
.
Nested classes/interfaces declared in class javax.swing.RowSorter
RowSorter.SortKey


Constructor Summary
Constructors Constructor Description DefaultRowSorter()
Creates an emptyDefaultRowSorter
.

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description int
convertRowIndexToModel(int index)
Returns the location ofindex
in terms of the underlying model.int
convertRowIndexToView(int index)
Returns the location ofindex
in terms of the view.Comparator<?>
getComparator(int column)
Returns theComparator
for the specified column.int
getMaxSortKeys()
Returns the maximum number of sort keys.M
getModel()
Returns the underlying model.protected DefaultRowSorter.ModelWrapper<M,I>
getModelWrapper()
Returns the model wrapper providing the data that is being sorted and filtered.RowFilter<? super M,? super I>
getRowFilter()
Returns the filter that determines which rows, if any, should be hidden from view.List<? extends RowSorter.SortKey>
getSortKeys()
Returns the current sort keys.boolean
getSortsOnUpdates()
Returns true if a sort should happen when the underlying model is updated; otherwise, returns false.boolean
isSortable(int column)
Returns true if the specified column is sortable; otherwise, false.void
rowsDeleted(int firstRow, int endRow)
Invoked when rows have been deleted from the underlying model in the specified range (inclusive).void
rowsInserted(int firstRow, int endRow)
Invoked when rows have been inserted into the underlying model in the specified range (inclusive).void
rowsUpdated(int firstRow, int endRow)
Invoked when rows have been changed in the underlying model between the specified range (inclusive).void
rowsUpdated(int firstRow, int endRow, int column)
Invoked when the column in the rows have been updated in the underlying model between the specified range.void
setComparator(int column, Comparator<?> comparator)
Sets theComparator
to use when sorting the specified column.void
setMaxSortKeys(int max)
Sets the maximum number of sort keys.protected void
setModelWrapper(DefaultRowSorter.ModelWrapper<M,I> modelWrapper)
Sets the model wrapper providing the data that is being sorted and filtered.void
setRowFilter(RowFilter<? super M,? super I> filter)
Sets the filter that determines which rows, if any, should be hidden from the view.void
setSortable(int column, boolean sortable)
Sets whether or not the specified column is sortable.void
setSortKeys(List<? extends RowSorter.SortKey> sortKeys)
Sets the sort keys.void
setSortsOnUpdates(boolean sortsOnUpdates)
If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated
is invoked).void
sort()
Sorts and filters the rows in the view based on the sort keys of the columns currently being sorted and the filter, if any, associated with this sorter.void
toggleSortOrder(int column)
Reverses the sort order from ascending to descending (or descending to ascending) if the specified column is already the primary sorted column; otherwise, makes the specified column the primary sorted column, with an ascending sort order.protected boolean
useToString(int column)
Returns whether or not to convert the value to a string before doing comparisons when sorting.
Methods declared in class javax.swing.RowSorter
addRowSorterListener, allRowsChanged, fireRowSorterChanged, fireSortOrderChanged, getModelRowCount, getViewRowCount, modelStructureChanged, removeRowSorterListener




Method Detail

setModelWrapper
protected final void setModelWrapper(DefaultRowSorter.ModelWrapper<M,I> modelWrapper)
Sets the model wrapper providing the data that is being sorted and filtered. Parameters:
modelWrapper
 the model wrapper responsible for providing the data that gets sorted and filtered Throws:
IllegalArgumentException
 ifmodelWrapper
isnull

getModelWrapper
protected final DefaultRowSorter.ModelWrapper<M,I> getModelWrapper()
Returns the model wrapper providing the data that is being sorted and filtered. Returns:
 the model wrapper responsible for providing the data that gets sorted and filtered

getModel
public final M getModel()
Returns the underlying model.

setSortable
public void setSortable(int column, boolean sortable)
Sets whether or not the specified column is sortable. The specified value is only checked whentoggleSortOrder
is invoked. It is still possible to sort on a column that has been marked as unsortable by directly setting the sort keys. The default is true. Parameters:
column
 the column to enable or disable sorting on, in terms of the underlying modelsortable
 whether or not the specified column is sortable Throws:
IndexOutOfBoundsException
 ifcolumn
is outside the range of the model See Also:
toggleSortOrder(int)
,setSortKeys(java.util.List<? extends javax.swing.RowSorter.SortKey>)

isSortable
public boolean isSortable(int column)
Returns true if the specified column is sortable; otherwise, false. Parameters:
column
 the column to check sorting for, in terms of the underlying model Returns:
 true if the column is sortable
 Throws:
IndexOutOfBoundsException
 if column is outside the range of the underlying model

setSortKeys
public void setSortKeys(List<? extends RowSorter.SortKey> sortKeys)
Sets the sort keys. This creates a copy of the suppliedList
; subsequent changes to the suppliedList
do not effect thisDefaultRowSorter
. If the sort keys have changed this triggers a sort. Specified by:
setSortKeys
in classRowSorter<M>
 Parameters:
sortKeys
 the newSortKeys
;null
is a shorthand for specifying an empty list, indicating that the view should be unsorted Throws:
IllegalArgumentException
 if any of the values insortKeys
are null or have a column index outside the range of the model

getSortKeys
public List<? extends RowSorter.SortKey> getSortKeys()
Returns the current sort keys. This returns an unmodifiablenonnull List
. If you need to change the sort keys, make a copy of the returnedList
, mutate the copy and invokesetSortKeys
with the new list. Specified by:
getSortKeys
in classRowSorter<M>
 Returns:
 the current sort order

setMaxSortKeys
public void setMaxSortKeys(int max)
Sets the maximum number of sort keys. The number of sort keys determines how equal values are resolved when sorting. For example, assume a table row sorter is created andsetMaxSortKeys(2)
is invoked on it. The user clicks the header for column 1, causing the table rows to be sorted based on the items in column 1. Next, the user clicks the header for column 2, causing the table to be sorted based on the items in column 2; if any items in column 2 are equal, then those particular rows are ordered based on the items in column 1. In this case, we say that the rows are primarily sorted on column 2, and secondarily on column 1. If the user then clicks the header for column 3, then the items are primarily sorted on column 3 and secondarily sorted on column 2. Because the maximum number of sort keys has been set to 2 withsetMaxSortKeys
, column 1 no longer has an effect on the order.The maximum number of sort keys is enforced by
toggleSortOrder
. You can specify more sort keys by invokingsetSortKeys
directly and they will all be honored. However iftoggleSortOrder
is subsequently invoked the maximum number of sort keys will be enforced. The default value is 3. Parameters:
max
 the maximum number of sort keys Throws:
IllegalArgumentException
 ifmax
< 1

getMaxSortKeys
public int getMaxSortKeys()
Returns the maximum number of sort keys. Returns:
 the maximum number of sort keys

setSortsOnUpdates
public void setSortsOnUpdates(boolean sortsOnUpdates)
If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated
is invoked). For example, if this is true and the user edits an entry the location of that item in the view may change. The default is false. Parameters:
sortsOnUpdates
 whether or not to sort on update events

getSortsOnUpdates
public boolean getSortsOnUpdates()
Returns true if a sort should happen when the underlying model is updated; otherwise, returns false. Returns:
 whether or not to sort when the model is updated

setRowFilter
public void setRowFilter(RowFilter<? super M,? super I> filter)
Sets the filter that determines which rows, if any, should be hidden from the view. The filter is applied before sorting. A value ofnull
indicates all values from the model should be included.RowFilter
'sinclude
method is passed anEntry
that wraps the underlying model. The number of columns in theEntry
corresponds to the number of columns in theModelWrapper
. The identifier comes from theModelWrapper
as well.This method triggers a sort.
 Parameters:
filter
 the filter used to determine what entries should be included

getRowFilter
public RowFilter<? super M,? super I> getRowFilter()
Returns the filter that determines which rows, if any, should be hidden from view. Returns:
 the filter

toggleSortOrder
public void toggleSortOrder(int column)
Reverses the sort order from ascending to descending (or descending to ascending) if the specified column is already the primary sorted column; otherwise, makes the specified column the primary sorted column, with an ascending sort order. If the specified column is not sortable, this method has no effect. Specified by:
toggleSortOrder
in classRowSorter<M>
 Parameters:
column
 index of the column to make the primary sorted column, in terms of the underlying model Throws:
IndexOutOfBoundsException
 if column is outside the range of the underlying model See Also:
setSortable(int,boolean)
,setMaxSortKeys(int)

convertRowIndexToView
public int convertRowIndexToView(int index)
Returns the location ofindex
in terms of the view. That is, for the rowindex
in the coordinates of the underlying model this returns the row index in terms of the view. Specified by:
convertRowIndexToView
in classRowSorter<M>
 Parameters:
index
 the row index in terms of the underlying model Returns:
 row index in terms of the view, or 1 if index has been filtered out of the view
 Throws:
IndexOutOfBoundsException
 ifindex
is outside the range of the model

convertRowIndexToModel
public int convertRowIndexToModel(int index)
Returns the location ofindex
in terms of the underlying model. That is, for the rowindex
in the coordinates of the view this returns the row index in terms of the underlying model. Specified by:
convertRowIndexToModel
in classRowSorter<M>
 Parameters:
index
 the row index in terms of the underlying view Returns:
 row index in terms of the view
 Throws:
IndexOutOfBoundsException
 ifindex
is outside the range of the view

sort
public void sort()
Sorts and filters the rows in the view based on the sort keys of the columns currently being sorted and the filter, if any, associated with this sorter. An emptysortKeys
list indicates that the view should unsorted, the same as the model.

useToString
protected boolean useToString(int column)
Returns whether or not to convert the value to a string before doing comparisons when sorting. If trueModelWrapper.getStringValueAt
will be used, otherwiseModelWrapper.getValueAt
will be used. It is up to subclasses, such asTableRowSorter
, to honor this value in theirModelWrapper
implementation. Parameters:
column
 the index of the column to test, in terms of the underlying model Returns:
 true if values are to be converted to strings before doing comparisons when sorting
 Throws:
IndexOutOfBoundsException
 ifcolumn
is not valid

setComparator
public void setComparator(int column, Comparator<?> comparator)
Sets theComparator
to use when sorting the specified column. This does not trigger a sort. If you want to sort after setting the comparator you need to explicitly invokesort
. Parameters:
column
 the index of the column theComparator
is to be used for, in terms of the underlying modelcomparator
 theComparator
to use Throws:
IndexOutOfBoundsException
 ifcolumn
is outside the range of the underlying model

getComparator
public Comparator<?> getComparator(int column)
Returns theComparator
for the specified column. This will returnnull
if aComparator
has not been specified for the column. Parameters:
column
 the column to fetch theComparator
for, in terms of the underlying model Returns:
 the
Comparator
for the specified column  Throws:
IndexOutOfBoundsException
 if column is outside the range of the underlying model

rowsInserted
public void rowsInserted(int firstRow, int endRow)
Invoked when rows have been inserted into the underlying model in the specified range (inclusive).The arguments give the indices of the effected range. The first argument is in terms of the model before the change, and must be less than or equal to the size of the model before the change. The second argument is in terms of the model after the change and must be less than the size of the model after the change. For example, if you have a 5row model and add 3 items to the end of the model the indices are 5, 7.
You normally do not call this method. This method is public to allow view classes to call it.
 Specified by:
rowsInserted
in classRowSorter<M>
 Parameters:
firstRow
 the first rowendRow
 the last row Throws:
IndexOutOfBoundsException
 if either argument is invalid, orfirstRow
>endRow

rowsDeleted
public void rowsDeleted(int firstRow, int endRow)
Invoked when rows have been deleted from the underlying model in the specified range (inclusive).The arguments give the indices of the effected range and are in terms of the model before the change. For example, if you have a 5row model and delete 3 items from the end of the model the indices are 2, 4.
You normally do not call this method. This method is public to allow view classes to call it.
 Specified by:
rowsDeleted
in classRowSorter<M>
 Parameters:
firstRow
 the first rowendRow
 the last row Throws:
IndexOutOfBoundsException
 if either argument is outside the range of the model before the change, orfirstRow
>endRow

rowsUpdated
public void rowsUpdated(int firstRow, int endRow)
Invoked when rows have been changed in the underlying model between the specified range (inclusive).You normally do not call this method. This method is public to allow view classes to call it.
 Specified by:
rowsUpdated
in classRowSorter<M>
 Parameters:
firstRow
 the first row, in terms of the underlying modelendRow
 the last row, in terms of the underlying model Throws:
IndexOutOfBoundsException
 if either argument is outside the range of the underlying model, orfirstRow
>endRow

rowsUpdated
public void rowsUpdated(int firstRow, int endRow, int column)
Invoked when the column in the rows have been updated in the underlying model between the specified range.You normally do not call this method. This method is public to allow view classes to call it.
 Specified by:
rowsUpdated
in classRowSorter<M>
 Parameters:
firstRow
 the first row, in terms of the underlying modelendRow
 the last row, in terms of the underlying modelcolumn
 the column that has changed, in terms of the underlying model Throws:
IndexOutOfBoundsException
 if either argument is outside the range of the underlying model after the change,firstRow
>endRow
, orcolumn
is outside the range of the underlying model

