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	必需有一个 2个中的一个	定义在你的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。

<map>

<property name="useName"><value>false</value></property>

<property name="defaultSortColumn"><value>startdate</value></property>

<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="*">

<tr>

<c:out value="${list.valueListInfo.totalNumberOfEntries}"/>
Total

- Page (<c:out
value="${list.valueListInfo.pagingPage}"/> of
<c:out
value="${list.valueListInfo.totalNumberOfPages}"/>)

</td>

<vlh:paging />

</td>

</tr>

<tr>

<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-uri>valuelist.tld</taglib-uri>

<taglib-location>/WEB-INF/tlds/valuelist.tld</taglib-location>

</taglib>

总结

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

package cn.js.fan.util;

import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;

import org.apache.log4j.Logger;

import com.berheley.oa.persistence.model.calendar.TIndividualAffair;
import com.kgw.xym.test;

import net.mlw.vlh.ValueListInfo;
import net.mlw.vlh.adapter.jdbc.AbstractJdbcAdapter;
import net.mlw.vlh.adapter.util.ObjectWrapper;

//DefaultWrapperAdapter的源代码自己改了一下不然一直抱Wrapper=null，所以改了，注意要写自己的adapter实现AbstractJdbcAdapter接口就行了
public class DefaultWrapperAdapter extends AbstractJdbcAdapter {
   public Logger logger = Logger.getLogger(DefaultWrapperAdapter.class);

        private String _columnName = null;

        private int _columnNumber = 1;

       private ObjectWrapper _wrapper;

private boolean wrapResultSet = false;

private Object   getOrignalRecord(ResultSet result) throws SQLException
           {
              if (wrapResultSet)
              {
                 return result;
              }
              else
              {
                 if (_columnName != null && _columnName.length() > 0)
                {
                    return result.getObject(_columnName);
                 }
                 else
                 {
                    return result.getObject(_columnNumber);
                 }
              }
           }

           public List   processResultSet(String   name, ResultSet   result, int numberPerPage, ValueListInfo info) throws SQLException
           {
              if (LOGGER.isDebugEnabled())
              {
                 LOGGER.debug("Start wrapping using column '"
                       + (_columnName != null && _columnName.length() > 0 ? _columnName : (_columnNumber + "")) + "'.");
              }

              List<TIndividualAffair>   list = new ArrayList();
                 for (int i = 0;result.next()&&i < numberPerPage; i++)
                 {
                   TIndividualAffair t= new TIndividualAffair();
                   // t.setBeforeNum(Integer.parseInt(result.getString("before_num")));

                   t.setId(result.getString("id"));
                   t.setTitle(result.getString("remind_bgin_time"));
                   t.setWheeltype(result.getString("wheeltype"));
                   t.setTitle(result.getString("title"));
                     list.add(t);
                 }

              LOGGER.debug("End wrapping.");
              return list;
           }

           /**
            * @return Returns the columnName.
            */
           public String   getColumnName()
           {
              return _columnName;
           }

           /**
            * Specify which column will be objectToBeWrapped. Default value is null. If
            * is <b>null </b>, is used column <b>Number </b> instead.
            * <h4>Example</h4>
            * <ul>
            * result.getObject(columnName);
            * </ul>
            *
            * @param columnName The columnName to set.
            */
           public void setColumnName(String   columnName)
           {
              _columnName = columnName;
           }

           /**
            * @return Returns the columnNumber.
            */
           public int getColumnNumber()
           {
              return _columnNumber;
           }

           /**
            * Specify which column will be objectToBeWrapped. Default is 1;
            * <h4>Example</h4>
            * <ul>
            * result.getObject(columnNumber);
            * </ul>
            *
            * @param columnNumber The columnNumber to set.
            */
           public void setColumnNumber(int columnNumber)
           {
              _columnNumber = columnNumber;
           }

           /**
            * @return Returns the objectWrapper.
            */
           public ObjectWrapper getWrapper()
           {
              return _wrapper;
           }

           /**
            * This param is required.
            *
            * @param objectWrapper The objectWrapper to set.
            * @see net.mlw.vlh.adapter.util.ObjectWrapper
            */
           public void setWrapper(ObjectWrapper objectWrapper)
           {
              this._wrapper = objectWrapper;
           }

           /**
            * @return Returns the wrapResultSet.
            */
           public boolean isWrapResultSet()
           {
              return wrapResultSet;
           }

           /**
            * Determine object to be wrapped - resultSet or column from result set. *
            * If true, wrapper will call getWrappedRecord with resultSet parameter as
            * objectToBeWrapped. If false, wrapper will call getWrappedRecord with
            * object from resultSet. Use false if you need to pass only ids. If you
            * need to access more than one object, use true. Default is false;
            *
            * @param wrapResultSet
            * @see ObjectWrapper#getWrappedRecord(Object)
            */
           public void setWrapResultSet(boolean wrapResultSet)
           {
              this.wrapResultSet = wrapResultSet;
           }
        }