ValueList

ValueList的OverView
概述
在很多情况下，使用JDBC是很繁琐的，有很多方法可以替换JDBC，比如JDO、Hibernate等。
即使在从service中接收POJO的List的解决方案中，我们仍然鼓励使用ValueListHandler来统一访问所有的service。在这种情况下，你应该实现自己的ValueListAdapter，它的作用是调用你的业务方法，同时也要把查询结果转换为一个ValueList。
配置
mlavwilson.properties文件是ValueListHandler服务标签库的配置文件,它包含了定制外观和定制属性的一些配置。但是，这个文件现在已经不再推荐使用了。
对于在Web下怎么使用Spring，请看www.springframework.org/docs/reference/beans.html。                                          

下面这个文件是例子中的配置文件：


上面配置文件中的bean“valueListHandler”是一个服务，这个服务有用于valueListHandler的adapter的map，使用Spring关联adapter，可以使这些adapter以统一的方式配置。下图是一个真实项目的配置文件：
 
怎么使用service？
上文简述了怎么向valueListHandler中添加adapter和query，从例子中的配置片断中你可以看到有一个叫做"nbaTeams"的adapter，它是从team表中select数据的查询。通过这个查询，我们将逐步解决查询返回的数据。
得到service的实例
ValueListHandler是一个接口，所以你要实现它。在Web环境中，最简单的获取ValueListHandler的方法是使用Spring来获取。

准备调用service
在服务被调用之前，必须创建ValueListInfo，它包含下面的内容：
Filter 构造查询的Map
排序列 用于排序的列（一个或者多个）
排序方向 用于排序的方向（一个或者多个列）
页号 当前页号，如果为空的话，则service会设置它
总记录数 调用后，被server设置
行数/页 每页上显示的记录的行数
条件的属性 用于指定条件查询的属性名，相当于列名
条件的值 指定条件的值，相当于指定的列的值
创建info对象，按照“team”列排序

从服务中请求ValueList

这个方法将返回一个ValueList，它包含一个List和传给service的info。ValueList也是一个Iterator，下面是接收它的方法：
1． 第一个参数是adapter的名字，上面的代码中的adapter的名字是“nbateams”，这个adapter在上面的xml文件中已经配置好了。
2． adapter用于从数据库中接收数据。作为“ValueListHandler”配置中的adapter，它必须实现ValueListAdapter接口。
3． 现在service已经有数据了。service还有一个机会去更改ValueList：如果service想对数据进行排序、分页、过滤，它可以使用adapter的方法getAdapterType。这样如果需要，adpater就可以代理分页、排序、过滤等功能。
4． service返回ValueList。
显示ValueList：
在Web环境下，有一些标签用于显示ValueList，它们将在以后讨论。显示ValueList也有一个Jtable的实现。当然我们并不限制你用哪种方式。
标签的例子：

代码说明：
行号 名称 描述 Since
1 vlh:root 这个标签是必须的，他是所有vlh元素的顶级元素。 0.1.3
2 vlh:retrieve 它调用ValueListHandler，并请求ValueList，然后把ValueList传给vlh:root标签。
注意：如果你不使用MVC的push模式的话，应该使用该标签。(push:是指数据是由数据是由框架推向显示页面的，显示页面并不能主动取得数据，相对于“拉”) 0.1.1
5 vlh:row 这是一个iterate标签，它对ValueList进行循环显示。 0.1.0
6－11 vlh:column 它指定显示哪个属性（字段）。 0.1.0

更多的细节和示例，请参见valuelist.war。
内置的adapter
DefaultDynaBeanAdapter
返回DynaBean的一个ValueList。对于简单的程序或者例子来说，它是很有用的。但我们不推荐你在真正的程序里面使用它。
DefaultDynclassAdapter
返回Dynclass的一个ValueList。对于简单的程序或者例子来说，它是很有用的。但我们不推荐你在真正的程序里面使用它。
DefaultWrapperAdapter
返回封装了ResultSet的ValueList，我推荐在在下列情况下使用：Hibernate的HQL太复杂，不能控制所有的复合连接。
FileSystemAdapter
返回FileInfo的ValueList，在Web上浏览一个文件系统时，它是很有用的。
Hibernate20Adapter
返回POJO的ValueList。它也能返回指定条件的一条记录。
除了FileSystemAdapter，其他的adapter都可以调用行的校验。
你可以在Hibernate20Adapter找到简单的用法。

在MVC框架中怎么使用ValueList
这部分的主要目的是要解决“刷新按钮问题”（就是点击“刷新”按钮引起的问题）。
在Web程序中，你可能常常redirect到一个“view”上,并且要保证不能丢失分页、排序、查询条件的信息（focus：在原文中多次出现“focus”，按照上下文的理解应该是按照指定条件进行查询的意思）。
请考虑下面的情况：
你要删除一条数据，如果你是通过向请求字符串中添加一个转向参数（注：这个请求类似于：http://localhost:8080/jbxx.do?method=delete&id=123456）来实现的话，可能在删除数据后，转向到一个显示结果的jsp。但是如果用户点击“刷新”按钮，则还会提交同样的请求。（注：我在使用AppFuse的过程中也遇到这样的问题，DisplayTag没有处理这种情况，所以会执行同样的动作，但是数据已经在前一步被删除了，所以数据库会报错，我使用Struts的saveToken的方法来解决了这个问题，但我发现AppFuse的原来的用户部分就不会报这个错误，后来发现它转向的视图还是当前页面，所以没有这个问题。）。
所以，我们需要实现一个service helper类来解决这个问题。
得到service的helper的实例
ValueListHandlerHelper是在设置任何ValueListHandler实现前必须创建的一个类，在Web环境下，最简单的办法是使用Spring的bean Factory来创建它。

下一步是告诉你的Controller你要使用哪个service的helper类的实例。


“刷新”按钮问题的解决方案
现在，我们来关注更多的细节，设想一下：
在jsp中，我们有一个id="MyTable".的表，Struts的Controller的代码可能如下：

首先，我们必须得到ValueList的实际的info，我们可以修改它，然后，把它备份到Session中。
如果请求中没有任何id=”MyTable”的Table的信息，它会试着从上一个保存的备份（ValueListInfo）中获取。因此，在执行每个Action后，必须备份ValueList的info。
更多的信息，请参见：
• javadoc for the ValueListHadlerHelper 或者看
• source the code of this struts's controller 或者看例子
• valuelist.war 的下面的部分： '经过MVC的ValueListHandlerHelper备份ValueListInfo到session中'。
例子
如果你想找一个好的、使用ValueList的例子的话，请参见Fantasy Sports Components的配置文件。这个文件里面有一个叫做“playerRank”的查询，这个查询有left join, inline view和大量的group by，它使用的是DefaultDynaBeanAdapter。

2005-03-04 13:36

Hibernate20Adapter的文档
原文：http://valuelist.sourceforge.net/adapters/Hibernate20Adapter.html
属性
名称 必需 默认值 描述
adapterType N 0 1.JVM中排序
2.JVM中分页
4.在JVM中过滤(还没有实现)
sessionFactory Y N/A Hibernate SessionFactory的实例
hsql 废弃 建议使用hql代替
hql Y 必需有一个
2个中的一个 Spring配置文件中定义的查询
namedQuery N 定义在你的Hibernate的映射文件中查询的名字。如果你想使用排序和条件查询的话，我们推荐你不要使用这个属性。
defaultNumberPerPage N Integer.MAX_VALUE 每页显示的记录数，可以被ValueListInfo中的值覆盖。
defaultSortColumn N N/A 结果集排序的列，可以被ValueListInfo中的值覆盖。
defaultSortDirection N N/A 可以被ValueListInfo中的值覆盖。
allowCreate N true 如果在绑定的线程中没有发现，允许创建一个新的Session
maxRowsForFocus N Long.MAX_VALUE 进行focus查询的结果集的最大行数
defaultFocusPropertyObjectAlias N "" 从Hibernate的SQL语法中得到focus属性的对象的名字：SELECT defaultFocusPropertyObjectAlias.focusProperty FROM XXX
removeEmptyStrings N false 是否使用给定的filter 的值的长度检测，如果filter的值是null或者“”，将从查询中被删除。
validator N null 对已经查询出来的记录进行后期处理的Validator
focusOptimalization N true 在focus查询的时候，是否使用statement的优化功能
statementBuilder N 所有属性的字符串setter的隐式对象(Implicit object) 支持Long, Timestamps和其他的hibernate类型设置Hibernate查询的"preparedStatement" 。它用于filter的conjuction

使用HQL属性的图：

使用NamedQuery的属性的图：

配置文件的例子：

需要注意的是：在<hql>标签中的HQL不是一个有效的hql。
/~sortColumn: ORDER BY [sortColumn] [sortDirection]~/ 包含 “/”、“~”、“[”和“]”。 下面让我为你解释这些无效的字符都是起什么作用的。

Filter
你可以使用某些条件限制的ValueList的记录。我们要感谢叫做“Filter”的东西，Hibernate20Adapter使用ValueListInfo.filters的值去动态构造查询。
应用规则如下：
• /~sortColumn: ~/ 被称做filter。 只有ValueListInfo.filters 包含'sortColumn'时，
/~ 和~/之间的内容才会被包含。
• [sortColumn] 被称作constant。 [ 和 ] 之间的内容将被ValueListInfo.filters map的值替换。 例如:
'ORDER BY [sortColumn] DESC' = 'ORDER BY my_sorted_column DESC'
• {name} 被称作 bind varable。{ 和 } 之间的内容被? 替换，然后ValueListInfo.filters map中的值将被设置到PreparedStatement。例如:
'WHERE user.name = {name}' = 'WHERE user.name = :name'
注意： 默认情况下，Hibernate20Adapter将你的bind varable作为PreparedStatement的一个字符串。(通常像这样：Query.setString("name",(String) valueListInfo.getFilters().get("name"));) 当然，Hibernate20Adapter也可以设定其他类型，如Timestamps，但你需要用你的key和key的类型的名字声明map。这种map的管理者叫做StatementBuilder。

bind varable：
• {name} 将被设置为String。
• {myLongId} 将被设置为Long。
(你可以这样设想:
Query.setLong("myLongId",(Long) valueListInfo.getFilters().get("myLongId"));)
注意： StatemntBuilder与在基于adapter的jdbc中的用法类似。See war example adapters config file.
Focusing
如果你想使用focus特性，你可以直接设置focusValue, focusProperty，它们告诉Hibernate20Adapter你将focus什么。当你点击下一页按钮时，Focus将会被自动关闭，所以，你必须使它可以使用（Enable）。
例如：


例子中的第一列不能被排序，你可以设定sortable="desc"，这样就可以排序了。
下一个非常有用的标签是：focusStatus，它会告诉你当进行focus搜索时正在发生什么。
如果能用Focus，这个标签将会创建一个Table。如果你设置focusproperty为一个非null的值时，focus将可以使用。更多的细节请看：focus status tag。

Validator
我们经常会遇到这样的情况，我们使用Hibernate接收数据是非常复杂的。此时，你应该使用ObjectValidators。Validator帮你使用JVM级别的过滤，并且仍然支持分页和Hibernate20Adapter的其他功能。
使用Validator之前，你需要做如下的工作：
1． 实现你的ObjectValidator接口

2． 创建Bean：PlayersObjectValidator，并将Hibernate20Adapter的validator属性设置为PlayersObjectValidator。

• 这个解决方案在如下情况下是适用的：如果在数据库层不能filter，则可以使用这种方法。因为它是在JVM级别进行操作的，所以效率很差。
• 你也应该为focus关闭查询的optimalization。如果你设定focusOptimalization 为false，则会实现这个目的。
• 正常情况下，在被focus的对象所在的页上，focus选择只针对focusproperty的属性 (比如，一个普通的数字 - id) ，并且不是针对整个对象的快速探测。这样你只需要控制focus属性，你可以打开optimalization。
更多的信息请参见示例的war文件 (version 0-1-7Beta9或者更高的版本)。
2005-03-04 15:58

ValueList的Tutorial
我只翻译了主要步骤
1． 配置数据源
我们为WEB-INF/classes/applicationContext.xml文件添加MySQL数据源，添加后，文件内容如下：

2． 配置ValueListAdapter
原始的WEB-INF/classes/applicationContext.xml文件中有2个adapter entry，类型都是net.mlw.vlh.adapter.file.FileSystemAdapter，删除它们，再添加一个新的。
我们的查询依赖于数据库，所以我们使用DynaBeanAdapter（你也可以写自己的adapter）。我们希望每页显示20条记录，并且按照points_avg排序。

3． 创建一个JSP
在目录WEB-INF/jsp/reports下创建一个新的叫做playerRank.jsp的jsp。我们首先把report1.jsp中的内容复制进来：


行号 描述
1－2 导入这页中用到的标签。
8 这个report的title。
12 Vlh：root标签是所有其他vlh标签都需要的父标签。
13 vhl:retrieve标签调用ValueListHandler服务，然后接收一个ValueList。注意 name="playerRank"属性，它必须和上文讨论的applicationContext.xml文件中的一个 adapter entry相匹配。

15 vhl:row标签将对ValueList进行循环，并创建table。
16－18 vhl:column 标签在table中添加一列。
添加完所有需要定义的列之后，我们的jsp内容如下：

4． 为我们的新report添加一个链接
打开文件：jsp/layout/Header.jsp.

删除2个例子的链接，添加一个新链接。你也可以用自己公司的Logo和名字覆盖掉默认的Logo和名字。
注意：URL中的参数report的值是jsp的名字，没有扩展名”.jsp”。使用的是Spring的MVC框架。

2005-03-04 16:31

在Struts或其他框架中使用ValueList：在Struts或其他框架中使用ValueList
原文链接：http://adigio.com/blogs/kris/archives/2004/09/how_to_setupval.html

ValueList是一个需要Spring支持的工具，它和DisplayTag和DataGrid的很大的不同是-它使用Spring处理从数据库中获取的数据，在Display和DataGrid中，你从一个collection中接受数据，然后在collection上处理分页，但是，如果你的collection中超过5000条记录呢？而ValueList查询的只是你需在当前页显示的数据，所以，即使数据量再大，对它来说也不是问题。Valuelist使用以一种清晰的解耦办法将数据层和表示层进行分离。
因为valuelist文档很少，所以，我愿意把用我的痛苦总结出来的经验分享给你，因为它真的很好！
在下面的例子中，我使用它提供的jdbcAdaptor，当然你可以使用其他的像Hibernate的适配器，或者你自己写的适配器。
共有如下几个文件：
applicationContext.xml
view.jsp
CustomAdaptor
Struts Action
第一步 配置文件
你需要有一个Spring的applicationContext.xml文件，并且添加valuelist的entry。
<bean id="valueListHandler" singleton="true" class="net.mlw.vlh.DefaultValueListHandlerImpl">
       <property name="config.adapters">
       <map>

         <entry key="jobListByJobKey">
           <bean class="com.xcel.flipper.console.dao.adapters.JobHistoryAdapter">
             <property name="dataSource"><ref bean="flipperDataSource"/></property>
             <property name="useName"><value>false</value></property>
             <property name="defaultNumberPerPage"><value>8</value></property>
             <property name="defaultSortColumn"><value>startdate</value></property>
             <property name="defaultSortDirection"><value>asc</value></property>
             
             <property name="sql">
               <value>
              
                 select el.JOB_KEY as jobKey,
   el.START_DATE_TIME as startdate,
   el.END_DATE_TIME as enddate,
   job.job_name as jobname,
   jobstatus.job_execution_status_descr as status
   From JOB_EXECUTION_LOG el,
   JOB job,
   JOB_EXECUTION_STATUS jobstatus
   where el.job_key = job.job_key
   and jobstatus.job_execution_status_code = el.job_execution_status_code
   /~jobId: and el.job_key = {jobId}~/
   /~sortColumn: ORDER BY [sortColumn] [sortDirection]~/
             </value>
            </property>
          </bean>
        </entry>
关键问题是怎么得到输入的参数：
/~jobId: and el.job_key = {jobId}~/
/~sortColumn: ORDER BY [sortColumn] [sortDirection]~/
也就是说在request中有一个叫做jobId的参数，它很可能是从form的一个post动作中提交过来的。还有2个参数－SortColumn和sortDirection，不需要你手工的放入request中，当用户点击视图中的需要排序的列时，valuelist会自动为你修改这些参数的。需要注意的是，在上面的配置的前面有一个默认的排序列和排序方向。你可以在列的标题附近看到一个用于排序的箭头，它们用来链接排序的列。你可以查看例子的截屏。
第二步 创建定制的适配器
public class JobHistoryAdapter extends AbstractJdbcAdapter {
    public List processResultSet(String name, ResultSet result, int numberPerPage) throws SQLException
    {
      List list = new ArrayList();

      for ( int rowIndex = 0; result.next() && rowIndex < numberPerPage; rowIndex++)
      {
          JobHistoryDisplayBean historyBean = new JobHistoryDisplayBean();
              
          historyBean.jobLog.setJobInstanceKey(result.getString("jobKey"));
          historyBean.jobLog.setStartDateTime(result.getDate("startdate"));
          historyBean.jobLog.setEndDateTime(result.getDate("enddate"));
          historyBean.job.setJobName(result.getString("jobname"));
          historyBean.status.setJobExecutionStatusDescr(result.getString("status"));
          list.add(historyBean);                   
      }
      return list;
    } 
}
请注意：我从result中抽取查询的值，然后把它复制到Bean中。Result的变量的名字字是我在上面的配置文件中配置的，如startdate，而不是START_DATE_TIME。
第三步 建立你的Action类
如果你使用Struts，那么在你的Action中加入下面的代码：
ValueList valueList = getValueListHandler().getValueList("jobListByJobKey",
ValueListRequestUtil.buildValueListInfo(request));
    request.setAttribute("list", valueList);
如果你使用WebWork，那么应该写在自定义的Interceptor中。程序将调用applicationContext.xml文件中的配置，然后把结果list写入request中。ValueList的显示和DisplayTag非常相似，但不同的是DisplayTag将所有结果都放入request中，而valuelist则只放入当前页面需要显示的数据，那些不需要显示的则不会被放入request中。在ValueList中，这个collection的尺寸是一页需要显示的数据数，是在上面的配置文件中由defaultNumberPerPage的值指定的，在我的这个例子中，它的值是8。
如果你想查询其他的东西，那么你只需要在代码中调用其他的entry的name就行了。
第四步 创建视图
<vlh:root value="list" url="?" includeParameters="*">


<table width="450">
<!-- pagination section -->
<tr>
<td align="left" nowrap="true">
<c:out value="${list.valueListInfo.totalNumberOfEntries}"/> Total
- Page (<c:out value="${list.valueListInfo.pagingPage}"/> of <c:out value="${list.valueListInfo.totalNumberOfPages}"/>)

</td>
<td align="right">
<vlh:paging />
</td>
</tr>
<!-- end of Pagination -->
<tr>
<td colspan="2">
<table width="650" class="classicLook" cellspacing="0" cellpadding="0">
<vlh:row bean="job">
<vlh:attribute name="onclick">document.location='viewJobDetails.do?jobInstanceId=<c:out value="${job.jobInstanceKey}"/>';</vlh:attribute>
<vlh:attribute name="onmouseover">this.className='selected';</vlh:attribute>
<vlh:attribute name="onmouseout">this.className='zebra0';</vlh:attribute>

<vlh:column title="Start Date" property="startDateTime"       sortable="desc" />
<vlh:column title="End Date" property="endDateTime"           sortable="desc" />
<vlh:column title="Job Name" property="jobName"        sortable="desc" />
<vlh:column title="Job Status" property="status"           sortable="desc" />

</vlh:row>
</table>
</td>
</tr>
</table>

</vlh:root>
最后一步是添加tld到web.xml中
<taglib>
    <taglib-uri>valuelist.tld</taglib-uri>
    <taglib-location>/WEB-INF/tlds/valuelist.tld</taglib-location>
</taglib>

总结
valuelist的设置步骤的确比Display和DataGrid多，这是因为它包含了数据层，而不是把它留给你去处理，如果你的collection的记录数很少，那么你不比花费精力使用ValueList，但是使用ValueList并不会花费你太多的时间。并且它的作者很热心，如果你在使用过程中遇到问题，你可以在论坛中请求帮助，作者很快就会给你回复。