/*
* Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.swing;
import javax.swing.SortOrder;
import javax.swing.event.*;
import java.util.*;
/**
* <code>RowSorter</code> provides the basis for sorting and filtering.
* Beyond creating and installing a <code>RowSorter</code>, you very rarely
* need to interact with one directly. Refer to
* {@link javax.swing.table.TableRowSorter TableRowSorter} for a concrete
* implementation of <code>RowSorter</code> for <code>JTable</code>.
* <p>
* <code>RowSorter</code>'s primary role is to provide a mapping between
* two coordinate systems: that of the view (for example a
* <code>JTable</code>) and that of the underlying data source, typically a
* model.
* <p>
* The view invokes the following methods on the <code>RowSorter</code>:
* <ul>
* <li><code>toggleSortOrder</code> — 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.
* <li>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 <code>RowSorter</code> should not update its mapping
* until one of these methods is invoked.
* </ul>
* Because the view makes extensive use of the
* <code>convertRowIndexToModel</code>,
* <code>convertRowIndexToView</code> and <code>getViewRowCount</code> methods,
* these methods need to be fast.
* <p>
* <code>RowSorter</code> provides notification of changes by way of
* <code>RowSorterListener</code>. Two types of notification are sent:
* <ul>
* <li><code>RowSorterEvent.Type.SORT_ORDER_CHANGED</code> — notifies
* listeners that the sort order has changed. This is typically followed
* by a notification that the sort has changed.
* <li><code>RowSorterEvent.Type.SORTED</code> — notifies listeners that
* the mapping maintained by the <code>RowSorter</code> has changed in
* some way.
* </ul>
* <code>RowSorter</code> 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,
* <code>toggleSortOrder</code> might call through to the database
* (on a background thread), and override the mapping methods to return the
* argument that is passed in.
* <p>
* Concrete implementations of <code>RowSorter</code>
* need to reference a model such as <code>TableModel</code> or
* <code>ListModel</code>. The view classes, such as
* <code>JTable</code> and <code>JList</code>, will also have a
* reference to the model. To avoid ordering dependencies,
* <code>RowSorter</code> implementations should not install a
* listener on the model. Instead the view class will call into the
* <code>RowSorter</code> when the model changes. For
* example, if a row is updated in a <code>TableModel</code>
* <code>JTable</code> invokes <code>rowsUpdated</code>.
* When the model changes, the view may call into any of the following methods:
* <code>modelStructureChanged</code>, <code>allRowsChanged</code>,
* <code>rowsInserted</code>, <code>rowsDeleted</code> and
* <code>rowsUpdated</code>.
*
* @param <M> the type of the underlying model
* @see javax.swing.table.TableRowSorter
* @since 1.6
*/
public abstract class RowSorter<M> {
private EventListenerList listenerList = new EventListenerList();
/**
* Creates a <code>RowSorter</code>.
*/
public RowSorter() {
}
/**
* Returns the underlying model.
*
* @return the underlying model
*/
public abstract M getModel();
/**
* 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.
* <p>
* If this results in changing the sort order and sorting, the
* appropriate <code>RowSorterListener</code> notification will be
* sent.
*
* @param column the column to toggle the sort ordering of, in
* terms of the underlying model
* @throws IndexOutOfBoundsException if column is outside the range of
* the underlying model
*/
public abstract void toggleSortOrder(int column);
/**
* Returns the location of <code>index</code> in terms of the
* underlying model. That is, for the row <code>index</code> in
* the coordinates of the view this returns the row index in terms
* of the underlying model.
*
* @param index the row index in terms of the underlying view
* @return row index in terms of the view
* @throws IndexOutOfBoundsException if <code>index</code> is outside the
* range of the view
*/
public abstract int convertRowIndexToModel(int index);
/**
* Returns the location of <code>index</code> in terms of the
* view. That is, for the row <code>index</code> in the
* coordinates of the underlying model this returns the row index
* in terms of the view.
*
* @param index the row index in terms of the underlying model
* @return row index in terms of the view, or -1 if index has been
* filtered out of the view
* @throws IndexOutOfBoundsException if <code>index</code> is outside
* the range of the model
*/
public abstract int convertRowIndexToView(int index);
/**
* Sets the current sort keys.
*
* @param keys the new <code>SortKeys</code>; <code>null</code>
* is a shorthand for specifying an empty list,
* indicating that the view should be unsorted
*/
public abstract void setSortKeys(List<? extends SortKey> keys);
/**
* Returns the current sort keys. This must return a {@code
* non-null List} and may return an unmodifiable {@code List}. If
* you need to change the sort keys, make a copy of the returned
* {@code List}, mutate the copy and invoke {@code setSortKeys}
* with the new list.
*
* @return the current sort order
*/
public abstract List<? extends SortKey> getSortKeys();
/**
* 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.
*
* @return number of rows in the view
* @see #getModelRowCount
*/
public abstract int getViewRowCount();
/**
* Returns the number of rows in the underlying model.
*
* @return number of rows in the underlying model
* @see #getViewRowCount
*/
public abstract int getModelRowCount();
/**
* Invoked when the underlying model structure has completely
* changed. For example, if the number of columns in a
* <code>TableModel</code> changed, this method would be invoked.
* <p>
* 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 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.
* <p>
* You normally do not call this method. This method is public
* to allow view classes to call it.
*/
public abstract void allRowsChanged();
/**
* Invoked when rows have been inserted into the underlying model
* in the specified range (inclusive).
* <p>
* 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.
* <p>
* You normally do not call this method. This method is public
* to allow view classes to call it.
*
* @param firstRow the first row
* @param endRow the last row
* @throws IndexOutOfBoundsException if either argument is invalid, or
* <code>firstRow</code> > <code>endRow</code>
*/
public abstract void rowsInserted(int firstRow, int endRow);
/**
* Invoked when rows have been deleted from the underlying model
* in the specified range (inclusive).
* <p>
* The arguments give the indices of the effected range and
* are in terms of the model <b>before</b> 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.
* <p>
* You normally do not call this method. This method is public
* to allow view classes to call it.
*
* @param firstRow the first row
* @param endRow the last row
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the model before the change, or
* <code>firstRow</code> > <code>endRow</code>
*/
public abstract void rowsDeleted(int firstRow, int endRow);
/**
* Invoked when rows have been changed in the underlying model
* between the specified range (inclusive).
* <p>
* You normally do not call this method. This method is public
* to allow view classes to call it.
*
* @param firstRow the first row, in terms of the underlying model
* @param endRow the last row, in terms of the underlying model
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the underlying model, or
* <code>firstRow</code> > <code>endRow</code>
*/
public abstract void rowsUpdated(int firstRow, int endRow);
/**
* Invoked when the column in the rows have been updated in
* the underlying model between the specified range.
* <p>
* You normally do not call this method. This method is public
* to allow view classes to call it.
*
* @param firstRow the first row, in terms of the underlying model
* @param endRow the last row, in terms of the underlying model
* @param column the column that has changed, in terms of the underlying
* model
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the underlying model after the change,
* <code>firstRow</code> > <code>endRow</code>, or
* <code>column</code> is outside the range of the underlying
* model
*/
public abstract void rowsUpdated(int firstRow, int endRow, int column);
/**
* Adds a <code>RowSorterListener</code> to receive notification
* about this <code>RowSorter</code>. If the same
* listener is added more than once it will receive multiple
* notifications. If <code>l</code> is <code>null</code> nothing
* is done.
*
* @param l the <code>RowSorterListener</code>
*/
public void addRowSorterListener(RowSorterListener l) {
listenerList.add(RowSorterListener.class, l);
}
/**
* Removes a <code>RowSorterListener</code>. If
* <code>l</code> is <code>null</code> nothing is done.
*
* @param l the <code>RowSorterListener</code>
*/
public void removeRowSorterListener(RowSorterListener l) {
listenerList.remove(RowSorterListener.class, l);
}
/**
* Notifies listener that the sort order has changed.
*/
protected void fireSortOrderChanged() {
fireRowSorterChanged(new RowSorterEvent(this));
}
/**
* Notifies listener that the mapping has changed.
*
* @param lastRowIndexToModel the mapping from model indices to
* view indices prior to the sort, may be <code>null</code>
*/
protected void fireRowSorterChanged(int[] lastRowIndexToModel) {
fireRowSorterChanged(new RowSorterEvent(this,
RowSorterEvent.Type.SORTED, lastRowIndexToModel));
}
void fireRowSorterChanged(RowSorterEvent event) {
Object[] listeners = listenerList.getListenerList();
for (int i = listeners.length - 2; i >= 0; i -= 2) {
if (listeners[i] == RowSorterListener.class) {
((RowSorterListener)listeners[i + 1]).
sorterChanged(event);
}
}
}
/**
* 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
*/
public static class SortKey {
private int column;
private SortOrder sortOrder;
/**
* Creates a <code>SortKey</code> for the specified column with
* the specified sort order.
*
* @param column index of the column, in terms of the model
* @param sortOrder the sorter order
* @throws IllegalArgumentException if <code>sortOrder</code> is
* <code>null</code>
*/
public SortKey(int column, SortOrder sortOrder) {
if (sortOrder == null) {
throw new IllegalArgumentException(
"sort order must be non-null");
}
this.column = column;
this.sortOrder = sortOrder;
}
/**
* Returns the index of the column.
*
* @return index of column
*/
public final int getColumn() {
return column;
}
/**
* Returns the sort order of the column.
*
* @return the sort order of the column
*/
public final SortOrder getSortOrder() {
return sortOrder;
}
/**
* Returns the hash code for this <code>SortKey</code>.
*
* @return hash code
*/
public int hashCode() {
int result = 17;
result = 37 * result + column;
result = 37 * result + sortOrder.hashCode();
return result;
}
/**
* Returns true if this object equals the specified object.
* If the specified object is a <code>SortKey</code> and
* references the same column and sort order, the two objects
* are equal.
*
* @param o the object to compare to
* @return true if <code>o</code> is equal to this <code>SortKey</code>
*/
public boolean equals(Object o) {
if (o == this) {
return true;
}
if (o instanceof SortKey) {
return (((SortKey)o).column == column &&
((SortKey)o).sortOrder == sortOrder);
}
return false;
}
}
}