com.jidesoft.list
Class SortableListModel

java.lang.Object
  javax.swing.AbstractListModel
      com.jidesoft.list.DefaultListModelWrapper
          com.jidesoft.list.SortableListModel

All Implemented Interfaces:

IndexChangeEventGenerator, EventFireListModel, ListModelWrapper, Serializable, EventListener, ListDataListener, ListModel

Direct Known Subclasses:

SortableGroupableListModel

public class SortableListModel
extends DefaultListModelWrapper

SortableListModel is a list model wrapper which can do the sorting. Given any existing list model, you can wrap it into SortableListModel and use it later on any JList.

 SortableListModel sortableListModel = new SortableListModel(listModel);
 JList sortableList = new JList(sortableListModel);
 

To sort the list, you just call

 sortableListModel.sort(); // or sort(SortableListModel.SORT_DESCENDING) to sort descending.
 

See Also:

Serialized Form

Field Summary

static int	SORT_ASCENDING
static int	SORT_DESCENDING
static int	UNSORTED

Fields inherited from class com.jidesoft.list.DefaultListModelWrapper

_adjustingIndexes, _indexes, _model

Fields inherited from class javax.swing.AbstractListModel

listenerList

Constructor Summary

SortableListModel()

SortableListModel(ListModel model)
Creates a SortableListModel from any list model.

Method Summary

void	addSortListener(SortListener l) Adds the specified listener to receive collapsible pane events from this collapsible frame.
protected int	compare(int row1, int row2) Compares two rows to decide the order.
protected int	compare(Object o1, Object o2) Compares its two arguments for order.
void	contentsChanged(ListDataEvent e)
void	fireSortEvent() Fires an collapsible pane event.
void	fireSortingEvent() Fires sort event.
Comparator	getComparator() Gets the comparator.
ComparatorContext	getComparatorContext() Gets the comparator context.
static SortableListModel	getSortableListModel(ListModel model) Gets the sortable table model.
SortListener[]	getSortListeners() Returns an array of all the SortListeners added to this CollapsiblePane with addSortListener.
int	getSortOrder() Gets the sort order.
protected int[]	getSortRanges() Gets the row index range that will be sorted.
void	intervalAdded(ListDataEvent e)
void	intervalRemoved(ListDataEvent e)
boolean	isAlwaysUseComparators() Checks if the alwaysUseComparators flag value.
boolean	isAutoResort() Checks if the table is automatically resorted when data changes.
boolean	isOptimized() Checks if the sortable table model is in optimized mode.
void	removeSortListener(SortListener l) Removes the specified collapsible pane listener so that it no longer receives collapsible pane events from this collapsible pane .
void	reset() Resets.
void	resort() Resort the table.
protected int	search(int[] indexes, int row) Searches the specified array of rows for the specified value using binary search.
void	setAlwaysUseComparators(boolean alwaysUseComparators) Sets the alwaysUseComparators flag.
void	setAutoResort(boolean autoResort) AutoResort is a feature that automatically resort the table when table data changes.
void	setComparator(Comparator comparator) Sets the comparator.
void	setComparatorContext(ComparatorContext comparatorContext) Sets the comparator context.
void	setIndexes(int[] indexes) Overrides the method in DefaultListModelWrapper to clear up any sort order.
void	setOptimized(boolean optimized) If optimized flag is true and the table is already sorted, SortableListModel will do incremental sorting when data is only partially changed.
void	setSortOrder(int sortOrder) Sets the sort order.
void	sort() Sort the list model ascending.
void	sort(int order) Sort the list model.
protected void	sort(int[] from, int[] to, int low, int high) Sorts the rows.
void	unsort() Unsorts the list model.

Methods inherited from class com.jidesoft.list.DefaultListModelWrapper

addIndexChangeListener, createCompoundListDataEvent, fireEvents, fireIndexChanged, fireListDataEvent, getActualIndexAt, getActualModel, getElementAt, getIndexAt, getIndexChangeListeners, getIndexes, getSize, reallocateIndexes, removeIndexChangeListener, setActualModel

Methods inherited from class javax.swing.AbstractListModel

addListDataListener, fireContentsChanged, fireIntervalAdded, fireIntervalRemoved, getListDataListeners, getListeners, removeListDataListener

Methods inherited from class java.lang.Object

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

Field Detail

SORT_ASCENDING

public static final int SORT_ASCENDING

See Also:

Constant Field Values

SORT_DESCENDING

public static final int SORT_DESCENDING

See Also:

Constant Field Values

UNSORTED

public static final int UNSORTED

See Also:

Constant Field Values

Constructor Detail

SortableListModel

public SortableListModel()

SortableListModel

public SortableListModel(ListModel model)

Creates a SortableListModel from any list model.

Parameters:

model - the actual list model

Method Detail

intervalAdded

public void intervalAdded(ListDataEvent e)

Specified by:

intervalAdded in interface ListDataListener

Overrides:

intervalAdded in class DefaultListModelWrapper

intervalRemoved

public void intervalRemoved(ListDataEvent e)

Specified by:

intervalRemoved in interface ListDataListener

Overrides:

intervalRemoved in class DefaultListModelWrapper

contentsChanged

public void contentsChanged(ListDataEvent e)

Specified by:

contentsChanged in interface ListDataListener

Overrides:

contentsChanged in class DefaultListModelWrapper

getSortRanges

protected int[] getSortRanges()

Gets the row index range that will be sorted. It will be a one dimension int array with the first value to be the low row index of the range and the second value to be the high row index of the range. The low row index is included in the range and the hig row index is not included in the range. By default, we will return new int[]{0, _indexes.length} which is from the first row to the last row, the whole range. If your last row is a summary row so you don't want it to be sorted, you can return new int[]{0, _indexes.length - 1}. Or if you want the row at index 3 to always stay there, you can return new int[]{0, 3, 4, _indexes.length}.

Returns:

the sort ranges.

search

protected int search(int[] indexes,
                     int row)

Searches the specified array of rows for the specified value using binary search. The array must be sorted prior to making this call. If it is not sorted, the results are undefined. If the array contains multiple elements with the specified value, there is no guarantee which one will be found.
Subclass can override this method to implement their own algorithm to do the search. When doing comparison in the algorithm, use the compare(int, int) method defined in this class. The original indexes are sorted in a way that compare(indexes[n], indexes[n + 1]) will always return 1 or 0. So if you compare(indexes[n], row) and it returns -1, you knows the row index should be greater than n.

Parameters:

indexes - the array of row to be searched.

row - the index of the row to be searched for.

Returns:

index of the search key, if it is contained in the list; otherwise, (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted into the list: the index of the first element greater than the key, or list.size(), if all elements in the list are less than the specified key. Note that this guarantees that the return value will be >= 0 if and only if the key is found.

sort

protected void sort(int[] from,
                    int[] to,
                    int low,
                    int high)

Sorts the rows.

Subclass can override this method to implement their own algorithm to sort. When doing comparison in the algorithm, use the compare(int, int) method defined in this class.

Parameters:

from - an int array of row indices to be sorted

to - an int array of row indices to store the result after sorting

low - the start index of the row in the array to be sorted

high - the end index of the row in the array to be sorted

compare

protected int compare(int row1,
                      int row2)

Compares two rows to decide the order. It will consider the ascending or descending and return different value so the return has different meaning comparing to that of Comparator.compare(o1, o2).
If it returns 1, it means keep the current order. If it returns -1, it means the order should be swapped. If it returns 0, it means the order doesn't matter. It could be either the table model is not sorted so the order doesn't matter or the two rows have the same order.

Subclass can override this method to provide their own way to compare the two rows. Please make sure you access the element using getActualModel().getElement(rowIndex) since SortableListModel is also a ListModelWrapper.

Parameters:

row1 - index of the first row to be compared

row2 - index of the second row to be compared

Returns:

If it returns 1, it means keep the current order. If it returns -1, it means the order should be swapped. If it returns 0, it means the order doesn't matter. It could be either the table model is not sorted so the order doesn't matter or the two rows have the same order.

compare

protected int compare(Object o1,
                      Object o2)

Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

By default, we took several steps to improve the performance. First we will check if either objects is null. If both are null, we return 0. If one is null, we return 1 or -1. Then we will check if the objects are String. If yes,we will use String#compareToIgnoreCase. Then we will check if the objects are Comparable and if yes, we will ues Comparable#compareTo method. At last, we will check if getComparator returns a non-null value and use it. If the getComparator() is null, we will try to get a Comparator from ObjectComparatorManager based on the object type and the ComparatorContext and use it. Subclass can override it to provide your own way to compare. If you ever call setComparator(java.util.Comparator) or setComparatorContext(com.jidesoft.comparator.ComparatorContext), we will try to use it without doing the extra checking steps. There is also a setter called setAlwaysUseComparators(boolean). If yes, we will also skip the checking of String and Comparable, and use getComparator or ObjectComparatorManager.

Parameters:

o1 - the first object to be compared

o2 - the second object to be compared

Returns:

a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

getComparator

public Comparator getComparator()

Gets the comparator.

Returns:

the comparator that will be used to compare the values.

setComparator

public void setComparator(Comparator comparator)

Sets the comparator. If you never set it, SortableTableModel will look up for a comparator from ObjectComparatorManager based on the class of the value to be compared and the value returned from getComparatorContext.

Parameters:

comparator - the comparator

getComparatorContext

public ComparatorContext getComparatorContext()

Gets the comparator context. Comparator context along with the type of the element in the list will uniquely find a comparator on ObjectComparatorManager. In most cases, comparator context is null. Only if the type is the same but you want to compare differently, you can use comparator context to break the tie.

Returns:

the comparator context. Default value is null.

setComparatorContext

public void setComparatorContext(ComparatorContext comparatorContext)

Sets the comparator context. Comparator context along with the type of the element in the list will uniquely find a comparator on ObjectComparatorManager.

Parameters:

comparatorContext - the comparator context

getSortOrder

public int getSortOrder()

Gets the sort order.

Returns:

the sort order. The value could be UNSORTED, SORT_DESCENDING, or SORT_ASCENDING.

setSortOrder

public void setSortOrder(int sortOrder)

Sets the sort order.

Parameters:

sortOrder - the new sort order. The value could be UNSORTED, SORT_DESCENDING, or SORT_ASCENDING.

sort

public void sort()

Sort the list model ascending.

sort

public void sort(int order)

Sort the list model. The order could be either SORT_ASCENDING or SORT_DESCENDING. You can also pass in UNSORTED, which will be the same as unsort().

Parameters:

order - the new sort order.

unsort

public void unsort()

Unsorts the list model.

reset

public void reset()

Resets. It's the same as unsort().

setIndexes

public void setIndexes(int[] indexes)

Overrides the method in DefaultListModelWrapper to clear up any sort order.

Specified by:

setIndexes in interface ListModelWrapper

Overrides:

setIndexes in class DefaultListModelWrapper

Parameters:

indexes - the indexes

getSortableListModel

public static SortableListModel getSortableListModel(ListModel model)

Gets the sortable table model. If model is a ListModelWrapper, it will get the actual model until it finds the first sortable table model.

Parameters:

model - the outer list model

Returns:

sortable list model.

isOptimized

public boolean isOptimized()

Checks if the sortable table model is in optimized mode.

Returns:

the optimizedd flag.

setOptimized

public void setOptimized(boolean optimized)

If optimized flag is true and the table is already sorted, SortableListModel will do incremental sorting when data is only partially changed. If the flag is false, SortableListModel will resort completely whenever data changed.
Default is false. The performance will be not as good but it's more stable. If you want to change the flag to true, you need to make sure the underlying table model fires correct event when data changes.

Parameters:

optimized - the flag

isAutoResort

public boolean isAutoResort()

Checks if the table is automatically resorted when data changes.

Returns:

true if autoResort. Otherwise false.

setAutoResort

public void setAutoResort(boolean autoResort)

AutoResort is a feature that automatically resort the table when table data changes. This is the default behavior and useful in most cases. However there are cases when the data changes frequently, resort will make it very hard for user to read the value. So in these cases, you can set autoResort to false. Then you will need to provide a button to call resort() to resort the table.

Note: this flag is only used when optimized flag is true. If optimized is false, autoResort is always true.

Parameters:

autoResort - the flag

resort

public void resort()

Resort the table. When autoResort is false, the table will be out of order after data changes. The method will resort the table while keeping the sorting columns.

addSortListener

public void addSortListener(SortListener l)

Adds the specified listener to receive collapsible pane events from this collapsible frame.

Parameters:

l - the collapsible pane listener

removeSortListener

public void removeSortListener(SortListener l)

Removes the specified collapsible pane listener so that it no longer receives collapsible pane events from this collapsible pane .

Parameters:

l - the collapsible pane listener

getSortListeners

public SortListener[] getSortListeners()

Returns an array of all the SortListeners added to this CollapsiblePane with addSortListener.

Returns:

all of the SortListeners added or an empty array if no listeners have been added

Since:

1.4

See Also:

addSortListener(com.jidesoft.grid.SortListener)

fireSortingEvent

public void fireSortingEvent()

Fires sort event.

fireSortEvent

public void fireSortEvent()

Fires an collapsible pane event.

isAlwaysUseComparators

public boolean isAlwaysUseComparators()

Checks if the alwaysUseComparators flag value.

Returns:

true if alwaysUseComparators is true. Otherwise false.

setAlwaysUseComparators

public void setAlwaysUseComparators(boolean alwaysUseComparators)

Sets the alwaysUseComparators flag. By default, we will check if the two values are Comparable. If they both are, we will use Comparable.compareTo(Object) to compare. This is the default preferred way because this gives developer a finer control of the comparison result.

Parameters:

alwaysUseComparators - true or false.