| // Copyright 2004 The Apache Software Foundation |
| // |
| // 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. |
| |
| package org.apache.tapestry.contrib.table.components; |
| |
| import java.io.Serializable; |
| import java.util.ArrayList; |
| import java.util.Collection; |
| import java.util.Iterator; |
| import java.util.List; |
| |
| import org.apache.commons.collections.CollectionUtils; |
| import org.apache.tapestry.ApplicationRuntimeException; |
| import org.apache.tapestry.BaseComponent; |
| import org.apache.tapestry.IBinding; |
| import org.apache.tapestry.IComponent; |
| import org.apache.tapestry.IMarkupWriter; |
| import org.apache.tapestry.IRequestCycle; |
| import org.apache.tapestry.contrib.table.model.IBasicTableModel; |
| import org.apache.tapestry.contrib.table.model.ITableColumn; |
| import org.apache.tapestry.contrib.table.model.ITableColumnModel; |
| import org.apache.tapestry.contrib.table.model.ITableDataModel; |
| import org.apache.tapestry.contrib.table.model.ITableModel; |
| import org.apache.tapestry.contrib.table.model.ITableModelSource; |
| import org.apache.tapestry.contrib.table.model.ITablePagingState; |
| import org.apache.tapestry.contrib.table.model.ITableSessionStateManager; |
| import org.apache.tapestry.contrib.table.model.ITableSessionStoreManager; |
| import org.apache.tapestry.contrib.table.model.common.BasicTableModelWrap; |
| import org.apache.tapestry.contrib.table.model.simple.SimpleListTableDataModel; |
| import org.apache.tapestry.contrib.table.model.simple.SimpleTableColumnModel; |
| import org.apache.tapestry.contrib.table.model.simple.SimpleTableModel; |
| import org.apache.tapestry.contrib.table.model.simple.SimpleTableState; |
| import org.apache.tapestry.event.PageDetachListener; |
| import org.apache.tapestry.event.PageEvent; |
| import org.apache.tapestry.event.PageRenderListener; |
| |
| /** |
| * A low level Table component that wraps all other low level Table components. |
| * This component carries the {@link org.apache.tapestry.contrib.table.model.ITableModel} |
| * that is used by the other Table components. Please see the documentation of |
| * {@link org.apache.tapestry.contrib.table.model.ITableModel} if you need to know more |
| * about how a table is represented. |
| * <p> |
| * This component also handles the saving of the state of the model using an |
| * {@link org.apache.tapestry.contrib.table.model.ITableSessionStateManager} |
| * to determine what part of the model is to be saved and an |
| * {@link org.apache.tapestry.contrib.table.model.ITableSessionStoreManager} |
| * to determine how to save it. |
| * <p> |
| * Upon the beginning of a new request cycle when the table model is first needed, |
| * the model is obtained using the following process: |
| * <ul> |
| * <li>The persistent state of the table is loaded. |
| * If the tableSessionStoreManager binding has not been bound, the state is loaded |
| * from a persistent property within the component (it is null at the beginning). |
| * Otherwise the supplied |
| * {@link org.apache.tapestry.contrib.table.model.ITableSessionStoreManager} is used |
| * to load the persistent state. |
| * <li>The table model is recreated using the |
| * {@link org.apache.tapestry.contrib.table.model.ITableSessionStateManager} that |
| * could be supplied using the tableSessionStateManager binding |
| * (but has a default value and is therefore not required). |
| * <li>If the {@link org.apache.tapestry.contrib.table.model.ITableSessionStateManager} |
| * returns null, then a table model is taken from the tableModel binding. Thus, if |
| * the {@link org.apache.tapestry.contrib.table.model.common.NullTableSessionStateManager} |
| * is used, the table model would be taken from the tableModel binding every time. |
| * </ul> |
| * Just before the rendering phase the persistent state of the model is saved in |
| * the session. This process occurs in reverse: |
| * <ul> |
| * <li>The persistent state of the model is taken via the |
| * {@link org.apache.tapestry.contrib.table.model.ITableSessionStateManager}. |
| * <li>If the tableSessionStoreManager binding has not been bound, the persistent |
| * state is saved as a persistent page property. Otherwise the supplied |
| * {@link org.apache.tapestry.contrib.table.model.ITableSessionStoreManager} is used |
| * to save the persistent state. Use of the |
| * {@link org.apache.tapestry.contrib.table.model.ITableSessionStoreManager} |
| * is usually necessary when tables with the same model have to be used across |
| * multiple pages, and hence the state has to be saved in the Visit, rather than |
| * in a persistent component property. |
| * </ul> |
| * <p> |
| * |
| * <p> |
| * Please see the Component Reference for details on how to use this component. |
| * |
| * [<a href="../../../../../../../ComponentReference/contrib.TableView.html">Component Reference</a>] |
| * |
| * @author mindbridge |
| * @version $Id$ |
| */ |
| public abstract class TableView |
| extends BaseComponent |
| implements PageDetachListener, PageRenderListener, ITableModelSource |
| { |
| // Component properties |
| private ITableSessionStateManager m_objDefaultSessionStateManager = null; |
| private ITableColumnModel m_objColumnModel = null; |
| |
| // Transient objects |
| private ITableModel m_objTableModel; |
| private ITableModel m_objCachedTableModelValue; |
| |
| // enhanced parameter methods |
| public abstract ITableModel getTableModelValue(); |
| public abstract Object getSource(); |
| public abstract Object getColumns(); |
| public abstract IBinding getColumnsBinding(); |
| public abstract IBinding getPageSizeBinding(); |
| public abstract String getInitialSortColumn(); |
| public abstract boolean getInitialSortOrder(); |
| public abstract ITableSessionStateManager getTableSessionStateManager(); |
| public abstract ITableSessionStoreManager getTableSessionStoreManager(); |
| public abstract IComponent getColumnSettingsContainer(); |
| |
| // enhanced property methods |
| public abstract Serializable getSessionState(); |
| public abstract void setSessionState(Serializable sessionState); |
| |
| /** |
| * The component constructor. Invokes the component member initializations. |
| */ |
| public TableView() |
| { |
| initialize(); |
| } |
| |
| /** |
| * Invokes the component member initializations. |
| * |
| * @see org.apache.tapestry.event.PageDetachListener#pageDetached(PageEvent) |
| */ |
| public void pageDetached(PageEvent objEvent) |
| { |
| initialize(); |
| } |
| |
| /** |
| * Initialize the component member variables. |
| */ |
| private void initialize() |
| { |
| m_objTableModel = null; |
| m_objCachedTableModelValue = null; |
| } |
| |
| /** |
| * Resets the table by removing any stored table state. |
| * This means that the current column to sort on and the current page will be |
| * forgotten and all data will be reloaded. |
| */ |
| public void reset() |
| { |
| initialize(); |
| storeSessionState(null); |
| } |
| |
| public ITableModel getCachedTableModelValue() |
| { |
| if (m_objCachedTableModelValue == null) |
| m_objCachedTableModelValue = getTableModelValue(); |
| return m_objCachedTableModelValue; |
| } |
| |
| /** |
| * Returns the tableModel. |
| * |
| * @return ITableModel the table model used by the table components |
| */ |
| public ITableModel getTableModel() |
| { |
| // if null, first try to recreate the model from the session state |
| if (m_objTableModel == null) |
| { |
| Serializable objState = loadSessionState(); |
| m_objTableModel = getTableSessionStateManager().recreateTableModel(objState); |
| } |
| |
| // if the session state does not help, get the model from the binding |
| if (m_objTableModel == null) |
| m_objTableModel = getCachedTableModelValue(); |
| |
| // if the model from the binding is null, build a model from source and columns |
| if (m_objTableModel == null) |
| m_objTableModel = generateTableModel(null); |
| |
| if (m_objTableModel == null) |
| throw new ApplicationRuntimeException( |
| TableUtils.format("missing-table-model", getExtendedId())); |
| |
| return m_objTableModel; |
| } |
| |
| /** |
| * Generate a table model using the 'source' and 'columns' parameters. |
| * |
| * @return the newly generated table model |
| */ |
| protected ITableModel generateTableModel(SimpleTableState objState) |
| { |
| // create a new table state if none is passed |
| if (objState == null) |
| { |
| objState = new SimpleTableState(); |
| objState.getSortingState().setSortColumn(getInitialSortColumn(), getInitialSortOrder()); |
| } |
| |
| // update the page size if set in the parameter |
| IBinding objPageSizeBinding = getPageSizeBinding(); |
| if (objPageSizeBinding != null) |
| objState.getPagingState().setPageSize(objPageSizeBinding.getInt()); |
| |
| // get the column model. if not possible, return null. |
| ITableColumnModel objColumnModel = getTableColumnModel(); |
| if (objColumnModel == null) |
| return null; |
| |
| Object objSourceValue = getSource(); |
| if (objSourceValue == null) |
| return null; |
| |
| // if the source parameter is of type {@link IBasicTableModel}, |
| // create and return an appropriate wrapper |
| if (objSourceValue instanceof IBasicTableModel) |
| return new BasicTableModelWrap( |
| (IBasicTableModel) objSourceValue, |
| objColumnModel, |
| objState); |
| |
| // otherwise, the source parameter must contain the data to be displayed |
| ITableDataModel objDataModel = null; |
| if (objSourceValue instanceof Object[]) |
| objDataModel = new SimpleListTableDataModel((Object[]) objSourceValue); |
| else if (objSourceValue instanceof List) |
| objDataModel = new SimpleListTableDataModel((List) objSourceValue); |
| else if (objSourceValue instanceof Collection) |
| objDataModel = new SimpleListTableDataModel((Collection) objSourceValue); |
| else if (objSourceValue instanceof Iterator) |
| objDataModel = new SimpleListTableDataModel((Iterator) objSourceValue); |
| |
| if (objDataModel == null) |
| throw new ApplicationRuntimeException( |
| TableUtils.format( |
| "invalid-table-source", |
| getExtendedId(), |
| objSourceValue.getClass())); |
| |
| return new SimpleTableModel(objDataModel, objColumnModel, objState); |
| } |
| |
| /** |
| * Returns the table column model as specified by the 'columns' binding. |
| * If the value of the 'columns' binding is of a type different than |
| * ITableColumnModel, this method makes the appropriate conversion. |
| * |
| * @return The table column model as specified by the 'columns' binding |
| */ |
| protected ITableColumnModel getTableColumnModel() |
| { |
| Object objColumns = getColumns(); |
| |
| if (objColumns == null) |
| return null; |
| |
| if (objColumns instanceof ITableColumnModel) |
| { |
| return (ITableColumnModel) objColumns; |
| } |
| |
| if (objColumns instanceof Iterator) |
| { |
| // convert to List |
| Iterator objColumnsIterator = (Iterator) objColumns; |
| List arrColumnsList = new ArrayList(); |
| CollectionUtils.addAll(arrColumnsList, objColumnsIterator); |
| objColumns = arrColumnsList; |
| } |
| |
| if (objColumns instanceof List) |
| { |
| // validate that the list contains only ITableColumn instances |
| List arrColumnsList = (List) objColumns; |
| int nColumnsNumber = arrColumnsList.size(); |
| for (int i = 0; i < nColumnsNumber; i++) |
| { |
| if (!(arrColumnsList.get(i) instanceof ITableColumn)) |
| throw new ApplicationRuntimeException( |
| TableUtils.format("columns-only-please", getExtendedId())); |
| } |
| //objColumns = arrColumnsList.toArray(new ITableColumn[nColumnsNumber]); |
| return new SimpleTableColumnModel(arrColumnsList); |
| } |
| |
| if (objColumns instanceof ITableColumn[]) |
| { |
| return new SimpleTableColumnModel((ITableColumn[]) objColumns); |
| } |
| |
| if (objColumns instanceof String) |
| { |
| String strColumns = (String) objColumns; |
| if (getColumnsBinding().isInvariant()) |
| { |
| // if the binding is invariant, create the columns only once |
| if (m_objColumnModel == null) |
| m_objColumnModel = generateTableColumnModel(strColumns); |
| return m_objColumnModel; |
| } |
| |
| // if the binding is not invariant, create them every time |
| return generateTableColumnModel(strColumns); |
| } |
| |
| throw new ApplicationRuntimeException( |
| TableUtils.format("invalid-table-columns", getExtendedId(), objColumns.getClass())); |
| } |
| |
| /** |
| * Generate a table column model out of the description string provided. |
| * Entries in the description string are separated by commas. |
| * Each column entry is of the format name, name:expression, |
| * or name:displayName:expression. |
| * An entry prefixed with ! represents a non-sortable column. |
| * If the whole description string is prefixed with *, it represents |
| * columns to be included in a Form. |
| * |
| * @param strDesc the description of the column model to be generated |
| * @return a table column model based on the provided description |
| */ |
| protected ITableColumnModel generateTableColumnModel(String strDesc) |
| { |
| IComponent objColumnSettingsContainer = getColumnSettingsContainer(); |
| return TableUtils.generateTableColumnModel(strDesc, this, objColumnSettingsContainer); |
| } |
| |
| /** |
| * The default session state manager to be used in case no such manager |
| * is provided by the corresponding parameter. |
| * |
| * @return the default session state manager |
| */ |
| public ITableSessionStateManager getDefaultTableSessionStateManager() |
| { |
| if (m_objDefaultSessionStateManager == null) |
| m_objDefaultSessionStateManager = new TableViewSessionStateManager(this); |
| return m_objDefaultSessionStateManager; |
| } |
| |
| /** |
| * Invoked when there is a modification of the table state and it needs to be saved |
| * |
| * @see org.apache.tapestry.contrib.table.model.ITableModelSource#fireObservedStateChange() |
| */ |
| public void fireObservedStateChange() |
| { |
| saveSessionState(); |
| } |
| |
| /** |
| * Ensures that the table state is saved before the render phase begins |
| * in case there are modifications for which {@link #fireObservedStateChange()} |
| * has not been invoked. |
| * |
| * @see org.apache.tapestry.event.PageRenderListener#pageBeginRender(org.apache.tapestry.event.PageEvent) |
| */ |
| public void pageBeginRender(PageEvent event) |
| { |
| // 'suspenders': save the table model if it has been already loaded. |
| // this means that if a change has been made explicitly in a listener, |
| // it will be saved. this is the last place before committing the changes |
| // where a save can occur |
| if (m_objTableModel != null) |
| saveSessionState(); |
| } |
| |
| /** |
| * @see org.apache.tapestry.event.PageRenderListener#pageEndRender(PageEvent) |
| */ |
| public void pageEndRender(PageEvent objEvent) |
| { |
| } |
| |
| /** |
| * Saves the table state using the SessionStateManager to determine |
| * what to save and the SessionStoreManager to determine where to save it. |
| * |
| */ |
| protected void saveSessionState() |
| { |
| ITableModel objModel = getTableModel(); |
| Serializable objState = getTableSessionStateManager().getSessionState(objModel); |
| storeSessionState(objState); |
| } |
| |
| /** |
| * Loads the table state using the SessionStoreManager. |
| * |
| * @return the stored table state |
| */ |
| protected Serializable loadSessionState() |
| { |
| ITableSessionStoreManager objManager = getTableSessionStoreManager(); |
| if (objManager != null) |
| return objManager.loadState(getPage().getRequestCycle()); |
| return getSessionState(); |
| } |
| |
| /** |
| * Stores the table state using the SessionStoreManager. |
| * |
| * @param objState the table state to store |
| */ |
| protected void storeSessionState(Serializable objState) |
| { |
| ITableSessionStoreManager objManager = getTableSessionStoreManager(); |
| if (objManager != null) |
| objManager.saveState(getPage().getRequestCycle(), objState); |
| else |
| setSessionState(objState); |
| } |
| |
| /** |
| * Make sure that the values stored in the model are useable and correct. |
| * The changes made here are not saved. |
| */ |
| protected void validateValues() |
| { |
| ITableModel objModel = getTableModel(); |
| |
| // make sure current page is within the allowed range |
| ITablePagingState objPagingState = objModel.getPagingState(); |
| int nCurrentPage = objPagingState.getCurrentPage(); |
| int nPageCount = objModel.getPageCount(); |
| if (nCurrentPage >= nPageCount) |
| { |
| // the current page is greater than the page count. adjust. |
| nCurrentPage = nPageCount - 1; |
| objPagingState.setCurrentPage(nCurrentPage); |
| } |
| if (nCurrentPage < 0) |
| { |
| // the current page is before the first page. adjust. |
| nCurrentPage = 0; |
| objPagingState.setCurrentPage(nCurrentPage); |
| } |
| } |
| |
| /** |
| * Stores a pointer to this component in the Request Cycle while rendering |
| * so that wrapped components have access to it. |
| * |
| * @see org.apache.tapestry.BaseComponent#renderComponent(IMarkupWriter, IRequestCycle) |
| */ |
| protected void renderComponent(IMarkupWriter writer, IRequestCycle cycle) |
| { |
| Object objOldValue = cycle.getAttribute(ITableModelSource.TABLE_MODEL_SOURCE_ATTRIBUTE); |
| cycle.setAttribute(ITableModelSource.TABLE_MODEL_SOURCE_ATTRIBUTE, this); |
| |
| initialize(); |
| validateValues(); |
| super.renderComponent(writer, cycle); |
| |
| cycle.setAttribute(ITableModelSource.TABLE_MODEL_SOURCE_ATTRIBUTE, objOldValue); |
| } |
| |
| } |
