/*

 * 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> &#8212; 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 &#8212; 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> &#8212; 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> &#8212; 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> &gt; <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> &gt; <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> &gt; <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> &gt; <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;

        }

    }

}