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. 
024     * 
025     * A column is responsible for presenting a particular part of the data
026     * from the objects in the table. This is done via the getValueRender() method.
027     * 
028     * A column may be sortable, in which case it defines the way in which the
029     * objects in the table must be sorted by providing a Comparator.
030     * 
031     * @author mindbridge
032     */
033    public interface ITableColumn
034    {
035            /**
036             * Method getColumnName provides the name of the column. 
037             *
038             * The column name must be unique and is generally used for the identification 
039             * of the column. It does not have to be the same as the display name 
040             * via which the column is identified to the user (see the getColumnRender() method).
041             * @return String the name of the column
042             */
043            String getColumnName();
044    
045            /**
046             * Method getSortable declares whether the column allows sorting.
047             * If the column allows sorting, it must also return a valid Comparator
048             * via the getComparator() method.
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 
055             * the data in the table according to this column. The Comparator must
056             * accept two different rows, compare them according to this column, 
057             * and return the appropriate value.
058             * @return Comparator the Comparator used to sort the table data
059             */
060            Comparator getComparator();
061    
062            /**
063             * Method getColumnRenderer provides a renderer that takes care of rendering 
064             * the column in the table header. If the column is sortable, the renderer
065             * may provide a mechanism to sort the table in an ascending or descending 
066             * manner.
067             * @param objCycle the current request cycle
068             * @param objSource a component that can provide the table model (typically TableView)
069             * @return IRender the renderer to present the column header
070             */
071            IRender getColumnRenderer(
072                    IRequestCycle objCycle,
073                    ITableModelSource objSource);
074    
075            /**
076             * Method getValueRenderer provides a renderer for presenting the value of a 
077             * particular row in the current column.
078             * 
079             * @param objCycle the current request cycle
080             * @param objSource a component that can provide the table model (typically TableView)
081             * @param objRow the row data
082             * @return IRender the renderer to present the value of the row in this column
083             */
084            IRender getValueRenderer(
085                    IRequestCycle objCycle,
086                    ITableModelSource objSource,
087                    Object objRow);
088    }