RowSorter provides the basis for sorting and filtering. 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.

RowSorter's primary role is to provide a mapping between two coordinate systems: that of the view (for example a JTable) and that of the underlying data source, typically a model.

The view invokes the following methods on the RowSorter:

toggleSortOrder — The view invokes this when the appropriate user gesture has occurred to trigger a sort. For example, the user clicked a column header in a table.
One of the model change methods — The view invokes a model change method when the underlying model has changed. There may be order dependencies in how the events are delivered, so a RowSorter should not update its mapping until one of these methods is invoked.

Because the view makes extensive use of the convertRowIndexToModel, convertRowIndexToView and getViewRowCount methods, these methods need to be fast.

RowSorter provides notification of changes by way of RowSorterListener. Two types of notification are sent:

RowSorterEvent.Type.SORT_ORDER_CHANGED — notifies listeners that the sort order has changed. This is typically followed by a notification that the sort has changed.
RowSorterEvent.Type.SORTED — notifies listeners that the mapping maintained by the RowSorter has changed in some way.

RowSorter implementations typically don't have a one-to-one mapping with the underlying model, but they can. For example, if a database does the sorting, toggleSortOrder might call through to the database (on a background thread), and override the mapping methods to return the argument that is passed in.

Concrete implementations of RowSorter need to reference a model such as TableModel or ListModel. The view classes, such as JTable and JList, will also have a reference to the model. To avoid ordering dependencies, RowSorter implementations should not install a listener on the model. Instead the view class will call into the RowSorter when the model changes. For example, if a row is updated in a TableModel JTable invokes rowsUpdated. When the model changes, the view may call into any of the following methods: modelStructureChanged, allRowsChanged, rowsInserted, rowsDeleted and rowsUpdated.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	RowSorter.SortKey SortKey describes the sort order for a particular column.

Modifier and Type	Field and Description
private EventListenerList	listenerList

Constructor Summary

Access	Constructor and Description
public	RowSorter() Creates a `RowSorter`.

Method Summary

Modifier and Type	Method and Description
public void	addRowSorterListener(RowSorterListener the `RowSorterListener` l) Adds a `RowSorterListener` to receive notification about this `RowSorter`.
public abstract void	allRowsChanged() Invoked when the contents of the underlying model have completely changed.
public abstract int	Returns: row index in terms of the view convertRowIndexToModel(int the row index in terms of the underlying view index) Returns the location of `index` in terms of the underlying model.
public abstract int	Returns: row index in terms of the view, or -1 if index has been filtered out of the view convertRowIndexToView(int the row index in terms of the underlying model index) Returns the location of `index` in terms of the view.
protected void	fireRowSorterChanged(int[] the mapping from model indices to view indices prior to the sort, may be `null` lastRowIndexToModel) Notifies listener that the mapping has changed.
pack-priv void	fireRowSorterChanged(RowSorterEvent event)
protected void	fireSortOrderChanged() Notifies listener that the sort order has changed.
public abstract M	Returns: the underlying model getModel() Returns the underlying model.
public abstract int	Returns: number of rows in the underlying model getModelRowCount() Returns the number of rows in the underlying model.
public abstract List<? extends RowSorter.SortKey>	Returns: the current sort order getSortKeys() Returns the current sort keys.
public abstract int	Returns: number of rows in the view getViewRowCount() Returns the number of rows in the view.
public abstract void	modelStructureChanged() Invoked when the underlying model structure has completely changed.
public void	removeRowSorterListener(RowSorterListener the `RowSorterListener` l) Removes a `RowSorterListener`.
public abstract void	rowsDeleted(int the first row firstRow, int the last row endRow) Invoked when rows have been deleted from the underlying model in the specified range (inclusive).
public abstract void	rowsInserted(int the first row firstRow, int the last row endRow) Invoked when rows have been inserted into the underlying model in the specified range (inclusive).
public abstract void	rowsUpdated(int the first row, in terms of the underlying model firstRow, int the last row, in terms of the underlying model endRow) Invoked when rows have been changed in the underlying model between the specified range (inclusive).
public abstract void	rowsUpdated(int the first row, in terms of the underlying model firstRow, int the last row, in terms of the underlying model endRow, int the column that has changed, in terms of the underlying model column) Invoked when the column in the rows have been updated in the underlying model between the specified range.
public abstract void	setSortKeys(List<? extends RowSorter.SortKey> the new `SortKeys`; `null` is a shorthand for specifying an empty list, indicating that the view should be unsorted keys) Sets the current sort keys.
public abstract void	toggleSortOrder(int the column to toggle the sort ordering of, in terms of the underlying model column) Reverses the sort order of the specified column.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

listenerList	back to summary
private EventListenerList listenerList

Constructor Detail

RowSorter	back to summary
public RowSorter() Creates a `RowSorter`.

Method Detail

addRowSorterListener back to summary

addRowSorterListener	back to summary
public void addRowSorterListener(RowSorterListener l) Adds a `RowSorterListener` to receive notification about this `RowSorter`. If the same listener is added more than once it will receive multiple notifications. If `l` is `null` nothing is done. Parameters l:RowSorterListener the `RowSorterListener`

public void addRowSorterListener(RowSorterListener l)

Adds a RowSorterListener to receive notification about this RowSorter. If the same listener is added more than once it will receive multiple notifications. If l is null nothing is done.

Parameters

l:RowSorterListener: the RowSorterListener

allRowsChanged	back to summary
public abstract void allRowsChanged() Invoked when the contents of the underlying model have completely changed. The structure of the table is the same, only the contents have changed. This is typically sent when it is too expensive to characterize the change in terms of the other methods. You normally do not call this method. This method is public to allow view classes to call it.

allRowsChanged

back to summary

public abstract void allRowsChanged()

Invoked when the contents of the underlying model have completely changed. The structure of the table is the same, only the contents have changed. This is typically sent when it is too expensive to characterize the change in terms of the other methods.

You normally do not call this method. This method is public to allow view classes to call it.

convertRowIndexToModel back to summary

convertRowIndexToModel	back to summary
public abstract int convertRowIndexToModel(int index) Returns the location of `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. Parameters index:int the row index in terms of the underlying view Returns:int row index in terms of the view Exceptions IndexOutOfBoundsException: if `index` is outside the range of the view

public abstract int convertRowIndexToModel(int index)

Returns the location of 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.

Parameters

index:int: the row index in terms of the underlying view

Returns:int

row index in terms of the view

Exceptions

IndexOutOfBoundsException:: if index is outside the range of the view

convertRowIndexToView back to summary

convertRowIndexToView	back to summary
public abstract int convertRowIndexToView(int index) Returns the location of `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. Parameters index:int the row index in terms of the underlying model Returns:int row index in terms of the view, or -1 if index has been filtered out of the view Exceptions IndexOutOfBoundsException: if `index` is outside the range of the model

public abstract int convertRowIndexToView(int index)

Returns the location of 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.

Parameters

index:int: the row index in terms of the underlying model

Returns:int

row index in terms of the view, or -1 if index has been filtered out of the view

Exceptions

IndexOutOfBoundsException:: if index is outside the range of the model

fireRowSorterChanged back to summary

fireRowSorterChanged	back to summary
protected void fireRowSorterChanged(int[] lastRowIndexToModel) Notifies listener that the mapping has changed. Parameters lastRowIndexToModel:int[] the mapping from model indices to view indices prior to the sort, may be `null`

protected void fireRowSorterChanged(int[] lastRowIndexToModel)

Notifies listener that the mapping has changed.

Parameters

lastRowIndexToModel:int[]: the mapping from model indices to view indices prior to the sort, may be null

fireRowSorterChanged	back to summary
pack-priv void fireRowSorterChanged(RowSorterEvent event)

fireSortOrderChanged	back to summary
protected void fireSortOrderChanged() Notifies listener that the sort order has changed.

getModel	back to summary
public abstract M getModel() Returns the underlying model. Returns:M the underlying model

getModel

back to summary

public abstract M getModel()

Returns the underlying model.

Returns:M: the underlying model

getModelRowCount back to summary

getModelRowCount	back to summary
public abstract int getModelRowCount() Returns the number of rows in the underlying model. Returns:int number of rows in the underlying model See Also `getViewRowCount`

public abstract int getModelRowCount()

Returns the number of rows in the underlying model.

Returns:int: number of rows in the underlying model
See Also: getViewRowCount

getSortKeys back to summary

getSortKeys	back to summary
public abstract List<? extends RowSorter.SortKey> getSortKeys() Returns the current sort keys. This must return a `non-null List` and may return an unmodifiable `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. Returns:List<? extends RowSorter.SortKey> the current sort order

public abstract List<? extends RowSorter.SortKey> getSortKeys()

Returns the current sort keys. This must return a non-null List and may return an unmodifiable 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.

Returns:List<? extends RowSorter.SortKey>: the current sort order

getViewRowCount back to summary

getViewRowCount	back to summary
public abstract int getViewRowCount() Returns the number of rows in the view. If the contents have been filtered this might differ from the row count of the underlying model. Returns:int number of rows in the view See Also `getModelRowCount`

public abstract int getViewRowCount()

Returns the number of rows in the view. If the contents have been filtered this might differ from the row count of the underlying model.

Returns:int: number of rows in the view
See Also: getModelRowCount

modelStructureChanged back to summary

modelStructureChanged	back to summary
public abstract void modelStructureChanged() Invoked when the underlying model structure has completely changed. For example, if the number of columns in a `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.

public abstract void modelStructureChanged()

Invoked when the underlying model structure has completely changed. For example, if the number of columns in a 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.

removeRowSorterListener back to summary

removeRowSorterListener	back to summary
public void removeRowSorterListener(RowSorterListener l) Removes a `RowSorterListener`. If `l` is `null` nothing is done. Parameters l:RowSorterListener the `RowSorterListener`

public void removeRowSorterListener(RowSorterListener l)

Removes a RowSorterListener. If l is null nothing is done.

Parameters

l:RowSorterListener: the RowSorterListener

rowsDeleted back to summary

rowsDeleted	back to summary
public abstract 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 5-row 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. Parameters firstRow:int the first row endRow:int the last row Exceptions IndexOutOfBoundsException: if either argument is outside the range of the model before the change, or `firstRow` > `endRow`

public abstract 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 5-row 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.

Parameters

firstRow:int: the first row
endRow:int: the last row

Exceptions

IndexOutOfBoundsException:: if either argument is outside the range of the model before the change, or firstRow > endRow

rowsInserted back to summary

rowsInserted	back to summary
public abstract 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 5-row 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. Parameters firstRow:int the first row endRow:int the last row Exceptions IndexOutOfBoundsException: if either argument is invalid, or `firstRow` > `endRow`

public abstract 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 5-row 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.

Parameters

firstRow:int: the first row
endRow:int: the last row

Exceptions

IndexOutOfBoundsException:: if either argument is invalid, or firstRow > endRow

rowsUpdated back to summary

rowsUpdated	back to summary
public abstract 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. Parameters firstRow:int the first row, in terms of the underlying model endRow:int the last row, in terms of the underlying model Exceptions IndexOutOfBoundsException: if either argument is outside the range of the underlying model, or `firstRow` > `endRow`

public abstract 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.

Parameters

firstRow:int: the first row, in terms of the underlying model
endRow:int: the last row, in terms of the underlying model

Exceptions

IndexOutOfBoundsException:: if either argument is outside the range of the underlying model, or firstRow > endRow

rowsUpdated back to summary

rowsUpdated	back to summary
public 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. You normally do not call this method. This method is public to allow view classes to call it. Parameters firstRow:int the first row, in terms of the underlying model endRow:int the last row, in terms of the underlying model column:int the column that has changed, in terms of the underlying model Exceptions IndexOutOfBoundsException: 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

public 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.

You normally do not call this method. This method is public to allow view classes to call it.

Parameters

firstRow:int: the first row, in terms of the underlying model
endRow:int: the last row, in terms of the underlying model
column:int: the column that has changed, in terms of the underlying model

Exceptions

IndexOutOfBoundsException:: 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

setSortKeys back to summary

setSortKeys	back to summary
public abstract void setSortKeys(List<? extends RowSorter.SortKey> keys) Sets the current sort keys. Parameters keys:List<? extends RowSorter.SortKey> the new `SortKeys`; `null` is a shorthand for specifying an empty list, indicating that the view should be unsorted

public abstract void setSortKeys(List<? extends RowSorter.SortKey> keys)

Sets the current sort keys.

Parameters

keys:List<? extends RowSorter.SortKey>: the new SortKeys; null is a shorthand for specifying an empty list, indicating that the view should be unsorted

toggleSortOrder back to summary

toggleSortOrder	back to summary
public abstract void toggleSortOrder(int column) Reverses the sort order of the specified column. It is up to subclasses to provide the exact behavior when invoked. Typically this will reverse 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. If this results in changing the sort order and sorting, the appropriate `RowSorterListener` notification will be sent. Parameters column:int the column to toggle the sort ordering of, in terms of the underlying model Exceptions IndexOutOfBoundsException: if column is outside the range of the underlying model

public abstract void toggleSortOrder(int column)

Reverses the sort order of the specified column. It is up to subclasses to provide the exact behavior when invoked. Typically this will reverse 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.

If this results in changing the sort order and sorting, the appropriate RowSorterListener notification will be sent.

Parameters

column:int: the column to toggle the sort ordering of, in terms of the underlying model

Exceptions

IndexOutOfBoundsException:: if column is outside the range of the underlying model

javax.swing back to summary

public Class RowSorter.SortKey

Class Inheritance

extends Object

java.lang.Object
javax.swing.RowSorter.SortKey

SortKey describes the sort order for a particular column. The column index is in terms of the underlying model, which may differ from that of the view.

Since: 1.6

Field Summary

Modifier and Type	Field and Description
private int	column
private SortOrder	sortOrder

Constructor Summary

Access	Constructor and Description
public	SortKey(int index of the column, in terms of the model column, SortOrder the sorter order sortOrder) Creates a `SortKey` for the specified column with the specified sort order.

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: true if `o` is equal to this `SortKey` equals(Object the object to compare to o) Overrides java.lang.Object.equals. Returns true if this object equals the specified object.
public final int	Returns: index of column getColumn() Returns the index of the column.
public final SortOrder	Returns: the sort order of the column getSortOrder() Returns the sort order of the column.
public int	Returns: hash code hashCode() Overrides java.lang.Object.hashCode. Returns the hash code for this `SortKey`.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll toString wait wait wait

Field Detail

column	back to summary
private int column

sortOrder	back to summary
private SortOrder sortOrder

Constructor Detail

SortKey back to summary

SortKey	back to summary
public SortKey(int column, SortOrder sortOrder) Creates a `SortKey` for the specified column with the specified sort order. Parameters column:int index of the column, in terms of the model sortOrder:SortOrder the sorter order Exceptions IllegalArgumentException: if `sortOrder` is `null`

public SortKey(int column, SortOrder sortOrder)

Creates a SortKey for the specified column with the specified sort order.

Parameters

column:int: index of the column, in terms of the model
sortOrder:SortOrder: the sorter order

Exceptions

IllegalArgumentException:: if sortOrder is null

Method Detail

equals back to summary

equals	back to summary
public boolean equals(Object o) Overrides java.lang.Object.equals. Returns true if this object equals the specified object. If the specified object is a `SortKey` and references the same column and sort order, the two objects are equal. Parameters o:Object the object to compare to Returns:boolean true if `o` is equal to this `SortKey`

public boolean equals(Object o)

Overrides java.lang.Object.equals.

Returns true if this object equals the specified object. If the specified object is a SortKey and references the same column and sort order, the two objects are equal.

Parameters

o:Object: the object to compare to

Returns:boolean

true if o is equal to this SortKey

getColumn	back to summary
public final int getColumn() Returns the index of the column. Returns:int index of column

getColumn

back to summary

public final int getColumn()

Returns the index of the column.

Returns:int: index of column

getSortOrder	back to summary
public final SortOrder getSortOrder() Returns the sort order of the column. Returns:SortOrder the sort order of the column

getSortOrder

back to summary

public final SortOrder getSortOrder()

Returns the sort order of the column.

Returns:SortOrder: the sort order of the column

hashCode back to summary

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. Returns the hash code for this `SortKey`. Returns:int hash code

public int hashCode()

Overrides java.lang.Object.hashCode.

Returns the hash code for this SortKey.

Returns:int: hash code

public abstract Class RowSorter<M>

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class RowSorter.SortKey

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail