TableRowSorter

Class Overview

An implementation of RowSorter that provides sorting and filtering using a TableModel. The following example shows adding sorting to a JTable:

   TableModel myModel = createMyTableModel();
   JTable table = new JTable(myModel);
   table.setRowSorter(new TableRowSorter(myModel));
 

This will do all the wiring such that when the user does the appropriate gesture, such as clicking on the column header, the table will visually sort.

JTable's row-based methods and JTable's selection model refer to the view and not the underlying model. Therefore, it is necessary to convert between the two. For example, to get the selection in terms of myModel you need to convert the indices:

   int[] selection = table.getSelectedRows();
   for (int i = 0; i < selection.length; i++) {
     selection[i] = table.convertRowIndexToModel(selection[i]);
   }
 

Similarly to select a row in JTable based on a coordinate from the underlying model do the inverse:

   table.setRowSelectionInterval(table.convertRowIndexToView(row),
                                 table.convertRowIndexToView(row));
 

The previous example assumes you have not enabled filtering. If you have enabled filtering convertRowIndexToView will return -1 for locations that are not visible in the view.

TableRowSorter uses Comparators for doing comparisons. The following defines how a Comparator is chosen for a column:

1. If a Comparator has been specified for the column by the setComparator method, use it.
2. If the column class as returned by getColumnClass is String, use the Comparator returned by Collator.getInstance().
3. If the column class implements Comparable, use a Comparator that invokes the compareTo method.
4. If a TableStringConverter has been specified, use it to convert the values to Strings and then use the Comparator returned by Collator.getInstance().
5. Otherwise use the Comparator returned by Collator.getInstance() on the results from calling toString on the objects.

In addition to sorting TableRowSorter provides the ability to filter. A filter is specified using the setFilter method. The following example will only show rows containing the string "foo":

   TableModel myModel = createMyTableModel();
   TableRowSorter sorter = new TableRowSorter(myModel);
   sorter.setRowFilter(RowFilter.regexFilter(".*foo.*"));
   JTable table = new JTable(myModel);
   table.setRowSorter(sorter);
 

If the underlying model structure changes (the modelStructureChanged method is invoked) the following are reset to their default values: Comparators by column, current sort order, and whether each column is sortable. The default sort order is natural (the same as the model), and columns are sortable by default.

TableRowSorter has one formal type parameter: the type of the model. Passing in a type that corresponds exactly to your model allows you to filter based on your model without casting. Refer to the documentation of RowFilter for an example of this.

WARNING: DefaultTableModel returns a column class of Object. As such all comparisons will be done using toString. This may be unnecessarily expensive. If the column only contains one type of value, such as an Integer, you should override getColumnClass and return the appropriate Class. This will dramatically increase the performance of this class.

Summary

Public Constructors
	TableRowSorter() Creates a TableRowSorter with an empty model.
	TableRowSorter(M model) Creates a TableRowSorter using model as the underlying TableModel.

Public Methods
Comparator<?>	getComparator(int column) Returns the Comparator for the specified column.
TableStringConverter	getStringConverter() Returns the object responsible for converting values from the model to strings.
void	setModel(M model) Sets the TableModel to use as the underlying model for this TableRowSorter.
void	setStringConverter(TableStringConverter stringConverter) Sets the object responsible for converting values from the model to strings.

Protected Methods
boolean	useToString(int column) Returns whether or not to convert the value to a string before doing comparisons when sorting.

[Expand] Inherited Methods
From class javax.swing.DefaultRowSorter 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. final M getModel() Returns the underlying model. int getModelRowCount() Returns the number of rows in the underlying model. final 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, int column) Invoked when the column in the rows have been updated in the underlying model between the specified range. void rowsUpdated(int firstRow, int endRow) Invoked when rows have been changed in the underlying model between the specified range (inclusive). 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. final void setModelWrapper(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 setSortKeys(List<? extends RowSorter.SortKey> sortKeys) Sets the sort keys. void setSortable(int column, boolean sortable) Sets whether or not the specified column is sortable. 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. boolean useToString(int column) Returns whether or not to convert the value to a string before doing comparisons when sorting.
From class javax.swing.RowSorter void addRowSorterListener(RowSorterListener l) Adds a RowSorterListener to receive notification about this RowSorter. abstract void allRowsChanged() Invoked when the contents of the underlying model have completely changed. abstract int convertRowIndexToModel(int index) Returns the location of index in terms of the underlying model. abstract int convertRowIndexToView(int index) Returns the location of index in terms of the view. void fireRowSorterChanged(int[] lastRowIndexToModel) Notifies listener that the mapping has changed. void fireSortOrderChanged() Notifies listener that the sort order has changed. abstract M getModel() Returns the underlying model. abstract int getModelRowCount() Returns the number of rows in the underlying model. abstract List<? extends RowSorter.SortKey> getSortKeys() Returns the current sort keys. abstract int getViewRowCount() Returns the number of rows in the view. abstract void modelStructureChanged() Invoked when the underlying model structure has completely changed. void removeRowSorterListener(RowSorterListener l) Removes a RowSorterListener. abstract void rowsDeleted(int firstRow, int endRow) Invoked when rows have been deleted from the underlying model in the specified range (inclusive). abstract void rowsInserted(int firstRow, int endRow) Invoked when rows have been inserted into the underlying model in the specified range (inclusive). abstract 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. abstract void rowsUpdated(int firstRow, int endRow) Invoked when rows have been changed in the underlying model between the specified range (inclusive). abstract void setSortKeys(List<? extends RowSorter.SortKey> keys) Sets the current sort keys. abstract void toggleSortOrder(int column) Reverses the sort order of the specified column.
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object. final void wait(long timeout, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long timeout) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed.