JPivot标签库使用详解
Introduce
JPivot 是一套基于 Mondrian 的 OLAP 前端展现工具，它提供了一套标签库来解决的 OLAP 的展现层问题。
在一个 JSP 页面当中，如果要使用 JPivot 标签库，除了要配置相关的配置文件外，我们需要在 JSP 头的位置声明对 JPivot 标签库的引用，引用方法如下：
| <%@ taglib uri = "http://www.tonbeller.com/jpivot" prefix = "jp" %> |
JPivot 标签库包含以下几个标签：
l chart
l chooseQuery
l clickable
l destroyQuery
l mondrianQuery
l navitator
l print
l scalarQuery
l setParam
l table
l testQuery
l xmlaQuery
接下来我们将详细介绍这些标签的具体用法及相关参数的含义。
chart
创建一个图表组件，这个图表组件的标签不能直接产生可见输出，它必须通过 WCF 的渲染标签才行。 chart 标签的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| id | 是 | String | 是 | 标签的 ID |
| visible | 否 | boolean | 是 | 用来设置该组件是否可见，当该属性为 false 时 WCF 标签半角不显示该组件。 |
| role | 否 | String | 是 | Role 的名称，如： role=”tomcat” 就允许当前用户角色为 tomcat 的访问该控件， role=”!tomcat” 则就允许除角色为 tomcat 以外的所有的用户访问。 |
| query | 是 | OlapModel | 是 | 一个 mondrianQuery 标签的 ID 值 |
| baseDisplayURL | 否 | String | 是 | 显示图表的链接，链接的后面还要添加参数“ ?=filename=[ 临时图表文件的名称 ] ” |
| controllerURL | 否 | String | 是 | 链接到 JPivot Controller 的 URL ，该属性在一些复杂环境下比如 Portal 之类就很有用。 |
chooseQuery
从前面创建的若干个查询当中选择一个合适的查询（通过查询名称进行选择），例如：
<jp:mondrianQuery id="query01" queryName="name1"> SELECT ... </jp:mondrianQuery> <jp:mondrianQuery id="query01" queryName="name2"> SELECT ... </jp:mondrianQuery> ... <jp:chooseQuery id="query01" queryName="name1"/> |
它的属性比较简单，只有 id 和 queryName 两个，而且比较容易理解。
clickable
该标签的作用是给一个 dimension 或一个 level 里的所有的 members 加上超链，使得它们变的可以进行点击操作。生成的 URL 中包含这个 member 的唯一名称，这个标签必须要在一个 table 或一个 query 的标签里嵌套使用。
这个动作还依赖于该标签的 sessionParam 属性，如果该属性存在，那么参数值将在页面显示之前写到 com.tonbeller.jpivot.param.SessionParamPool 当中，如果不存在该属性，参数将会被编码到超链接当中。
例如：
<jp:mondrianQuery ...> select .. from Sales <jp:clickable urlPattern="/otherpage.jsp?param={0}" uniqueName="[Customers]"/> <jp:clickable page="/yetotherpage.jsp" uniqueName="[Products].[Category]" sessionParam="Category"/> </jp:mondrianQuery> |
该标签的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| urlPattern | 否 | String | 是 | 该属性已过时，使用 page 属性替代它。 |
| page | 否 | String | 是 | 目标页面的名称，该属性的值必须要以“ / ”开始，如果不设置，那么会采用当前页面的名称。 |
| uniqueName | 否 | String | 是 | 一个 dimension 或 hierarchy 或 level 的唯一名称，用来标识哪个 member 将可以点击。 |
| menuLabel | 否 | String | 是 | 如果多次定义 clickable ，那么它将通过一个右键来进行显示，这里的值就是右键菜单的名称。 |
| sessionParam | 否 | String | 是 | 参数名称，它将会被回写到 com.tonbeller.jpivot.param.SessionParamPool 当中。 |
| propertyName | 否 | String | 是 | 该属性如果存在，该 member 属性的值将会被带到 com.tonbeller.jpivot.param.Parameter 的 sqlValue 的属性当中。 |
| propertyPrefix | 否 | String | 是 | 如果存在该属性，多个 SessionParam 将会被创建，每一个 member 的名字的开始部分将采用该属性的值。 |
| providerClass | 否 | String | 是 | 如果存在该属性，这个类的实例将会从当前的 member 中获取 SessionParam 对象的实例，这里的类必须实现 com.tonbeller.jpivot.table.navi.ClickableMember.ParameterProvider 接口。 |
destroyQuery
该标签的主要作用是销毁所有的查询，它的用法如下：
<jp:destroyQuery id="query01"/> |
它只有一个 ID 属性。
mondrianQuery
该标签的主要作用是让 mondrian 执行指定的查询，该标签需要指定一个 JDBC 的 datasource 或单独指定 JDBC 连接的各个属性从而可以让 mondrian 连接到指定的数据库。
它的用法如下：
<jp:mondrianQuery id="query01" jdbcDriver="com.mysql.jdbc.Driver" jdbcUrl="jdbc:mysql://localhost/foodmart" catalogUri="/WEB-INF/test/FoodMart.xml"> select {[Measures].[Unit Sales], [Measures].[Store Cost], [Measures].[Store Sales]} on columns, {[Product].[All Products]} ON rows from Sales where ([Time].[1997]) </jp:mondrianQuery> |
它的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| id | 是 | String | 是 | 标签的 ID |
| jdbcDriver | 否 | String | 是 | 要连接到目标数据库的驱动类名 |
| jdbcUrl | 否 | String | 是 | 目标数据库的 URL |
| jdbcUser | 否 | String | 是 | 登录数据库的用户名 |
| jdbcPassword | 否 | String | 是 | 登录数据库的密码 |
| dataSource | 否 | String | 是 | 可以连接到数据库的 JNDI 名称，如 jdbc/SampleDB ，当使用它时另外四个单独连接数据库的属性不可以再用。 |
| catalogUri | 是 | String | 是 | Mondrian Schema 文件所在的路径，指定路径时需要从 web 应用的根开始，如 /WEB-INF/FoodMart.xml 。 |
| role | 否 | String | 是 | 指定角色，该角色的值来自 Mondrian Schema 里定义的角色。 |
| dynResolver | 否 | String | 是 | 指定一个用来解析 Mondrian Schema 里定义的动态变量的解析类。 |
| connectionPooling | 否 | String | 是 | 当该值为 false 时，将从连接池里阻止 Mondrian |
| dynLocale | 否 | String | 是 | 设置动态解析 Mondrian Schema 里的 Local |
| dataSourceChangeListener | 否 | String | 是 | 指定一个类用来检测 datasource 的变化。 |
| queryName | 否 | String | 是 | 这个属性允许保留多个查询，对于每一个查询，最后一个查询将会被存储下来，可以使用 chooseQuery 标签在查询间进行切换。 |
| stackMode | 否 | boolean | 是 | 如果设置为 false ，那么所有的查询将同时被处理；如果设置为 true ，那么将保持其原有的顺序，例如： 查询名称为 qn1 的创建后，标签就马上将其显示出来 ; 接下来创建 qn2 ，现在 stack 里有 qn1 和 qn2 ， qn2 也将被显示出来。 |
navigator
创建一个导航组件，这个组件不会直接输出，它必须通过 WCF 的标签来 render 输出。
示例用法：
<jp:navigator id="navi01" query="#{query01}" visible="false"/> <wcf:render ref="navi01" xslUri="/WEB-INF/jpivot/navi/navigator.xsl" xslCache="true"/> |
该标签的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| id | 是 | String | 是 | 标签的 ID |
| query | 是 | OlapModel | 是 | 指定一个 mondrianQuery 标签的名称 |
| visible | 否 | boolean | 是 | 设置该组件是否可见，如果设置为 false 那么 WCF 的 render 标签将不会 render 该组件。 |
| role | 否 | String | 是 | 角色的名称，可以加前缀“！”，表示“除 … 角色之外”都可以访问该组件，否则就是只有该角色才能访问该组件。 |
创建一个打印控件，该控件不能直接输出，你必须创建 WCF form 来调用打印的 servlet 来生成 XLS/PDF 文件。
该标签只有一个 ID 属性。
scalarQuery
创建一个包含由单个单元格的组成的 OLAP 结果的会话属性，它的值由标签的属性提供。
示例用法：
<jp:scalarQuery id="query01" value="#{some.bean.property}"> formattedValue="#{some.bean.otherProperty}" caption="Some Caption" /> |
它的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| id | 是 | String | 是 | 标签的 ID |
| value | 是 | String | 是 | 是一个 EL 的表达式，通过 EL 表达式来计算值，这里是一个数字。 |
| formattedValue | 否 | String | 是 | 用一个 EL 表达式来计算格式化后的值，是一个字符串 |
| caption | 否 | String | 是 | 用一个 EL 表达式来生成 caption 的值，这里是一个字符串 |
| queryName | 否 | String | 是 | 请参考 mondrianQuery 标签 |
| stackMode | 否 | boolean | 是 | 请参考 mondrianQuery 标签 |
selectProperties
创建一个选择属性的组件，该组件不会直接输出，必须要与 WCF 的 render 标签结合。
示例用法：
<jp:selectproperties id="selectprop01" table="#{table01}" visible="false"/> <wcf:render ref="selectprop01" xslUri="/WEB-INF/jpivot/navi/navigator.xsl" xslCache="true"/> |
它的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| id | 是 | String | 是 | 标签的 ID |
| table | 是 | TableComponent | 是 | 该属性用来指定一个表格组件。 |
| visible | 否 | boolean | 是 | 设置该组件是否可见，如果设置为 false 那么 WCF 组件将不会显示该组件。 |
| role | 否 | String | 是 | 指定角色，同样可以使用“！” |
setParam
通过 get 或 post 或 session 里的值为 MDX 查询设置查询参数。示例用法：
<jp:mondrianQuery id="query01"...> SELECT ... Parameter("Param01", ... WHERE ... </jp:mondrianQuery/> <jp:setParam query="query01" httpParam="param" mdxParam="Param01"/> or <jp:setParam query="query01" sessionParam="CUSTOMER" mdxParam="Param01"/> |
它的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| query | 是 | OlapModel | 是 | 指定一个 mondrianQuery 标签的名称 |
| httpParam | 否 | String | 是 | http 参数的名称，如果存在该属性，那么它的值将会被告解析并设置到 mdx 查询的 parameter 当中 |
| sessionParam | 否 | String | 是 | Session 的参数名称 |
| mdxParam | 是 | String | 是 | MDX 的 parameter 的名称 |
table
创建一个 pivot 的表格组件，该组件要借助于 WCF 的 render 标签输出。
示例用法：
<jp:table id="table01" query="#{query01}" visible="true"/> |
该标签的主要属性如下：
| 属性名 | 必须 | 数据类型 | 是否能动态计算指定 | 描述 |
| id | 是 | String | 是 | 标签的 ID |
| visible | 否 | boolean | 是 | 设置组件是否可见，如果为 false 那么 WCF 的标签将不会将其 render 。 |
| role | 否 | String | 是 | 可访问该组件的角度，支持“！”用法 |
| query | 是 | OlapModel | 是 | 指定一个 mondrianQuery 标签的名称 |