M
 the type of the modelI
 the type of the identifier passed to the RowFilter
public abstract class DefaultRowSorter<M,I> extends RowSorter<M>
RowSorter
that provides sorting and
filtering around a gridbased data model.
Beyond creating and installing a RowSorter
, you very rarely
need to interact with one directly. Refer to
TableRowSorter
for a concrete
implementation of RowSorter
for JTable
.
Sorting is done based on the current SortKey
s, in order.
If two objects are equal (the Comparator
for the
column returns 0) the next SortKey
is used. If no
SortKey
s remain or the order is UNSORTED
, 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 the setComparator
method.
If a Comparator
has not been specified, the
Comparator
returned by
Collator.getInstance()
is used on the results of
calling toString
on the underlying objects. The
Comparator
is never passed null
. A
null
value is treated as occuring before a
nonnull
value, and two null
values are
considered equal.
If you specify a Comparator
that casts its argument to
a type other than that provided by the model, a
ClassCastException
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 a
RowFilter
that is specified using the
setRowFilter
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 default Comparator
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.
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 a column is sortable.
DefaultRowSorter
is an abstract class. Concrete
subclasses must provide access to the underlying data by invoking
setModelWrapper
. The setModelWrapper
method
must be invoked soon after the constructor is
called, ideally from within the subclass's constructor.
Undefined behavior will result if you use a DefaultRowSorter
without specifying a ModelWrapper
.
DefaultRowSorter
has two formal type parameters. The
first type parameter corresponds to the class of the model, for example
DefaultTableModel
. The second type parameter
corresponds to the class of the identifier passed to the
RowFilter
. Refer to TableRowSorter
and
RowFilter
for more details on the type parameters.
TableRowSorter
,
DefaultTableModel
,
Collator
Modifier and Type  Class and Description 

protected static class 
DefaultRowSorter.ModelWrapper<M,I>
DefaultRowSorter.ModelWrapper is responsible for providing
the data that gets sorted by DefaultRowSorter . 
RowSorter.SortKey
Constructor and Description 

DefaultRowSorter()
Creates an empty
DefaultRowSorter . 
Modifier and Type  Method and Description 

void 
allRowsChanged()
Invoked when the contents of the underlying model have
completely changed.

int 
convertRowIndexToModel(int index)
Returns the location of
index in terms of the
underlying model. 
int 
convertRowIndexToView(int index)
Returns the location of
index in terms of the
view. 
Comparator<?> 
getComparator(int column)
Returns the
Comparator for the specified
column. 
int 
getMaxSortKeys()
Returns the maximum number of sort keys.

M 
getModel()
Returns the underlying model.

int 
getModelRowCount()
Returns the number of rows in 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.

int 
getViewRowCount()
Returns the number of rows in the view.

boolean 
isSortable(int column)
Returns true if the specified column is sortable; otherwise, false.

void 
modelStructureChanged()
Invoked when the underlying model structure has completely
changed.

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 the
Comparator 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.

addRowSorterListener, fireRowSorterChanged, fireSortOrderChanged, removeRowSorterListener
protected final void setModelWrapper(DefaultRowSorter.ModelWrapper<M,I> modelWrapper)
modelWrapper
 the model wrapper responsible for providing the
data that gets sorted and filteredIllegalArgumentException
 if modelWrapper
is
null
protected final DefaultRowSorter.ModelWrapper<M,I> getModelWrapper()
public final M getModel()
public void setSortable(int column, boolean sortable)
toggleSortOrder
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.column
 the column to enable or disable sorting on, in terms
of the underlying modelsortable
 whether or not the specified column is sortableIndexOutOfBoundsException
 if column
is outside
the range of the modeltoggleSortOrder(int)
,
setSortKeys(java.util.List<? extends javax.swing.RowSorter.SortKey>)
public boolean isSortable(int column)
column
 the column to check sorting for, in terms of the
underlying modelIndexOutOfBoundsException
 if column is outside
the range of the underlying modelpublic void setSortKeys(List<? extends RowSorter.SortKey> sortKeys)
List
; subsequent changes to the supplied
List
do not effect this DefaultRowSorter
.
If the sort keys have changed this triggers a sort.setSortKeys
in class RowSorter<M>
sortKeys
 the new SortKeys
; null
is a shorthand for specifying an empty list,
indicating that the view should be unsortedIllegalArgumentException
 if any of the values in
sortKeys
are null or have a column index outside
the range of the modelpublic List<? extends RowSorter.SortKey> getSortKeys()
nonnull List
. If you need to change the sort keys,
make a copy of the returned List
, mutate the copy
and invoke setSortKeys
with the new list.getSortKeys
in class RowSorter<M>
public void setMaxSortKeys(int max)
setMaxSortKeys(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
with setMaxSortKeys
, 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 invoking setSortKeys
directly and they will
all be honored. However if toggleSortOrder
is subsequently
invoked the maximum number of sort keys will be enforced.
The default value is 3.
max
 the maximum number of sort keysIllegalArgumentException
 if max
< 1public int getMaxSortKeys()
public void setSortsOnUpdates(boolean sortsOnUpdates)
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.sortsOnUpdates
 whether or not to sort on update eventspublic boolean getSortsOnUpdates()
public void setRowFilter(RowFilter<? super M,? super I> filter)
null
indicates all values from the model should be
included.
RowFilter
's include
method is passed an
Entry
that wraps the underlying model. The number
of columns in the Entry
corresponds to the
number of columns in the ModelWrapper
. The identifier
comes from the ModelWrapper
as well.
This method triggers a sort.
filter
 the filter used to determine what entries should be
includedpublic RowFilter<? super M,? super I> getRowFilter()
public void toggleSortOrder(int column)
toggleSortOrder
in class RowSorter<M>
column
 index of the column to make the primary sorted column,
in terms of the underlying modelIndexOutOfBoundsException
 if column is outside the range of
the underlying modelsetSortable(int,boolean)
,
setMaxSortKeys(int)
public int convertRowIndexToView(int index)
index
in terms of the
view. That is, for the row index
in the
coordinates of the underlying model this returns the row index
in terms of the view.convertRowIndexToView
in class RowSorter<M>
index
 the row index in terms of the underlying modelIndexOutOfBoundsException
 if index
is outside
the range of the modelpublic int convertRowIndexToModel(int index)
index
in terms of the
underlying model. That is, for the row index
in
the coordinates of the view this returns the row index in terms
of the underlying model.convertRowIndexToModel
in class RowSorter<M>
index
 the row index in terms of the underlying viewIndexOutOfBoundsException
 if index
is outside the
range of the viewpublic void sort()
sortKeys
list
indicates that the view should unsorted, the same as the model.protected boolean useToString(int column)
ModelWrapper.getStringValueAt
will be used, otherwise
ModelWrapper.getValueAt
will be used. It is up to
subclasses, such as TableRowSorter
, to honor this value
in their ModelWrapper
implementation.column
 the index of the column to test, in terms of the
underlying modelIndexOutOfBoundsException
 if column
is not validpublic void setComparator(int column, Comparator<?> comparator)
Comparator
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 invoke sort
.column
 the index of the column the Comparator
is
to be used for, in terms of the underlying modelcomparator
 the Comparator
to useIndexOutOfBoundsException
 if column
is outside
the range of the underlying modelpublic Comparator<?> getComparator(int column)
Comparator
for the specified
column. This will return null
if a Comparator
has not been specified for the column.column
 the column to fetch the Comparator
for, in
terms of the underlying modelComparator
for the specified columnIndexOutOfBoundsException
 if column is outside
the range of the underlying modelpublic int getViewRowCount()
getViewRowCount
in class RowSorter<M>
RowSorter.getModelRowCount()
public int getModelRowCount()
getModelRowCount
in class RowSorter<M>
RowSorter.getViewRowCount()
public void modelStructureChanged()
TableModel
changed, this method would be invoked.
You normally do not call this method. This method is public to allow view classes to call it.
modelStructureChanged
in class RowSorter<M>
public void allRowsChanged()
You normally do not call this method. This method is public to allow view classes to call it.
allRowsChanged
in class RowSorter<M>
public void rowsInserted(int firstRow, int endRow)
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.
rowsInserted
in class RowSorter<M>
firstRow
 the first rowendRow
 the last rowIndexOutOfBoundsException
 if either argument is invalid, or
firstRow
> endRow
public void rowsDeleted(int firstRow, int endRow)
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.
rowsDeleted
in class RowSorter<M>
firstRow
 the first rowendRow
 the last rowIndexOutOfBoundsException
 if either argument is outside
the range of the model before the change, or
firstRow
> endRow
public void rowsUpdated(int firstRow, int endRow)
You normally do not call this method. This method is public to allow view classes to call it.
rowsUpdated
in class RowSorter<M>
firstRow
 the first row, in terms of the underlying modelendRow
 the last row, in terms of the underlying modelIndexOutOfBoundsException
 if either argument is outside
the range of the underlying model, or
firstRow
> endRow
public void rowsUpdated(int firstRow, int endRow, int column)
You normally do not call this method. This method is public to allow view classes to call it.
rowsUpdated
in class RowSorter<M>
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
modelIndexOutOfBoundsException
 if either argument is outside
the range of the underlying model after the change,
firstRow
> endRow
, or
column
is outside the range of the underlying
model
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developertargeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.
DRAFT eab92