package com.esri.solutions.jitk.web.data.results;

/**
 * This class is an abstraction around arbitrary data binding technologies that 
 * can be used to adapt a variety of data sources that support per-row 
 * processing for their child components.
 * 
 * <p/>
 * The data collection underlying a table model instance is modeled as a 
 * collection of row objects that can be accessed by a 0-based cursor 
 * (row index).
 * 
 * <p/>
 * The table model supports paging through a result set viewing a specified 
 * number  of rows (page size) at a time.
 * 
 * <p/>
 * A concrete table model instance is attached to a particular collection of 
 * underlying data by calling the <code>setData(java.lang.Object)</code> 
 * method. It can be detached from that underlying data collection by passing 
 * a </code>null</code> parameter to this method.
 * 
 * Concrete implementations must provide a public o-arguments constructor that 
 * calls <code>setData(null)</code>. A convenience constructor that takes a 
 * data object of the appropriate type (and passes it on via a call to 
 * <code>setData(java.lang.Object)</code>, should also be provided.
 * 
 * @author Carsten Piepel
 *
 */
public interface TableModel {
    
    /**
     * Return the number of rows of data objects represented by this 
     * table model. If the number of rows is unknown, 
     * or no <code>data</code> is available, return <code>-1</code>.
     * 
     * @return the number of rows of data objects.
     */
    int getRowCount();
    
    /**
     * Return a flag indicating whether there is row data 
     * available at the current row index. If no 
     * <code>data</code> is available, return <code>false</code>.
     * 
     * @return true if row data is available at the current row index, or false 
     * otherwise.
     */
    boolean isRowAvailable();
    
    /**
     * Return an object representing the data for the currenty selected 
     * row index. If no <code>data</code> is available, return 
     * <code>null</code>.
     * 
     * @return an object representing the data for the currently selected row.
     * 
     * @throws java.lang.IllegalStateException if no <code>data</code> is 
     * available.
     * @throws DataBindingException if an error occurs accessing the currently
     * selected row
     */
    Object getRowData() throws DataBindingException;
    
    /**
     * Return an object representing the data at the specified row index. 
     * If no <code>data</code> is available, return <code>null</code>.
     * 
     * @return an object representing the data at the specified row index.
     * 
     * @throws java.lang.IllegalStateException if no <code>data</code> is 
     * available.
     * @throws java.lang.IllegalArgumentException if <code>rowIndex</code> 
     * is less than <code>0</code> or greater than or equal to 
     * <code>getRowCount()</code>. 
     * @throws DataBindingException if an error occurs accessing the currently
     * selected row
     */
    Object getRowData(int rowIndex) throws DataBindingException;
    
    /**
     * Return the 0-based index of the currently selected row. If we are not 
     * currently positioned on a row, or no <code>data</code> is available, 
     * return <code>-1</code>.
     * 
     * @return the index of the currently selected row 
     */
    int getRowIndex();
    
    /**
     * Set the 0-based index of the currently selected row, or 
     * <code>-1</code> to indicate that we are not positioned on a row. It 
     * is possible to set the row index at a value for which the underlying 
     * data collection does not contain any row data. Therefore, callers may use 
     * the <code>isRowAvailable()</code> method to detect whether row data 
     * will be available for use by the <code>getRowData()</code> method.
     * 
     * <p/>
     * If there is no <code>data</code> available when this method is 
     * called, the specified row index is stored (and may be retrieved by a 
     * subsequent call to <code>getRowData()</code>), but no event is sent. 
     * Otherwise, if the currently selected row index is changed by this call, a 
     * <code>RowSelectionEvent</code> will be sent to the 
     * <code>rowSelected()</code> method of all registered 
     * <code>RowSelectionListeners</code>.
     * 
     * @param rowIndex the index of the currently selected row
     * 
     * @throws java.lang.IllegalArgumentException if <code>rowIndex</code> 
     * is less than <code>-1</code>.
     */
    void setRowIndex(int rowIndex);
    
    /**
     * Return the number of pages represented by this 
     * table model. This is a convenience method for 
     * <code>itemCount / pageSize</code>.
     * 
     * @return the number of pages
     */
    int getPageCount();
    
    /**
     * Return the maximum number of rows displayed on a page. If all rows
     * will be displayed on one page, return <code>0</code>.
     * 
     * @return the maximum number of rows displayed on a page.
     */
    int getPageSize();   
    
    /**
     * Set the maximum number of rows displayed on a page. If all rows should be
     * displayed on one page, set this value to <code>0</code>.
     * 
     * @param pageSize the maximum number of rows displayed on a page.
     * 
     * @throws java.lang.IllegalArgumentException if <code>pageSize</code> 
     * is less than <code>0</code>.
     */
    void setPageSize(int pageSize);
    
    /**
     * Return the 0-based index of the currently selected page. If we are not 
     * currently positioned on a page, or no <code>data</code> is available, 
     * return <code>-1</code>.
     * 
     * @return the index of the currently selected page 
     */
    int getPageIndex();
    
    /**
     * Set the 0-based index of the currently selected page, or 
     * <code>-1</code> to indicate that we are not positioned on a page. 
     * 
     * <p/>
     * If there is no <code>data</code> available when this method is 
     * called, the specified page index is stored (and may be retrieved by a 
     * subsequent call to <code>getRowData()</code>), but no event is sent.
     * If the currently selected page index is changed by this call, a 
     * <code>PageChangeEvent</code> will be sent to the 
     * <code>pageChanged()</code> method of all registered 
     * <code>PageChangeListeners</code>.
     * 
     * @param pageIndex the index of the currently selected row
     * 
     * @throws java.lang.IllegalArgumentException if <code>pageIndex</code> 
     * is less than <code>-1</code> or if <code>pageIndex</code> is 
     * greater than <code>pageCount</code>.
     */
    void setPageIndex(int pageIndex);
    
    /**
     * Return the object representing the data bound to this table model, if 
     * any.
     * 
     * @return the object representing the data bound to this table model or 
     * null if no data is bound.   
     */
    Object getData();
    
    /**
     * Set the object representing the data collection bount to this table 
     * model. If the specified data is <code>null</code>, detach this table 
     * model from any previously bound data collection instead.
     * 
     * <p/>
     * If the data collection bound to table model is changed by this call, a
     * <code>DataBindingEvent</code> must be sent to the 
     * <code>dataBindingChanged</code> method of all registered 
     * <code>DataBindingListeners</code> indicating that the data source 
     * changed.
     * <p/>
     * If data is non-null, the currently selected row index must be set to 
     * zero, and a <code>RowSelectionEvent</code> must be sent to the 
     * <code>rowSelected()</code> method of all registered 
     * </code>RowSelectionListeners</code> indicating that this row is now 
     * selected.
     */
    void setData(Object data);
    
    // TODO: add comment
    void setEntityInfo(EntityInfo entityInfo);
    
    // TODO: add comment
    EntityInfo getEntityInfo();
    
    /**
     * Add a new <code>DataBindingListener</code> to this table model.
     * 
     * @param listener the new listener to be registered
     * 
     * @throws java.lang.NullPointerException if the specified listener is 
     * <code>null</code>.
     * 
     */
    void addDataBindingListener(DataBindingListener listener);
    
    /**
     * Remove a <code>DataBindingListener</code> from this table model.
     * 
     * @param listener the old listener to be unregistered
     * 
     * @throws java.lang.NullPointerException if the specified listener is 
     * <code>null</code>.
     * 
     */
    void removeDataBindingListener(DataBindingListener listener);
    
    /**
     * Add a new <code>RowSelectionListener</code> to this table model.
     * 
     * @param listener the new listener to be registered
     * 
     * @throws java.lang.NullPointerException if the specified listener is 
     * <code>null</code>.
     * 
     */
    void addRowSelectionListener(RowSelectionListener listener);
    
    /**
     * Remove a <code>RowSelectionListener</code> from this table model.
     * 
     * @param listener the old listener to be unregistered
     * 
     * @throws java.lang.NullPointerException if the specified listener is 
     * <code>null</code>.
     * 
     */
    void removeRowSelectionListener(RowSelectionListener listener);
    
    /**
     * Add a new <code>PageChangeListener</code> to this table model.
     * 
     * @param listener the new listener to be registered
     * 
     * @throws java.lang.NullPointerException if the specified listener is 
     * <code>null</code>.
     * 
     */
    void addPageChangeListener(PageChangeListener listener);
    
    /**
     * Remove a <code>PageChangeListener</code> from this table model.
     * 
     * @param listener the old listener to be unregistered
     * 
     * @throws java.lang.NullPointerException if the specified listener is 
     * <code>null</code>.
     * 
     */
    void removePageChangeListener(PageChangeListener listener);
}