Lotus Domino 和 IBM WebSphere 集成解决方案: Domino JSP 标签库

在这个由两部分组成的系列文章的 第 1 部分 中，我们将介绍如何使用 Domino XML（也称为 DXL）集成 Lotus Domino 和 IBM WebSphere。DXL 可以让您访问 Domino 对象，而不用了解太多有关 Lotus Domino 的知识。然而，具有一些 Java 方面的经验对于使用 DXL 方法来说也是必要的。对于那些 Java 经验很少的 Notes 应用程序开发者来说，可以使用 Lotus Domino Toolkit for WebSphere Studio 中提供的 Domino JSP 标签库。（这个工具包在 Lotus Notes/Domino 6.0.2 及更新的版本中可用，用户可以从 Passport Advantage 下载这个工具包。）

从 Lotus Domino 6 开始，Lotus 提供了两个 JSP 标签库。这两个标签库让程序员可以开发与 J2EE 兼容的应用服务器上的 Lotus Domino 进行交互的 J2EE 应用程序。在可以使用标签库之前，那些想要将自己的应用程序与 Lotus Domino 连接的 JSP 开发者必须把 CORBA 和 IIOP 调用构建在应用程序中。这导致很大的复杂性，并且经常需要使用一些特定于数据库的代码，这些代码几乎是不可重用的。随着协作能力需求的增长，需要一种更智能的、功能更强大的解决方案。

Lotus 了解到了这种需求，因此创建了两个标签库，它们对通用的 Lotus Domino 和 J2EE 功能进行了抽象和封装。这些库是在标签库描述符 domtag.tld 和 domutils.tld 中定义的。Domutils.tld 定义了处理所有 J2EE 应用程序通用的任务的工具标签。这些标签不是 Lotus Domino 特有的，可以独立于 Domino 服务器应用于任何应用程序。在 domtag.tld 中定义的标签是 Lotus Domino 特有的。它们提供了对所有的 Domino 元素的编程访问能力，包括设计、访问控制列表和文档。在本文中，我们将着重介绍 Domino 特有的标签（在 domtag.tld 中定义的标签）。从现在开始，我们就将其简称为 taglib。

开始之前

taglib 比第一篇文章中所介绍的 XML 方法需要更深入的 Lotus Domino 方面的知识。它使用了 Domino 框架中的一些专用术语和控件。为了有效地使用 taglib，重要的是您要深入理解 Lotus Domino、各种设计元素以及您要访问的数据的结构。对第 1 部分的路线图部分进行回顾可以帮助您确定这种方法是否更适合于您和您的应用程序。

需求

taglib 遵守 JSP 1.1 和 Servlet 2.2 规范，支持大部分 J2EE 兼容的应用服务器。本文中的例子要安装到 IBM WebSphere Application Server 5.1 上，并使用 WebSphere Studio Application Developer 进行开发。本文假设您熟悉 Domino 对象和术语，并且了解使用 WebSphere Studio Application Developer 进行 J2EE 编程的基本知识。

注意：如果不准备让 Lotus Domino 来处理 IIOP，在使用 taglib 时就不需要任何 CORBA 或 IIOP 编程的知识。

软件需求如下：

• WebSphere Application Server 5.x 或其他 J2EE 兼容的应用服务器
• Lotus Domino 6.x，并且安装并启用了 DIIOP 服务

准备 Lotus Domino

taglib 使用 CORBA（Command Object Request Broker Architecture）和 IIOP（Internet Inter-ORB Protocol）技术与 Lotus Domino 进行通信。您必须设置 Domino 服务器监听 IIOP 请求。首先，确保已经安装了 DIIOP。在 Domino 终端中执行 show task 或 load diiop 命令，可以帮助判断现在是否已经安装了 DIIOP。如果还没有安装，请从 Domino 安装光盘上安装 DIIOP。

接下来，编辑 Domino 服务器的 Notes.ini 文件，设置为在启动 Lotus Domino 时自动加载 DIIOP。找到以 ServerTasks 开始的那一行。在本行的最后，添加 diiop。重新启动 Domino 服务器，并检查是否有 DIIOP 服务器的启动消息。

图 1. 在服务器启动过程中启动 DIIOP 进程

在 DIIOP 进程启动时，它在 Domino HTTP 根目录（Windows 中 Domino 默认的安装目录为 C:\lotus\domino\data\domino\html）中创建一个名为 diiop_ior.txt 的 IOR（Internet Object Reference）对象。如果您使用 Lotus Domino 作为 HTTP 服务器，就必须告诉 DIIOP 将这些文件放到您的 HTTP 服务器的根 HTML 目录中。

1. 打开 Domino Server 文档。
2. 选择 Internet Protocols 标签 - DIIOP 子标签。
3. 在 External HTML directory 字段中，输入非 Domino HTTP 服务器的根 HTML 目录的完整路径名。
4. 保存这个 Server 文档，并重新启动 DIIOP。

图 2. Server 文档的 DIIOP 部分

使用一个 Web 浏览器测试并查看该文件是否可以访问：http://127.0.0.1/diiop_ior.txt

图 3. Web 浏览器中的 diiop_ior.txt 文件

回页首

配置 J2EE 应用程序环境

要使用 taglib，需要两个 JAR 文件：NCSO.jar 或 Notes.jar（请参阅侧栏）和 domtag.jar。

1. 在 Windows Explorer 中，打开 [Notes installation path]\Data\domino\java。找到并将 domtags.jar 和 NCSO.jar 拷贝到 Web 应用程序的 WEB-INF/lib 目录中。

   注意：如果您有多个 Web 应用程序使用 taglib，请将这些文件拷贝到应用服务器的共享库目录中。

   
   图 4. WebSphere Studio Application Developer 的 J2EE 视图
   
   
2. 在 [Notes installation path]\Data\domino\java 目录中，找到并将 domtags.tld 拷贝到项目的 WEB-INF 目录中。这个文件就是标签库描述符（即 TLD 扩展）。它说明这些标签是相关于底层的 Java 代码的，因此应用服务器可以理解这些标签。
3. 接下来，找到并打开 Web 应用程序的 web.xml 文件。添加下面的 taglib 引用，并保存所做的修改。

   <taglib id="domtags"> <taglib-uri>domtags.tld</taglib-uri> <taglib-location>/WEB-INF/domtags.tld</taglib-location> </taglib>

   
   

下面是一个 web.xml 文件的例子：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="WebApp">
	<display-name>ArticleWeb</display-name>
	<welcome-file-list>
		<welcome-file>index.html</welcome-file>
		<welcome-file>index.htm</welcome-file>
		<welcome-file>index.jsp</welcome-file>
		<welcome-file>default.html</welcome-file>
		<welcome-file>default.htm</welcome-file>
		<welcome-file>default.jsp</welcome-file>
	</welcome-file-list>
	<taglib id="domtags">
		<taglib-uri>domtags.tld</taglib-uri>
		<taglib-location>/WEB-INF/domtags.tld</taglib-location>
	</taglib>
</web-app>

Domino 提供了两个 JAR 文件，用于编程访问 Domino 对象。这两个文件是 Notes.jar 和 NCSO.jar。Notes.jar 用来访问 本地的 Domino 服务器（此时 Lotus Domino 和 Java 程序运行在相同的服务器上）。NCSO.jar 包含了用来访问远程服务器的其他 CORBA/IIOP 代码。 在决定使用哪个 JAR 文件时，请考虑以下因素： 运行的 Java 程序和 Lotus Domino 的相对关系如何？如果它们运行在相同的机器上，那么使用 Notes.jar 可以获得更好的性能。 您关心可扩展性吗？即使现在您是在相同的机器上运行 Java 程序（单独的 Java 程序和非 J2EE 的程序）和 Lotus Domino，将来您可能会发现需要将其扩展到专用的服务器上。在这种情况中，请使用 NCSO.jar ，这样可以获得更好的适应能力。 Java 程序要在一个应用服务器上运行吗？在 WebSphere 的情况中，即使它与 Lotus Domino 在相同的机器上，也需要使用 NCSO.jar。

设置默认的参数

taglib 有很多上下文参数（Context Parameter），您可以在 web.xml 文件中进行设置。我们高度推荐您尽可能利用这些应用程序范围的参数，这样可以提高程序的可移植能力，并且简化将来的维护工作。

在我们的例子中，我们设置了主机名（127.0.0.1）和数据库（articleSample.nsf）作为上下文参数，它们分别是 lotus.domino.default.host 和 lotus.domino.default.dbname。

要这样设置，请打开 web.xml，然后添加以下行并保存。

	<context-param id="dominohost">
		<param-name>lotus.domino.default.host</param-name>
		<param-value>127.0.0.1</param-value>
	</context-param>
	<context-param id="dominodbname">
		<param-name>lotus.domino.default.dbname</param-name>
		<param-value>articlesample.nsf</param-value>
	</context-param>

回页首

使用 domtags

在接下来的部分中，我们将使用在上一篇文章中使用的 Car 数据库。我们将构建 4 个 JSP，它们分别实现以下功能：

• 显示一个文档。
• 显示一个 Domino 视图的内容。
• 启用 Domino 视图搜索。
• 允许用户创建并编辑文档。

在开始之前，您必须在所有使用 taglib 的 JSP 中都包括这个 taglib 的声明。它告诉应用服务器每个以单词 domino 开始的标签都是对domtags 标签库描述符中一个项的引用。例如， <domino:db>。（尽管您可以使用不同的前缀，但是我们高度建议使用 domino 作为前缀。）

<%@ taglib uri="domtags.tld" prefix="domino" %>

显示文档

我们首先创建一个简单的 JSP 来显示一个 Notes 文档的内容。它利用一个单独的查询字符串 uid，其值为所请求文档的惟一 ID。在 JSP 编辑器中，创建一个新的 JSP disptagcar.jsp。首先输入前面提到的 taglib 声明。包括一个包含 lotus.domino.* 的 import 行是一个好主意，因为这样可以允许您直接访问 Domino 对象。后面我们会使用很多这种声明。

<%@ taglib uri="domtags.tld" prefix="domino" %>
<%@page import="lotus.domino.*"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<%@ page 
language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"
%>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Vehicle information using Domino Tag Library</title>
</head>
<body>
<h1>Vehicle information using Domino Tag Library for <%= (String) request.getParameter("unid")%></h1>
<domino:document>
<table border="1" width="100%" cellspacing="0" cellpadding="0">
	<tr bgcolor="#ccff00">
		<th>Make</th>
		<th>Model</th>
		<th>Body Type</th>
		<th>Engine</th>
		<th>Year</th>
		<th>Specifications</th>
	</tr>
	<tr>
		<td>
			<domino:item name="make"/>
		</td>
		<td>
			<domino:item name="model"/>
		</td>
		<td>
			<domino:item name="bodytype"/>
		</td>
		<td>
			<domino:item name="enginetype"/>
		</td>
		<td>
			<domino:item name="year"/>
		</td>
		<td>
			<domino:item name="specifications" format="<LI>"/>
		</td>
	</tr>
</table>
</domino:document>
</body>
</html>

<domino:document> 标签可以显示 Notes 文档的内容。使用这个标签，您的代码可以访问一个特定文档的所有项目和属性。在某些情况中，您可能希望为文档标签中的 dbserver、dbname 和 unid 属性传递值。注意在我们的例子中不会这样做。原因是由于必需的信息早已在其他地方指定了。服务器的主机名和数据库的文件名早已在 Web 部署描述符（web.xml）中定义了。UNID 是在查询字符串参数 unid 中隐式指定的。

如果由于某些原因，您不想在 URL 中暴露这个 UNID，那么就必须在 unid 属性中明确地说明文档标签。

<%
String unid = [[code that obtains the document unid]];
%>
<domino:document unid=’<%= unid %>’>

<domino:item> 标签显示了在 name 属性中指定的项目的内容。例如，<domino:item name="make"/> 显示了保存在 make 项中的值。引用 specifications 字段的最后一个标签具有一个 format 属性。这个属性告诉标签库如何显示 JSP 中的值。为这个属性提供的值称为关键字（keyword）。在一个 format 属性中，可以使用多个关键字。

回想一下，specifications 字段是一个多值字段；它可以包含多个值。<li> 关键字告诉 <domino:item> 标签对 <li> 和 </li> 标签中的内容自动进行换行。

显示视图的内容

Domino 视图可以通过 <domino:view> 标签进行访问。例如，在我们的 car 的例子中，有一个简单的视图 Cars\By VIN，它有两列：vin 和 make。这个视图还有一个别名 vins，这就是我们在视图标签中要引用的内容。

图 5. Notes 客户机显示 VINs 视图

下面是用来将 VINs 视图显示为 HTML 文件的 JSP 代码。

<%@ taglib uri="domtags.tld" prefix="domino" %>
<%@page import="lotus.domino.*"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<%@ page 
language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"
%>
<%
String count = "30";
if(request.getParameter("count")!=null);
	count = (String)request.getParameter("count");
%>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Car List using Domino Tag Library</title>
</head>
<body>
<h1>Car List using Domino Tag Library</h1>
<domino:db>
	<table border="1">
		<tr bgcolor="#ffcccc">
			<th>
				VIN
			</th>
			<th>
				Make
			</th>
			<th>
				Model
			</th>
		</tr>
		<domino:view viewname="vins" max="<%= count %>">
			<domino:viewloop>
				<tr>
					<td>
						<domino:formlink href="disptagcar.jsp" >
							<domino:viewitem name="vin" />
						</domino:formlink>
					</td>		
					<td>
							<domino:viewitem name="make" />
					</td>
					<td>
						<domino:item name="model" /> 	
					</td>	
				</tr>
			</domino:viewloop>
		</domino:view>
	</table>
</domino:db>
</body>
</html>

查看视图的 JSP

下面让我们考查一下上面这个 JSP。在下一节我们将使用这个 JSP 来构建一个搜索页面。

• 数据库
  <domino:db> 标签为应用程序提供了数据库的内容。因为我们已经在 web.xml 中定义了一个默认的数据库，因此不需要在这儿再定义了。如果没有在 web.xml 中定义缺省的数据库，或者希望访问除了在 web.xml 中定义的数据库之外的其他数据库，就需要在这里通过定义属性 dbname 提供一些信息，如果数据库位于另外一个服务器上，还要定义 dbserver 属性。
• View
  将 <domino:view> 标签放在 <domino:db> 标签中，这样可以提供对这个数据库中的指定视图的访问权限。您必须提供视图名作为 viewname 属性中的一个属性。您可以使用该视图的别名。max 属性控制了每个页面中显示的项的个数。
• Viewloop
  这个标签提供了交互访问视图中的每一项的能力。它循环遍历视图，并提供对其内容的访问能力。在这个例子中，我们只是使用稍后介绍的 viewitem 标签简单地打印视图的内容。
• Formlink
  <domino:formlink> 标签动态地构建 <a href> 到指定 JSP 的链接。结果页面应该包括一些格式的标签库代码，它们可以显示文档的内容。在我们的例子中，将使用在最后一节中构建的 JSP（disptagcar.jsp）。
• Viewitem
  <domino:viewitem> 标签提供了对视图项的直接访问能力。name 属性会引用实体中的一个列名。name 的值是大小写敏感的，必须与列标题完全匹配。

  <domino:viewitem name="vin" />
<domino:viewitem name="make" />

• Item
  <domino:item> 标签提供了对文档中的一个字段的访问能力。name 属性是指要检索的字段。

<domino:item> 和 <domino:viewitem> 之间的区别如下：<domino:item> 必须打开文档才能检索值，而 <domino:viewitem> 则使用视图中显示的值。只要可能，在 viewloop 的上下文中就应该避免使用 item 标签，因为这样可能会造成严重的性能问题。

回页首

视图搜索

在本节中，我们将讨论如何修改所创建的视图 JSP，从而让它可以支持搜索功能。

要正确使用全文搜索功能，必须激活 Domino 数据库的全文索引。要查看一个数据库是否进行了索引，请打开 Database Properties 对话框，并点击 Search 选项卡。如果数据库没有进行索引，那么就点击 Create Index 按钮。Notes 客户机的状态条会告诉您这个请求是否已经排入了队列。全文索引通常很快就可以建好。

图 7. 数据库全文索引属性选项卡

我们的搜索表单会包含这三个字段用于一个可定制的搜索：查询，返回结果的最大个数，结果页面中每页显示的个数。我们使用上一节中的视图 JSP 作为这个 JSP 的基础。

下面是这个 JSP 代码中处理搜索功能的部分：

<domino:view viewname="vins" ftsearch='<%= query %>' max='<%= max %>'>
	<domino:page rows='<%= count %>'>
		<tr><td colspan="3" align="right">Go to page: 
		<domino:pagebar navstyle="NextPrev" />&nbsp;&nbsp;&nbsp;
		<domino:pagenext>Next></domino:pagenext></td></tr>
		<domino:viewloop>
			<tr>
				<td>
					<domino:formlink href="disptagcar.jsp" >
						<domino:viewitem name="vin" />
					</domino:formlink>
				</td>		
				<td>
					<domino:viewitem name="make" />
				</td>
				<td>
					<domino:item name="model" /> 	
				</td>
			</tr>
		</domino:viewloop>
		<domino:novalues>
			<tr>
				<td>
				The search for <%= query %> found no matches. Use another keyword and try again.
				</td>
			</tr>
		</domino:novalues>
		<tr><td colspan="3" align="right">Go to page: 
		<domino:pagebar navstyle="NextPrev" />&nbsp;&nbsp;&nbsp;
		<domino:pagenext>Next></domino:pagenext></td></tr>
	</domino:page>
</domino:view>

查看 Search 视图的 JSP

下面让我们更详细地查看一下 Search 视图的 JSP。

• View
  要构建一个搜索视图，我们只能添加两个属性到 <domino:view> 标签中：ftsearch 和 max。ftsearch 是查询的字符串，max 是要返回的结果的最大个数。
• Page
  这个标签为显示视图内容和搜索结果提供了分页控制。它的行属性限制了一个页面中的项数。这个标签为提供导航特性的标签提供了内容。
• Pagebar
  在 page 标签的上下文中，<domino:pagebar> 可以自动生成到搜索结构的页面的链接。这些到当前页面的链接是粗体的，而且是不能点击的。
• Pagenext
  这个标签自动生成了到下一个页面的链接。这个标签的主体就是该链接的文本标签。在这种情况中，我们使用 Next >。您可以将这个标签与 pagebar 一起使用，从而创建一个类似于图 8 所示的页面导航系统。
  图 8. 导航条
  
  
• Novalues
  这个标签的主题是在搜索不返回任何结果时所显示的文本。在我们的例子中，会显示消息“The search for [query] found no matches. Use another keyword and try again.”

回页首

表单

在这最后一节中，我们会创建一个 JSP 表单，用户可以使用这个表单来创建并修改 Notes 文档。出于简单性的考虑，我们的示例数据库允许匿名作者访问。在真实生活中的应用程序中，安全性实在是要关注的一个问题，更明智的方法是使用一个集中的用户注册（例如 LDAP），并采用单点登录（SSO）功能。将 WebSphere 设置为一个可信的容器，为 Lotus Domino 处理授权和认证的功能。有关 WebSphere 和 Lotus Domino 的 SSO 的更多信息，请参阅 WebSphere Application Server InfoCenter。

我们的表单提供了以下特性：

• 允许用户创建文档。显示一条消息说明用户正在创建一个新文档。
• 允许用户编辑现有的文档。显示一条消息说明用户正在修改一个现有的文档。
• 对输入信息进行有效性验证。如果有效性验证失败，就显示定制的错误消息。
• 当用户成功提交表单时，将用户重定向到一个感谢页面上。

这个 Form JSP 的详细代码，请参阅“Form JSP 代码”。

form 标签

<domino:form> 标签提供了对指定文档的编辑访问能力。它可以支持很多用来支持高级操作主机的属性。在我们的例子中，使用了更通用的一些属性。下面让我们仔细查看一下：

• Name
  这是表单对象的名字。其值会被用作 HTML 表单名。该值在每个 JSP 中都是惟一的。
• Schema
  这个值对应于 Domino 表单的名字，这个文档应该使用这个名字进行保存。对这个表单会执行 Domino 表单的保存前处理（QuerySave）操作。设置这个值还会隐式地将其放入该文档的 form 字段中。
• Editmode
  这个属性接受 3 个值：display、edit 和 delete。虽然您可以为这个属性设置固定的值，但是可能最有用的方式是，根据代码中的逻辑、以编程的方式给这个属性赋值。
• Validhref
  这个值是您希望在对表单进行有效性验证并保存之后将用户重定向到的页面。
• Clientvalidate
  将这个值设置为 true 会导致对表单根据 validation 标签对用户输入进行有效性验证。反之，将该值设置为 false 会导致该表单忽略所有的 validation 标签。
• User
  指定正在访问 Domino 数据的用户名。当使用 J2EE 容器进行认证时，请将该值设置为 *webuser。有关 taglib 安全性的详细信息，请参阅 Domino Designer Help。
• Unid
  如果在 JSP 查询字符串中有一个 unid 参数，那么 form 标签就会使用这个 unid 来打开一个文档。您也可以在 unid 属性中传递这个 unid。
• Input 标签
  input 标签创建 HTML 的输入字段。name 属性指明该项要保存的值。默认情况下，数据类型是 text。在需要其他数据类型的情况中，请指定数据类型属性来匹配表单模式中的字段。对于多值字段来说，要设置 multivalue="true"，并使用 mveditseparator 和 mvdisplayseparator 指定值的分隔符。在我们的例子中，使用了逗号来分隔要编辑的值，使用分号来分隔要显示的值。
• Validation 标签
  这些标签负责在保存表单之前对输入信息进行有效性验证。Lotus 提供了很多 validation 标签来对不同的数据类型进行有效性验证。在我们的例子中，使用更通用的一些标签：validaterequired 和 validatepattern。您可以对每个字段使用多个 validation 标签。

现在，让我们来查看一下使用的 validation 标签：

• Validatesummary
  这个标签显示了检测有效性验证失败的 validation 标签的 message 属性的值。将这个标签放到表单的顶部，这样用户就可以对自己是否填写了表单而一览无余了。
• Validaterequired
  这个标签确定 name 属性中的字段是否为空。如果非空，那就会在页面上显示这个标签的主体。将这个标签放到下一个字段中，从而精确地说明用户应该重点注意哪些内容。
• Validatepattern
  在基本的 validation 标签不够用的地方，可以使用这个标签来创建用户定制的有效性验证规则。这个标签的核心依赖于 Apache 的 regexp 库对用户输入的值进行有效性验证。构建一个说明所期望值格式的正则表达式，并将其放到 pattern 属性中。然后这个标签就会将用户输入的数据与正则表达式进行比较。在我们的例子中，validatepattern 标签会检查 year 字段是一个数字类型，有 4 个字符长。

document 标签

<domino:document> 标签提供了对 Notes 文档本身的访问能力。id 属性的存在标记着 taglib 分配一个名称为 id 标签中的值的 lotus.domino.Document 对象。在我们的例子中，这个对象是 doc。这为程序员提供了完全编程访问该对象的属性和方法的能力；在普通的 Java 代码中可以对 taglib 进一步地扩展使用。这个功能强大的工具在 taglib 中的大部分标签中都可以使用。要学习更多有关 Domino Java 类的知识，请参阅 Domino Designer Help。

回页首

结束语

在本文中，我们讨论了如何使用 Domino JSP 标签库进行编程，从而构建功能强大的启用 Domino 的 J2EE 应用程序。通过几个例子，我们讨论了最常用的标签，并详细介绍了它们背后的概念。本系列文章中介绍的内容应该可以帮助您在现有的 Domino 环境中采用 J2EE 技术。