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
015package org.apache.tapestry.contrib.table.model;
016
017import java.util.Comparator;
018
019import org.apache.tapestry.IRender;
020import 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 */
033public 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}