Module java.desktop
Package javax.swing.table

# Class TableRowSorter<M extends TableModel>

java.lang.Object
javax.swing.RowSorter<M>
javax.swing.DefaultRowSorter<M,Integer>
javax.swing.table.TableRowSorter<M>

Type Parameters:
  `M` - the type of the model, which must be an implementation of `TableModel`

public class TableRowSorter<M extends TableModel> extends DefaultRowSorter<M,Integer>
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 `Comparator`s 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 `String`s 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: `Comparator`s 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.

Since:
  1.6
See Also:
  - `JTable`
  - `RowFilter`
  - `DefaultTableModel`
  - `Collator`
  - `Comparator`

## Nested Class Summary

## Nested classes/interfaces declared in class javax.swing.DefaultRowSorter

`DefaultRowSorter.ModelWrapper<M,I>`

## Nested classes/interfaces declared in class javax.swing.RowSorter

`RowSorter.SortKey`

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`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 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.DefaultRowSorter

`allRowsChanged, convertRowIndexToModel, convertRowIndexToView, getMaxSortKeys, getModel, getModelRowCount, getModelWrapper, getRowFilter, getSortKeys, getSortsOnUpdates, getViewRowCount, isSortable, modelStructureChanged, rowsDeleted, rowsInserted, rowsUpdated, rowsUpdated, setComparator, setMaxSortKeys, setModelWrapper, setRowFilter, setSortable, setSortKeys, setSortsOnUpdates, sort, toggleSortOrder`

### Methods declared in class javax.swing.RowSorter

`addRowSorterListener, fireRowSorterChanged, fireSortOrderChanged, removeRowSorterListener`

### Methods declared in class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### TableRowSorter

public TableRowSorter()
Creates a `TableRowSorter` with an empty model.

### TableRowSorter

public TableRowSorter(M model)
Creates a `TableRowSorter` using `model` as the underlying `TableModel`.

Parameters:
  `model` - the underlying `TableModel` to use, `null` is treated as an empty model

## Method Details

### setModel

public void setModel(M model)
Sets the `TableModel` to use as the underlying model for this `TableRowSorter`. A value of `null` can be used to set an empty model.

Parameters:
  `model` - the underlying model to use, or `null`

### setStringConverter

public void setStringConverter(TableStringConverter stringConverter)
Sets the object responsible for converting values from the model to strings. If non-`null` this is used to convert any object values, that do not have a registered `Comparator`, to strings.

Parameters:
  `stringConverter` - the object responsible for converting values from the model to strings

### getStringConverter

public TableStringConverter getStringConverter()
Returns the object responsible for converting values from the model to strings.

Returns:
  object responsible for converting values to strings.

### getComparator

public Comparator<?> getComparator(int column)
Returns the `Comparator` for the specified column. If a `Comparator` has not been specified using the `setComparator` method a `Comparator` will be returned based on the column class (`TableModel.getColumnClass`) of the specified column. If the column class is `String`, `Collator.getInstance` is returned. If the column class implements `Comparable` a private `Comparator` is returned that invokes the `compareTo` method. Otherwise `Collator.getInstance` is returned.

Overrides:
  `getComparator` in class `DefaultRowSorter<M extends TableModel,Integer>`
Parameters:
  `column` - the column to fetch the `Comparator` 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

### useToString

protected boolean useToString(int column)
Returns whether or not to convert the value to a string before doing comparisons when sorting. If true `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.

Overrides:
  `useToString` in class `DefaultRowSorter<M extends TableModel,Integer>`
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` - if `column` is not valid