Copyright 1996-2008 Ariba, Inc.

    Licensed under the Apache License, Version 2.0 (the "License");

    you may not use this file except in compliance with the License.

    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software

    distributed under the License is distributed on an "AS IS" BASIS,

    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

    See the License for the specific language governing permissions and

    limitations under the License.

    $Id: //ariba/platform/ui/widgets/ariba/ui/table/AWTDataTable.java#203 $

*/

    DataTable widget

    See the AWApi section of .awl file for usage information.

    Important Concepts:

      Scroll Faulting / Pagination

      Grouping

      Filtering

      Sorting

      Display Group

      Details

      Nested Tables

    @aribaapi ariba

*/

    /*

    Implementation Overview:

    - Half of the implementation ("controller") is in AWTDisplayGroup

    - Table manages a set of AWTDataTable.Column objects.  AWTColumn is the most important one.

    - each Column has a corresponding *Renderer.java/.awl component that handles rendering of that column type.

    - The children of the Table element are Column elements which are managed as a list (like Tabs).

    - during initialization the Table prods the columns and they register themselves appropriately

    */

    public static final String TotalRowsKey = "totalRows";

    private static final String ShowTotalItemsBinding = "showTotalItems";

    private static final String IndentDetailRowBinding = "indentDetailRow";

    private static final String HasColumnHeadingBinding = "hasColumnHeading";

    private static final String RowIndexBinding = "rowIndex";

    private static final String ReorderActionBinding = "reorderAction";

    private static final String DragTypeBinding  = "dragType";

    private static final String DropTypesBinding = "dropTypes";

    public AWEncodedString _tableId;

    private static final String ChildrenBinding = "children";

    // this binding is used to disable the ChildrenBinding.  Since the existence of

    // the children binding enables outline mode, we need to have another binding to

    // allow conditionalization of the children binding.

    private static final String DisableChildrenBinding = "disableChildrenBinding";

    // passed to the column renderer if the value rendered is in a group heading

    public static final String IsGroupHeadingBinding = "isGroupHeading";

    // table configuration keys

    private static final String HiddenColumnsConfigKey = "hiddenColumns";

    private static final String GroupByColumnConfigKey = "groupByColumn";

    private static final String SortOrderingsConfigKey = "sortOrderings";

    private static final String GroupingExpansionDefaultConfigKey = "groupingExpansion";

    private static final String OutlineExpansionDefaultConfigKey = "outlineExpansion";

    private static final String TableBodyExpansionDefaultConfigKey = "tableBodyExpansion";

    /**

     * Maximum number of characters being displayed in the menus for the column names

     * @aribaapi ariba

     */

    public static final int ColumnLabelMenuMaxSize = 25;

    // a type for our column subclasses

    abstract public static class Column extends AWContainerElement

    {

        static {

            AWSemanticKeyProvider.registerClassExtension(Column.class,

                                                        new SemanticKeyProvider_Column());

        }

        /** AWComponent to use to render this component */

        abstract public String rendererComponentName ();

        public void initializeColumn (AWTDataTable table) {}

        // called by renderer before the column is used

        public void prepare (AWTDataTable table) {}

        /**

         * Tell the column the current table item

         * @param item The new current item (row value)

         * @param table The table that is setting the item

         * @aribaapi private

         */

        public void setCurrentItem (Object item, AWTDataTable table) {return;}

        /**

         * Tell the column that the rows are being reset.

         * @param table The table that is setting the item

         * @aribaapi private

         */

        public void rowsReset (AWTDataTable table) {return;}

        public boolean isValueColumn () { return false; }

        public boolean isValueColumn (AWTDataTable sender) {

            return isValueColumn();

        }

        public boolean isSortableColumn (AWTDataTable sender) {

            return true;

        }

        public boolean isGroupableColumn (AWTDataTable sender) {

            // by default, if sortable, it is groupable

            return isSortableColumn(sender);

        }

        // Pivot grouping property -- consecutive columns sharing equals() values will be merged

        public Object uniquingValue (AWTDataTable sender, Object item) {

            return NeverEqualValue;

        }

        public boolean isOptional (AWTDataTable sender) { return false; }   // can we hide it?

        public boolean initiallyVisible () { return true; }   // should it be visible by default?

        public boolean initiallyVisible (AWTDataTable sender) {

            return initiallyVisible();

        }

        public boolean wantsSpan (AWTDataTable sender) {

            // does this column want to span any any blank columns to the right

            return false;

        }

        public boolean isBlank (AWTDataTable sender) {

            // can be used for span of columns to left

            return false;

        }

        public String keyPathString () { return null; }

        public String label (AWTDataTable table) { return label(); }

        protected String label () { return null; }

        // Pivot field location compatability:

        //      Field, RowField, ColumnField

        //      Attribute, ColumnAttribute, DetailAttribute

        //      Any, None (can't move), Current (Attr to Attr, Field to Field)

        public String pivotMoveType (AWTDataTable table) { return "Current"; }

        public boolean renderValueInLabelColumn (AWTDataTable table) { return false; }

        public AWTSortOrdering createSortOrdering (AWTDataTable table) {

            String keyPathString = keyPathString();

            return (keyPathString == null) ? null

                : AWTSortOrdering.sortOrderingWithKey(keyPathString, AWTSortOrdering.CompareCaseInsensitiveAscending);

        }

        public void prepareSortOrdering (AWTDataTable table, AWTSortOrdering ordering)

        {

        }

        public boolean matchesKey (String key)

        {

            String ourKey = keyPathString();

            return (ourKey == key) || ((ourKey != null) && ourKey.equals(key));

        }

        protected Object bindingValue (AWBinding binding, AWTDataTable table)

        {

            return (binding == null) ? null : table.valueForBinding(binding);

        }

        // Style to be laid down on column to assign minimum width for TD

        // Value in px.  0 (zero) means do not set width

        public int minWidthPx (AWTDataTable table)

        {

            return 0;

        }

        // The real column to use for rendering

        public Column prepareAndReplace (AWTDataTable table)

        {

            prepare(table);

            return this;

        }

        // used to compute column set signature

        public int hashCode() {

            String key = keyPathString();

            return ((key != null) ? key.hashCode() : 1) * 31 + this.getClass().hashCode();

        }

        // Overridden by columns (e.g. DynamicColumns) that want ability to be re-covered during

        // forceColumnUpdate

        public Object purgatoryKey () { return keyPathString(); }

    }

    public interface DetailColumn {

        boolean renderBeforeRow (AWTDataTable table);

    }

    public static class SemanticKeyProvider_Column extends AWSemanticKeyProvider

    {

        public String getKey (Object receiver, AWComponent component)

        {

            Column column = (Column)receiver;

            return column.keyPathString();

        }

    }

    public static abstract class ColumnRenderer extends AWComponent

    {

        // stateless

        public AWTDataTable _table;

        public void awake ()

        {

            _table = (AWTDataTable)valueForBinding(BindingNames.table);

        }

        public void sleep ()

        {

            _table = null;

        }

        public Object _currentItem ()

        {

            return _table.displayGroup().currentItem();

        }

        public Column column ()

        {

            return _table._currentColumn;

        }

        protected Object bindingValue (AWBinding binding)

        {

            Object bindingValue = null;

            if (binding != null) {

                AWComponent parent = this;

                while (!(parent instanceof AWTDataTable)) {

                    parent = parent.parent();

                }

                bindingValue = parent.valueForBinding(binding);

            }

            return bindingValue;

        }

        protected boolean booleanBindingValue (AWBinding binding, boolean defaultValue)

        {

            if (binding == null) return defaultValue;

            Object value = bindingValue(binding);

            return AWBinding.computeBooleanValue(value);

        }

        public Object columnWidth ()

        {

            // width information for the column

            return null;

        }

        /**

         * Width information for the column.  Returns null if the column

         * in the current data row should not contain a width specification.

         * Should only be used for columns in data rows (ie. not header row).

         */

        public Object dataRowColumnWidth ()

        {

            Object retVal = null;

            if (!booleanValueForBinding(HasColumnHeadingBinding) &&

                intValueForBinding(RowIndexBinding) == 0) {

                retVal = columnWidth();

            }

            return retVal;

        }

    }

    public static final Object NeverEqualValue = new NeverEqualClass();

    private static class NeverEqualClass {

        public boolean equals () { return false; }

    }

    public static String EnvKey = "dataTable";

    void _phasePrepare ()

    {

        if (_parentTable == null) {

            _parentTable = (AWTDataTable)env().peek(EnvKey);

        }

        env().push(EnvKey, this);

    }

    void _phaseComplete ()

    {

        env().pop(EnvKey);

    }

    public static AWTDataTable currentInstance (AWComponent component)

    {

        return (AWTDataTable)component.env().peek(EnvKey);

    }

    /*******************************************************************************

     * Instance Variables

     *******************************************************************************/

    /**

     * This is where we store our row data.

     * @see #initializeDisplayGroupObjects

     * @see #checkListBinding

     */

    protected AWTDisplayGroup _displayGroup;

    /**

     * This is stored to check for rapid turnaround changes.

     */

    private AWComponentReference _processedReference;

    private List<Column> _allColumns;

    private boolean _visibilityArray[];

    protected List<Column> _displayedColumns;

    private List<Column> _dataColumns;

    private List<Column> _optionalColumns;

    private Column _detailColumn;

    private Column _secondDetailColumn;

    private AWTButtonArea _selectionButtonArea;

    private AWTButtonArea _globalButtonArea;

    private AWTButtonArea _rightButtonArea;

    private Column _headingAreaColumn;

    private Column _wrapperColumn;

    private Column _groupByColumn;

    private boolean _createdDisplayGroup;

    private boolean _didHibernate = false;

    private String _globalValign;

    private AWBinding _isItemSelectableBinding;

    private AWBinding _groupByColumnBinding;

    private AWBinding _forceColumnUpdateBinding;

    private AWBinding _forceRenderRowsBinding;

    private boolean _showColumnHeader;

    private String  _style;

    private String _tableClass;

    private boolean _enableScrolling;

    /**

     * Used to buffer changes in scroll offset until renderResponse.

     */

    protected int _scrollTopIndex = -1;

    /**

     * Only used to retain horizontal scroll across requests.

     * Binding.

     */

    public int _scrollLeftPos = 0;

    /**

     * This is the rendering scratch state.

     */

    private boolean _rowToggleState;

    // 0 = none, 1 = current page, 2 = all rows

    private static final int EXPORT_NONE = 0;

    private static final int EXPORT_CURRENT = 1;

    private static final int EXPORT_ALL = 2;

    protected int _exportState = EXPORT_NONE;

    private boolean _showOptionsMenu;

    private boolean _showBatchNavigation;

    private boolean _expandAll;

    public boolean _useParentLayout;

    public boolean _isOutline;

    AWTDataTable _parentTable;

    protected AWBinding _detailRowClassBinding;

    protected AWBinding _rowClassBinding;

    protected AWBinding _tdClassBinding;

    public Object _elementIdForVisibleRow;

    public Column _currentColumn;

    public Column _originalCurrentColumn;

    protected int _dynamicColspan;

    public int _currentRowIndex;

    public int _currentColumnIndex;

    public boolean _isTopBar;

    protected boolean _skipTopLine;

    public boolean _useRefresh;

    public boolean _isMaximized;  // pushed through from ScrollTableWrapper

    protected boolean _showSelectionColumn;

    public boolean _tableBodyCollapsible;

    public boolean _tableBodyExpanded;

    protected boolean _isDragDropEnabled = false;

    // 0 = none, 1 = single, 2 = multi

    protected static final int SELECT_NONE = 0;

    protected static final int SELECT_SINGLE = 1;

    protected static final int SELECT_MULTI = 2;

    protected int _selectMode = SELECT_NONE;

    protected int _colsBeforeData;

    protected int _colsAfterFirstDataColumn;

    protected int _outlineColumnIndex;

    protected int _nextColumnIndentation;

    private List<AWTColumnManager> _columnManagers = null;

    // If true, the selection column is always rendered regardless of the previous value.

    private boolean _forceRenderSelectionColumn = false;

    private boolean _showSelectAll = true;

    protected AWBinding _scrollFaultActionBinding;

    private boolean _isScrollFaultAction = false;

    public AWTDataTable ()

    {

        // System.out.println ("*** New DataTable: " + this);

    }

    /*******************************************************************************

     * Bindings (some)

     *******************************************************************************/

    public int currentRowIndex ()

    {

        return _currentRowIndex;

    }

    public void setCurrentRowIndex (int index)

    {

        _currentRowIndex = index;

        _dynamicColspan = 0;

        _didRenderCurrentRow = false;

    }

    public int scrollTopIndex ()

    {

        return _scrollTopIndex;

    }

    public void setScrollTopIndex (int index)

    {

        _scrollTopIndex = index;

    }

    /////////////

    // Awake

    /////////////

    protected void awake ()

    {

        _isDragDropEnabled = hasBinding(ReorderActionBinding) ||

                   hasBinding(AWDragContainer.DragActionBinding)||

                   hasBinding(AWDropContainer.DropActionBinding);

        if (_isDragDropEnabled && hasBinding(AWBindingNames.isDragDropEnabled)) {

            _isDragDropEnabled =

                booleanValueForBinding(AWBindingNames.isDragDropEnabled);

        }

    }

    public boolean isStateless ()

    {

        return false;

    }

    private boolean shouldForceColumnUpdate ()

    {

        boolean forceTableRefresh = false;

        if (_forceColumnUpdateBinding != null) {

            forceTableRefresh = booleanValueForBinding(_forceColumnUpdateBinding);

            if (forceTableRefresh) {

                setValueForBinding(false,_forceColumnUpdateBinding);

            }

        }

        return forceTableRefresh;

    }

    public void renderResponse(AWRequestContext requestContext, AWComponent component)

    {

        try {

            _phasePrepare();

            if ((_processedReference != componentReference()) ||

                parentTableLayoutChanged() ||

                hasDisplayGroupChanged()) {

                // make sure that columns are not being changed since we're trying to export

                // the visible columns during invoke

                Assert.that(!isExportMode(),

                    "Cannot change table structure during data export.");

                initForChangedReference();

                // if we're going to initForChangedReference, then we're going to update all

                // the columns and we need to ensure that our _forceColumnUpdateBinding

                // continues to operate as a latch by pushing false to the binding

                shouldForceColumnUpdate();

                // remember this template (and flag that we're done with initialization)

                _processedReference = componentReference();

            }

            else if (shouldForceColumnUpdate() && !isExportMode() && !_isScrollFaultAction) {

                invalidateColumns();

                columns();  // force refresh

            }

            if (_didHibernate) {

                initializeDisplayGroupObjects();

                _didHibernate = false;

            }

            checkListChanges();

            prepareForIteration();

            checkGroupByColumn();

            checkDetailExpandoEnabled();

            _rowToggleState = false;

            _showSelectionColumn = !hasBinding(BindingNames.showSelectionColumn)

                        || booleanValueForBinding(BindingNames.showSelectionColumn);

            // we delay buffered changes to the scroll offset until renderResponse

            checkScrollTop();

            _displayGroup._discardBufferedSelection();

            int cmLen = ListUtil.getListSize(_columnManagers);

            for (int ii=0; ii<cmLen; ii++) {

                _columnManagers.get(ii).preAppend(this);

            }

            // register error nav handler to provide default table nav support

            // We need to register with highest possible priority

            DataTableNavigationHandler handler = new DataTableNavigationHandler(this);

            errorManager().registerErrorHandler(handler, 1, true);

            // run the append on all our contained elements

            super.renderResponse(requestContext, component);

            for (int ii=0; ii<cmLen; ii++) {

                _columnManagers.get(ii).postAppend(this);

            }

            _forceRenderSelectionColumn = false;

        }

        finally {

            _phaseComplete();

        }

    }

    /*******************************************************************************

     * Scroll Faulting Support

     *******************************************************************************/

    public AWResponseGenerating  scrollFaultAction ()

    {

        _isScrollFaultAction = true;

        if (_scrollFaultActionBinding != null) {

            return (AWResponseGenerating)valueForBinding(BindingNames.scrollFaultAction);