package com.ztes.commons.dbo.pagination;

import java.util.List;

import javax.sql.DataSource;
import org.springframework.jdbc.core.RowMapper;

/**
 * 分頁的通用接口，不同的數據庫分頁應實現該接口，一般情況建議繼承抽象類{@link com.ztes.commons.dbo.pagination.AbstractPage}實現。
 * 程序會先判斷當前查詢是否能使用SQL語句達到分頁效果（一般由子類實現），
 * 如果不能，則借助JDBC的功能從ResultSet中截取所需數據，這也是最通用的分頁方法，但是效率不高。
 * 特別注意的是，SQLServer2000在很多情況下不能簡單的使用SQL語句（請參考{@link com.ztes.commons.dbo.pagination.impl.PageSqlServer}）分頁，
 * 并且程序無法簡單的判斷這些情況，此時應手動指定使用JDBC的功能分頁，
 * 請調用{@link #setUseCommonPage(boolean)}方法，設置參數為true(默認為false)。
 * 通常來說，該接口有如下使用方式(假如已有一個實例page)：
 * <pre>
 * (1)只獲取某一段數據：
 * 舉例：
 * page.setDataSource( dataSource );
 * page.setQuerySql("select id,name from users");
 *  //設置不統計總記錄數(默認為統計)
 * page.setCountRecord(false);
 *  //取第11-20至條記錄
 * List list = page.getData(10, 10);
 * 
 * (2)實現分頁(當分頁的鏈接為本頁面時)：
 * page.setDataSource( dataSource );
 * page.setQuerySql("select id,name from users");
 *  //分頁鏈接構造器
 * PageParameterMaker pageParameterMaker = new PageParameterMaker(request);
 *  //設置翻頁鏈接帶的url參數
 * //pageParameterMaker.putParameter("id","1");
 *  //初始化分頁所需的一些參數，該方法多次被重寫，至少應調用一個
 * page.initPageParameter( pageParameterMaker );
 *  //得到當前頁的數據
 * List list = page.getData();
 *  //將翻頁的鏈接統計等信息作為html代碼返回
 * String html = page.getPageHtml();
 * </pre>
 * <p>
 * 如果分頁的數據從存儲過程（而不是SQL語句）中獲取，那么請使用{@link #setProcSql(String, Object[])}
 * 代替{@link #setQuerySql(String)}，存儲過程只允許帶輸入參數。
 * </p>
 * 
 * 默認情況下返回的列表中存儲的對象為Map，若是要指定其它對象，則可通過方法{@link #setRowMapper(RowMapper)}設置。
 * <p>
 * 在撰寫查詢sql語句時，建議補齊order by部分(盡管有默認的)，也就是說，完整的查詢語句應如同：
 * <br>select userId,userName from user order by userId
 * </p>
 * <p>
 * 如果查詢的數據量較大，建議使用{@link #setCountRecord(boolean)}方法設置參數為false，
 * 這樣就不用統計記錄總數，可以免去統計造成的效率影響(作者在測試oracle中千萬級數據時，發現獲取指定的數據效率很高，
 * 但是在統計總數時效率較低)。
 * </p>
 * <p>
 * 如果已知所有數據，想對它分頁獲取，那么可以調用{@link #extractData(List)}，使用該方法后同樣可以獲取一些分頁信息。舉例：
 * <pre>
 * page.initPageParameter( pageParameter );
 * //得到當前頁的數據
 * List list = page.extractData( allData );
 *  //將翻頁的鏈接統計等信息作為html代碼返回
 * String html = page.getPageHtml();
 * </pre>
 * </p>
 * @author tiannet(曾次清)
 */
public interface Page {

	/**
	 * 設置操作數據庫的數據源。
	 * @param dataSource 操作數據庫的數據源。
	 */
	public void setDataSource(DataSource dataSource);
	
	/**
	 * 設置查詢結果中每行的映射關系。調用了該方法后，
	 * 通過getData等方法返回的結果集中存儲的對象即為映射中指定的對象，
	 * 默認情況下，該對象是Map，以字段名為key，字段值為value。
	 * @param rowMapper 查詢結果中每行的映射關系。
	 */
	public void setRowMapper(RowMapper rowMapper);
	
	
	/**
	 * 設置持有分頁參數的對象。
	 * 建議使用PageParameterMaker(request);得到實例，
	 * 該構造函數會自動獲取當前頁碼、頁尺寸、請求頁面地址等參數。
	 * 對于普通的請求處理(尤其是翻頁只在本頁面跳轉)，建議使用該類初始化參數。
	 * @see com.ztes.commons.dbo.pagination.PageParameterMaker
	 * @see com.ztes.commons.dbo.pagination.PageParameterSimple
	 * @param pageParameter 持有分頁參數的對象。
	 */
	public void initPageParameter(PageParameter pageParameter);
	
	/**
	 * 設置分頁配置信息。
	 * @param pageConfig 分頁配置信息。
	 */
	public void setPageConfig(PageConfig pageConfig);
	
	/**
	 * 設置查詢sql語句。建議補全order by部分，如：
	 * select userId,userName from user order by userId。
	 * 它與{@link #setProcSql(String, Object[])}只能同時使用其一。
	 * @param querySql 查詢sql語句。
	 */
	public void setQuerySql(String querySql);
	
	/**
	 * 設置從存儲過程獲取數據分頁的一些參數。
	 * 它與{@link #setQuerySql(String)}只能同時使用其一。
	 * @param procName 存儲過程名稱。
	 * @param args 存儲過程輸入參數值，必須依照參數順序。
	 */
	public void setProcSql(String procName, Object[] args);
	
	/**
	 * 設置是否使用通用的分頁方法，即JDBC的接口分頁。
	 * 默認情況下，程序會先判斷能否支持sql語句分頁，如果不支持則使用JDBC分頁。
	 * 如果將該方法的參數設為true，則程序直接使用JDBC分頁，對于SQLServer2000的分頁，
	 * 可能存在很多不能使用SQL語句分頁的情況({@link com.ztes.commons.dbo.pagination.impl.PageSqlServer})，
	 * 此時應將該方法的參數設為true，使用JDBC的相關方法從ResultSet中提取數據。
	 * @param useCommonPage 是否使用通用的方法分頁，默認為否。
	 */
	public void setUseCommonPage(boolean useCommonPage);
	
	/**
	 * 設置是否統計總記錄數，默認為統計。
	 * 對于數據量大的查詢，為了避免因統計而影響效率，可以設置為不統計總記錄數。
	 * @param countRecord 是否統計記錄總數，默認為是。
	 */
	public void setCountRecord(boolean countRecord);
	
	/**
	 * 獲取分頁信息對象。
	 * @return 分頁信息對象。
	 */
	public PageInfo getPageInfo();
	
	/**
	 * 將翻頁的鏈接統計等信息作為html代碼返回。
	 * @return 翻頁的鏈接統計等信息的html代碼。
	 */
	public String getPageHtml();
	
	/**
	 * 獲取指定記錄中的某些記錄。
	 * @param allData 所有記錄集。
	 * @param start 記錄開始位置，從0開始。
	 * @param size 獲取記錄大小。
	 * @return 截取從start開始，大小為size的記錄。
	 */
	public List extractData(List allData, int start, int size);
	
	/**
	 * 對已知數據進行分頁處理。
	 * 獲取當前頁數據，取決于當前頁碼、每頁顯示的記錄數。
	 * @param allData 所有記錄集。
	 * @return 當前頁顯示的數據。
	 */
	public List extractData(List allData);
	
	
	/**
	 * 獲取從指定開始位置開始計的指定記錄數。
	 * @param start 記錄開始位置，從0開始。
	 * @param size 獲取記錄大小。
	 * @return List中的對象取決于RowMapper對象，如果未設置，則List的每個元素為一個Map對象，該Map以字段名稱為key，
	 * 字段值為value。
	 */
	public List getData(int start, int size);
	
	/**
	 * 獲取當前頁數據，取決于當前頁碼、每頁顯示的記錄數。
	 * @return List中的對象取決于RowMapper對象，如果未設置，則List的每個元素為一個Map對象，該Map以字段名稱為key，
	 * 字段值為value。
	 */
	public List getData();
	
}