page.java

适合各种数据库的分页程序

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();
	
}