级别: 中级
Josephine E. Justin, 资深软件工程师, IBM
2006 年 5 月 23 日
如果您是 Workplace Forms 应用程序开发方面的新手，那么您可以在本文中了解 IBM Workplace Forms Server API 的概述；本文将向您简要介绍这个 API 中非常通用的一些类，并给出了一个示例应用程序供下载。
IBM Workplace Forms 2.5 为管理电子表单（e-form）的生命周期提供了端到端的平台，从设计到验证再到电子表单的存储和检索。服务器端的平台提供了一个 API 对表单的详细信息进行必要的处理。这个 API 提供了对表单进行存储和检索的能力，从而对与这个表单有关的数字签名进行验证，从中提取出数据元素和文件附件，并对电子表单中数据的 XML 实例进行操作。本文解释了我们如何使用 IBM Workplace Forms Server API 来实现这些功能。本文是为那些熟悉 Workplace Forms 并且具有 XML 经验的应用程序开发人员编写的。
IBM Workplace Forms Server API 概述
Workplace Forms Server API 允许我们开发与可扩展表单描述语言（XFDL）表单进行交互的应用程序。这个 API 还让我们可以对电子表单以结构化的数据类型进行访问和操作。Workplace Forms Server API 中的所有类都属于 com.PureEdge 包。
Workplace Forms Server API 可以大致分为两个库：Form 库和 Function Call Interface（FCI）库。Form 库让我们可以创建实现以下功能的应用程序：
读写表单
从表单元素中检索信息
将信息插入表单元素
操作并验证数字签名
提取并存储附件
FCI 库提供了另外一些方法：
为 XFDL 表单创建函数包
将包设置为 Workplace Forms Viewer 或 Designer 的扩展
确定如何使用这些函数，以及何时使用这些函数
本文将着重介绍 Form 库。有关创建定制库和表单扩展的内容在本文中并没有进行介绍，这是 FCI 库的一部分。
数据库交互以及与外部系统和服务的交互是独立于 Workplace Forms Server API 进行的。我们可以在一个 Java servlet 或 portlet 中使用 Workplace Forms Server API。然后使用这些 servlet 或 portlet 与数据库或外部系统进行交互。
电子表单结构概述
理解电子表单是如何组织的可以帮助我们正确使用这个 API 并正确对表单元素进行引用。本节将对节点结构、节点层次以及引用电子表单项的方法进行介绍。
节点结构
当一个电子表单被加载到内存中之后，它就会以一系列链接节点的形式进行表示 —— 每个节点都代表一个电子表单元素。这些节点一起创建一棵树来描述这个电子表单。这棵树中的每个节点都有 4 个属性：
Type。表示节点的类型，例如页、按钮、域，等等。
Literal。表示节点的值。
Identifier。表示该节点的惟一标识符。
Compute。表示赋值给该节点的计算语句。
注意： 根据节点的类型不同，这些属性中有些可能为空。
节点层次
这棵树中在将电子表单加载到目录中时进行格式化的每个节点都是整个层次结构的一部分。以下是这个层次中的结构按照降序排列的内容：
表单。每个电子表单都有一个表单级的节点，即树的根节点。
页。每个电子表单都有一些以表单节点的子孙形式表示的页。每个电子表单至少有两个页节点 —— 一个是全局页，用来存储全局设置；另外一个是电子表单的首页。
条目。每个页中都包含一些电子表单条目。每个页至少包含一个全局条目来为该页设置全局属性。
选项。每个条目都包含一些选项。
参数。每个选项都可以包含一些设置或参数。
引用
引用提供了到节点层次中每个条目的路径，这让我们可以定义特定的页、条目、选项或参数。其语法遵循下面这个一般模式：
page.item.option[argument]
其中页、条目、选项和参数都是这个节点层次中的一部分。例如，在本文提供的可下载的示例应用程序中，要引用页 PAGE1 中 field1 条目的值，我们使用的语法应该为：
PAGE1.field1.value
间接引用
间接引用让我们可以生成一个在运行时计算出来的动态引用。有时这是非常必要的，因为在节点层次结构中要引用的条目节点可能会依赖于用户的操作。例如，我们可以使用间接引用来从一个弹出或列表条目中提取出所选择单元的值。
引用中的名称空间
名称空间用来识别 XML 文档中的信息。类似地，XFDL 名称空间包含了用来对电子表单进行描述的信息。当我们使用 Workplace Forms Designer 创建一个 Workplace 电子表单时，XFDL 表单就会自动加入以下两个名称空间：
XFDL。前缀是 xfdl，这个名称空间用来识别所有与电子表单有关的 XML。
Custom。前缀是 custom，这个名称空间为电子表单开发人员定义成一个用来存储定制信息（例如元数据和计算）的方便位置。
Workplace Forms 允许使用任何其他名称空间作为电子表单的一部分。
IBM Workplace Forms Server API 的核心类
以下是 Workplace Forms Server API Form 库的核心类的列表。
DTK 类
DTK 类用来对 Form 库进行初始化。这是我们使用这个 API 中的第一个类。
XFDL 类
XFDL 类包括了将电子表单从指定的文件或流加载到内存中所使用的方法。这个类还可以创建电子表单的根节点。这个类还可以用来创建新节点。
IFSSingleton 类
IFSSingleton 类为应用程序的 XFDL 对象提供了一个静态接口。
FormNodeP 类
正如在 “电子表单结构概述” 一节中介绍的一样，当一个电子表单被加载到内存中之后，它就以链接节点的形式进行表示。不管节点处于哪个层次级别，每个节点都是使用一个 FormNodeP 对象来表示。Form 库中可以使用的函数提供了执行以下任务所使用的方法：
复制节点
填充节点
对节点进行导航
从节点中检索信息
销毁电子表单，从而将其从内存中删除（这可以通过对 电子表单的根节点调用 destroy 方法来实现）。
其他类
在使用 Workplace Forms Server API Form 库时，您会发现还有其他一些类也非常有用。
Certificate 类
Certificate 类让我们可以处理证书。这允许我们从在对 电子表单进行签名时使用的证书中提取出二进制大对象和证书的详细信息。
Hash 类
Hash 类让我们可以对消息进行散列操作。这个类在对 Authenticated Clickwrap 签名进行验证时使用，这些签名包含了一个共享秘密的散列值，这个散列值用来识别签名者。
LocalizationManager 类
LocalizationManager 类让我们可以设置报告错误所使用的地区。Workplace Forms Server API 在 2.5 版本中只能支持 en_US 和 fr_CA locale。默认情况下，Workplace Forms Server API 使用的是英语。
SecurityManager 类
SecurityManager 类可以用来检索 hash 对象。这个 hash 对象将用来对 Authenticated Clickwrap 签名使用的共享秘密进行散列操作。
Signature 类
Signature 类让我们可以处理电子表单中的签名对象。Workplace Forms 支持各种不同种类的签名，例如 RSA、Clickwrap 和 Authenticated Clickwrap。根据签名类型的不同，我们可以使用 Signature 类从封装在电子表单中的签名中提取出不同的数据，还可以从签名中提取出签名证书。
现在我们已经对 Workplace Forms Server API 有了一个基本的理解，接下来我们继续介绍 Workplace Forms Server API 在 IBM WebSphere Application Server 上的安装。本文假设您已经安装了 IBM Workplace Forms Server 2.5。
在 WebSphere Application Server 上安装并设置 Workplace Forms Server API
要将 Workplace Forms Server API 设置为与 WebSphere Application Server 一起工作，请执行以下步骤。
在 Workplace Forms Server 上，找到 <Workplace Forms Server Directory>\x.x\API\redist\msc32，其中 x.x 是 IBM Workplace Forms 的版本号。
在这个目录中，找到以下 DLL 文件：
MSLUR71.dll
pe_cc.dll
pe_com.dll
pe_java.dll
unicows.dll
uwi_java.dll
将这些 DLL 文件复制到 WebSphere Application Server 的 bin 目录中。
创建一个新文本文件 PureEdgeAPI.ini，其中包含以下内容，然后将这个文件放到 <WebSphere install dir>\AppServer\java\bin 目录中：
[API] *=<<Workplace Forms Server Directory>>\redist\msc32\PureEdge\xx
将 xx 修改成您在服务器上所安装的 IBM Workplace Forms 的版本号。
为 WebSphere Application Server 授予访问 API JAR 文件的权限
为 WebSphere Application Server 授予访问这个 API 的 JAR 文件的权限。
创建一个目录 <WebSphere installation directory>\AppServer\shared。
找到目录 <Workplace Forms Server Directory>\redist\msc32\PureEdge\xx\java\classes。
将以下文件从上面这个目录复制到步骤 1 中创建的目录：
pe_api.jar
pe_api_native.jar
uwi_api.jar
uwi_api_native.jar
现在为 Workplace Forms Server API JAR 文件创建一个库。
选择 Environment - Shared Libraries。
点击 New，创建一个新的共享库。
在 Name file 域中，输入 PureEdgeLib。
在 Classpath 域中，提供在前面步骤中所复制的 JAR 文件的路径。
点击 Apply，然后将配置保存到 master。
将 IBM 库添加到 WebSphere Application Server ClassLoaders 中
现在，我们要把这个 Workplace Forms Server API 库添加到 WebSphere Application Server 类加载器中，这样这些 API 就可以在服务器启动时可以使用了。
在 WebSphere Application Server Administrative Console 中，选择 Servers - Application Servers。
在 Application Server 下面，选择您安装 Workplace Forms Server API 的服务器。
在 Configuration 下面，选择 Classloader。
在 Classloader 下面，点击 New。
在 Configuration 下面，点击 Apply，然后点击 Libraries。
在 Library Ref 下面，点击 Add。
在 Library name 下拉框列表中，选择 PureEdgeLib。
点击 Apply。
点击 Save。
现在我们已经安装好了 Workplace Forms Server API，并对 WebSphere Application Server 进行了配置，接下来我们要下载并安装本文所提供的 Workplace Forms 示例应用程序。在安装这个示例应用程序之前，我们可能需要重新启动服务器。
使用示例应用程序
这个示例应用程序 WFAPISample 展示了如何使用 Workplace Forms Server API。在下载示例应用程序之后，我们需要使用 Administrative Console 将其安装到 WebSphere Application Server 上。我们将 WFAPISample 作为这个应用程序的上下文的根节点。在将应用程序部署到 WebSphere Application Server 上之后，就可以启动这个应用程序了。要查看它的工作情况，请在 Web 浏览器中访问 URL http://<IP address>:9080/WFAPISample。
这个示例应用程序用来展示这个 Workplace Forms Server API 的以下特性：
初始化 Form 库
向应用程序用户显示一个新的/已提交的电子表单
检索电子表单域的值
提取电子表单的附件
对电子表单中的数字签名进行验证
提取出数字签名中包含的信息
根据应用程序用户所提供的值提取出电子表单中所包含的 XML 实例
将所提交的电子表单保存到服务器上的本地文件中
这个示例应用程序可以存储用户所提交的所有电子表单。这些提交的电子表单都可以进行查看，也可以使用新的数据再次提交。这个应用程序中包含了一个示例电子表单。这个电子表单具有两个输入域：Input Field 1 和 Input Field 2。我们还可以使用它给应用程序添加附件，附件可以进行处理并保存到服务器上。这个电子表单还要使用数字签名进行保护，而数字签名也可以由服务器进行身份验证和有效性验证。
下面这个屏幕（图 1）给出了这个用来展示 Workplace Forms Server API 的示例程序所使用的电子表单。
图 1. 示例电子表单
这个应用程序提供了文件系统文件夹中可以使用的新电子表单清单，并且列出了所提交的电子表单。用户可以查看新的电子表单或所提交的电子表单。一旦查看之后，用户可以在这个电子表单中填充所需要的项，并将其提交给服务器进行处理。
要检索一个电子表单域的值，我们可以使用节点层次结构来标识一个项。PAGE1 中电子表单域 field1 的值可以使用 getLiteralByRefEx() 方法进行检索。
这个示例应用程序具有一个可以对 PureEdgeServlet 进行扩展的 servlet，这样 Workplace Forms Webform Server 就可以从 XFDL 翻译成 HTML 和 JavaScript 格式。如果这个特性不是 Web 应用程序所期望的，那么我们可以从 HttpServlet 开始对这个 servlet 进行扩展。
在 init() 方法中，会创建用于存储所提交的电子表单、附件和其他资源的必要文件夹。这个 servlet 通过调用 DTK 类的 initialize() 方法来对 Form 库进行初始化。
DTK.initialize("FormsHandler", "1.0.0", "6.5.0");
这个示例电子表单是从文件输入流中读入到内存中的。
//Retrieve the Input stream for the form from the file
fis = new FileInputStream(file);
// Obtain the XFDL object to read a form
XFDL theXFDL = IFSSingleton.getXFDL();
// From the XFDL object, read the form using the file inputstream.
// Compute Engine is turned off when reading the form for better performance
theForm = theXFDL.readForm(fis, XFDL.UFL_SERVER_SPEED_FLAGS);
这个示例电子表单可以使用 writeForm() 写入到响应输出流或文件系统中。
// Writes form to the response output stream theForm.writeForm(request.getOutputStream(), null, 0);
要检索一个电子表单域的值，我们可以使用节点层次结构来标识一个项。PAGE1 中电子表单域 field1 的值可以使用 getLiteralByRefEx() 方法进行检索。
String field1 = theForm.getLiteralByRefEx(null, "PAGE1.field1.value", 0, null, null);
要提取文件附件，我们可以使用 dereferenceEX() 方法，然后调用 extractFile() 方法来从这个电子表单中提取文件附件。
tempNode = theForm.dereferenceEx(null, "PAGE1.TestSingle", 0, FormNodeP.UFL_ITEM_REFERENCE , null);
tempNode.extractFile(resourceStorageDir + File.separator + attachmentFileName);
这个示例应用程序使用了 Clickwrap 签名，它有两个问题：签名者的名字和年龄。要对数字签名进行验证，在这个示例应用程序中使用了 verifyAllSignatures() 来检查这个数字签名的正确性。我们可以从 FormNodeP 对象中提取出单个签名。为了提取出签名中所包含的详细信息，我们这个示例应用程序使用了 Signature 类。
// This verifies the signatures present in the form
theForm.verifyAllSignatures(false);
tempNode = theForm.dereferenceEx(null, "PAGE1.SIGNATURE1", 0,
FormNodeP.UFL_ITEM_REFERENCE, null);
//Signature object is used to retrieve the signature details.
Signature theSignatureObject = tempNode.getSignature();
// Holder object to hold the return parameter
BooleanHolder encodedData = new BooleanHolder();
//Retrieve the Signature details
String signerCommonNameQuestion = theSignatureObject.getDataByPath
("Question1Text", false, encodedData);
String signerCommonName = theSignatureObject.getDataByPath
("Answer1Text", false, encodedData);
String signerAgeQuestion = theSignatureObject.getDataByPath
("Question2Text", false, encodedData);
String signerAge = theSignatureObject.getDataByPath
("Answer2Text", false, encodedData);
XML 数据模型是为了简化与其他 XML 处理器的集成。XML 数据模型让我们可以将信息从 XFDL 表单复制到一个可以进行格式化的 XML 文件，这样 XML 处理器就可以对 XML 实例进行处理，而不是对整个 XFDL 表单进行处理。每个 XML 实例都具有 3 个基本部分：
实例数据。 每个 XML 实例都是一组数据元素的集合。
绑定。 每个数据元素都可以映射成一个或多个 XFDL 表单元素。这会在数据元素和表单元素之间创建一个绑定。
提交规则。 每个实例都可以定义一些提交规则。这些规则确定要过滤的数据或其他相关属性。
这些 XML 实例可以直接提交给后端的 XML 处理器。这个示例应用程序会提交整个 XFDL 表单；XML 实例可以使用这个 API 进行提取。
这个示例表单还包括一个绑定了两个表单域（field1 和 field2）值的 XML 模型。XML 表单实例还可以包括所使用的名称空间。数据实例默认保存在 custom 名称空间中。这个示例实例使用了默认的名称空间。这个实例也是使用一个对该实例进行惟一标识的标识符来提供的。
<xmlmodel xmlns:xforms="http://www.w3.org/2003/xforms">
<instances>
<xforms:instance xmlns="http://test.ibm.com" id="UserAuthenticationResponse">
<getUserAuthenticationResponse>
<field1></field1>
<field2></field2>
</getUserAuthenticationResponse>
</xforms:instance>
</instances>
<submissions></submissions>
<bindings>
<bind>
<ref xmlns:default="http://test.ibm.com">
[default:getUserAuthenticationResponse][default:field1]
</ref>
<boundoption>PAGE1.field1.value</boundoption>
</bind>
<bind>
<ref xmlns:default="http://test.ibm.com">
[default:getUserAuthenticationResponse][default:field2]
</ref>
<boundoption>PAGE1.field2.value</boundoption>
</bind>
</bindings>
</xmlmodel>
当用户使用所提供的域值来提交表单时，这个示例应用程序会从 XML 数据模型中提取出一个实例，创建一个 XML 文件，从而完成处理。我们向 extractInstance() 方法提供了 XML 实例的标识符和在电子表单中所提供的名称空间：
theForm.extractInstance("UserAuthenticationResponse", null, "default",xmlFileName, 0, null, null, null);
回页首
结束语
本文向您简要介绍了 IBM Workplace Forms 2.5 API，并提供了一个展示这个 API 用法的示例应用程序。我们可以对这个应用程序进行扩充，从而在 XML 模型中包含一个基于 BPEL（Business Process Execution Language）的实例；我们还可以使用它来调用业务逻辑和规则。我们还可以对这个示例应用程序进行扩充，使其包括一个数字证书。
Sample Workplace Forms API WAR file WFAPISample.war 373KB
http://download.boulder.ibm.com/ibmdl/pub/software/dw/workplace/WFAPISample.war
