idatasource.java

Excel Report是一款基于Excel的报表生成工具

package net.excel.report.datasource;

import java.util.Map;

import net.excel.report.config.DataSourceConfig;



/**
 * 数据源接口, 数据源是报表数据来源, 生成报表数据时报表框架程序会从DataSource中检索数据.
 * @author juny
 */
public interface IDataSource {
    /**
     * 设置数据源配置信息。
     * @param config 数据源配置信息对象。
     * @param name 数据源名称。
     */
    public void setConfigInfo(DataSourceConfig config, String name);
    /**
     * 取得数据源名称
     * @return 返回数据源的名称
     */
    public String getName();
      
    /**
     * 取得DataSource对应的配置对象 
     * @return 返回本数据源实例对应的数据源配置对象
     */
    public DataSourceConfig getConfig();
    
    /**
     * 保存属于本dataSource的参数,传入所有参数列表.
     * 该函数搜寻传入的参数列表,并插入或替换新的参数值.
     * 2006-07-26 value改为Object为了兼容以后增加对多类型的支持。
     * @param param 本数据源对应输入参数的名称
     * @param value 参数值
     */
    public void setParameter(String param, Object value);
    
    /**
     * 取得当前数据源中参数信息
     * @return 取得当前数据源中的输入参数。
     */
    public Map getParams();
    
    /**
     * 取得对应字段类型，如果该字段没有在配置文件中定义
     * 则返回null
     * @param fieldName 字段名称
     * @return 非null 则返回字段类型值；null 该字段没有定义类型
     */
    public String getFieldType(String fieldName);
    
    /**
     * 检索数据,必须判断所有配置文件中配置的输入参数都有
     * 相应的值. 否则该函数返回失败,并抛出异常.
     * @return 返回检索数据的状态：QUERY_FAILURE，QUERY_SUCCESS
     * @throws Exception 如果数据源的输入参数无效则抛出异常。
     */
    public int queryData() throws Exception;
    
    /**
     * 数据源数据记录游标移动到首记录。
     * @return true 游标移动到记录集的首记录位置; false 无法移动游标。
     */
    public boolean moveToFirst();
    
    /**
     * 记录集游标移动到下一条记录.
     * @return 成功则返回移动前的记录值。（注意：请不要通过这中方式来访问记录的值，
     * 因为该函数有可能会修改返回值的类型）
     */
    public Map next();
    
    /**
     * 判断是否还存在下一条记录.
     * @return true 记录集中还存在下一条记录。 false 记录集已经到最后一条记录。
     */
    public boolean hasNext();
    
    /**
     * 撤销移动到下一条记录操作，在分组中会用到。
     */
    public void undoNext();
    
    /**
     * 从当前记录集中取得指定字段值.
     * @param fieldName 字段名称
     * @return 返回字段值，以String方式表示。
     */
    public String getString(String fieldName);
    
    /**
     * 从当前记录集中取得指定字段值.以Object对象方式返回。
     * @param fieldName 字段名称
     * @return 成功 返回非空的Object对象； 失败 返回null。
     */
    public Object getValue(String fieldName);
    
    /**
     * 数据源中记录条数。
     * @return 返回记录条数。
     */
    public int size();
    
    /**
     * 取得数据源类型。
     * @return 返回当前数据源的类型。
     */
    public String getType();
    
    /**
     * 初始化数据源对象. 系统在构建一个数据源对象实例时会调用该函数，
     * 该函数设计的初衷是当在构建某些用户自定义的数据源时可能需要某些初始化操作，
     * 这是用户可以重载该函数来实现，系统保证在构建数据源实例时会调用该函数一次，
     * 来进行初始化操作。典型的是在某些需要手动管理数据库连接的应用当中，
     * 可以在该函数中获得一个连接，并在destroy函数中释放相应连接。
     * @return 
     * @throws Exception
     * @see IDataSource#destroy()
     */
    public boolean initialize() throws Exception;
    
    /**
     * 释放数据源对象。具体用法参见initialize()
     * @throws Exception
     * @see IDataSource#initialize()
     */
    public void destroy()throws Exception;
    
    /**
     * 检索数据失败.
     */
    final static int QUERY_FAILURE = -1;
    /**
     * 检索数据成功.
     */
    final static int QUERY_SUCCESS = 1;
}