001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry.contrib.table.model;
016    
017    import java.util.Comparator;
018    
019    import org.apache.tapestry.IRender;
020    import org.apache.tapestry.IRequestCycle;
021    
022    /**
023     * The interface defining a table column. A column is responsible for presenting
024     * a particular part of the data from the objects in the table. This is done via
025     * the getValueRender() method. A column may be sortable, in which case it
026     * defines the way in which the objects in the table must be sorted by providing
027     * a Comparator.
028     * 
029     * @author mindbridge
030     */
031    public interface ITableColumn
032    {
033    
034        /**
035         * Method getColumnName provides the name of the column. The column name
036         * must be unique and is generally used for the identification of the
037         * column. It does not have to be the same as the display name via which the
038         * column is identified to the user (see the getColumnRender() method).
039         * 
040         * @return String the name of the column
041         */
042        String getColumnName();
043    
044        /**
045         * Method getSortable declares whether the column allows sorting. If the
046         * column allows sorting, it must also return a valid Comparator via the
047         * getComparator() method.
048         * 
049         * @return boolean whether the column is sortable or not
050         */
051        boolean getSortable();
052    
053        /**
054         * Method getComparator returns the Comparator to be used to sort the data
055         * in the table according to this column. The Comparator must accept two
056         * different rows, compare them according to this column, and return the
057         * appropriate value.
058         * 
059         * @return Comparator the Comparator used to sort the table data
060         */
061        Comparator getComparator();
062    
063        /**
064         * Method getColumnRenderer provides a renderer that takes care of rendering
065         * the column in the table header. If the column is sortable, the renderer
066         * may provide a mechanism to sort the table in an ascending or descending
067         * manner.
068         * 
069         * @param objCycle
070         *            the current request cycle
071         * @param objSource
072         *            a component that can provide the table model (typically
073         *            TableView)
074         * @return IRender the renderer to present the column header
075         */
076        IRender getColumnRenderer(IRequestCycle objCycle,
077                ITableModelSource objSource);
078    
079        /**
080         * Method getValueRenderer provides a renderer for presenting the value of a
081         * particular row in the current column.
082         * 
083         * @param objCycle
084         *            the current request cycle
085         * @param objSource
086         *            a component that can provide the table model (typically
087         *            TableView)
088         * @param objRow
089         *            the row data
090         * @return IRender the renderer to present the value of the row in this
091         *         column
092         */
093        IRender getValueRenderer(IRequestCycle objCycle,
094                ITableModelSource objSource, Object objRow);
095    }