ifieldlistener.java

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

/*
 * Created on 2006-6-27
 *
 * TODO To change the template for this generated file go to
 * Window - Preferences - Java - Code Style - Code Templates
 */
package net.excel.report.datasource;


/**
 * 数据源监听器主要用来监听一个数据源数据的字段值，一旦用户监听设定了要监听某个数据源的某个字段，
 * 那么一旦框架类需要重该数据源中取得该字段的值的时候都会触发监听程序，这样用户可以在框架取得该
 * 字段的真正的值前还有机会对该字段值进行处理。比如根据一个编号取得对应名称，
 * 或做一些复杂的计算操作等等。<br><br>
 * 使用示例：<br>
 * BaseDataSource ds = (BaseDataSource)dataSources.get("ds");<br>
 * if(ds != null){<br>
 * &nbsp;&nbsp;//装配数据源<br>
 * &nbsp;&nbsp;...<br>
 * &nbsp;&nbsp;//设置字段监听器<br>
 * &nbsp;&nbsp;ds.setFieldListener(new IFieldListener(){<br>
 * 	&nbsp;&nbsp;public Object getValue(IDataSource ds, String field, Object value) {<br>
 * 	&nbsp;&nbsp;&nbsp;&nbsp;//这里你可以修改value 的值，并返回<br>
 * 	&nbsp;&nbsp;&nbsp;&nbsp;if(field.equals("ptype")){<br>
 * 	&nbsp;&nbsp;&nbsp;&nbsp;...<br>
 * 	&nbsp;&nbsp;&nbsp;&nbsp;}<br>
 * 	&nbsp;&nbsp;}<br>
 * 	&nbsp;&nbsp;public String[] getFields() {<br>
 *  &nbsp;&nbsp;&nbsp;&nbsp;//监听 ptype 字段<br>
 *  &nbsp;&nbsp;&nbsp;&nbsp;return new String[] {"ptype"} ;<br>
 *  &nbsp;&nbsp;&nbsp;&nbsp;}<br>
 * 	&nbsp;&nbsp;});<br>
 * }<br>
 * @author juny
 * @since 1.0
 */
public interface IFieldListener {
    /**
     * 取字段值事件，在该事件中，你可以设置数据源的实际返回值，
     * 返回null则跳过，取数据源的原始值。<br>
     * 注意：<br>
     * 1. 在该函数中千万不要再通过数据源去取本身正在监听的字段值，因为该操作会引起字段监听的循环
     * 调用，切记！。<br>
     * 2. 当同时监听多个字段值时，由于多个字段都调用这个函数，所以一定要注意不能出现循环等待
     * 的情况,如监听A，B，C三个字段，其中取A值时依赖B字段的值，而取B字段的值又依赖于C字段的值，
     * 但这时千万不能出现取C字段的值又要依赖于A/B字段值的情况，因为这时A/B字段还在等C返回结果。一定要切记。否则程序将会陷入死循环
     * 等待状态。
     * <br><br>
     * 当然该问题可以通过设置每一个字段都引入一个独立的监听对象实例来解决，但这样会增加设置监听器的
     * 代码量。
     * @param ds 当前被监听的数据源实例。
     * @param field 字段当前取值的字段名称
     * @param value 当前字段在数据源中的原始值。
     * @return null 忽略用户返回的数据，取数据源的原始数据字段的值；非null 
     * 返回该字段的实际值，该值将被写入报表中。
     */
    public Object getValue(IDataSource ds, String field, Object value);
    
    /**
     * 重载该函数，设置你需要监听那些字段。
     *           返回null则监视所有字段。<br><br>
     * 注：字段的匹配不区分大小写。当用户指定监听字段时，如果出现没有指定的字段，
     * 系统是不会调用该监听器的函数的。
     * @return 非null 返回监听字段名称数组。null 则表示监听所有字段值。
     */
    public String[] getFields();
}