错误

　　我们将在此介绍 LotusScript 如何处理错误以及如何利用它使 Web 服务错误能够给客户机提供一些有用的信息。LotusScript 提供了三个函数来考察当前错误的状态并显示错误信息。这些函数分别是：

Error()，返回相关的错误消息。
Err()，返回相关的错误号。
Erl()，返回发生错误的行号。
在 LotusScript 中通过使用一个特殊的出口参数来抛出 Web 服务错误，该参数是 WS_Fault 类（可从 lsxsd.lss 库中获得）的实例，如 developerWorks 文章 “在 IBM Lotus Domino 7 中使用 Web 服务，第 3 部分: 编写复杂的 Web 服务” 所示。 见清单 14。

　　清单 14. 错误示例
Function foo(fault As WS_FAULT) As …
  
 Fault.SetFault True
 Fault.setFaultString "error message"

End Function
   
　　Lotus Domino V8 处理的自定义错误是 WS_Fault 类的扩展。它使 Axis 1.4 能够将错误生成为 AxisFault 的子类，当发生错误时将捕获到这些子类。清单 15 中的代码使用 OnError 语句来捕获运行时错误并使用自定义的 throwFault 函数来实例化 DiscussionError。DiscussionError 是一个（默认）自定义类，其中包含了错误消息、生成消息的函数名和包含 Web 服务的数据库名。函数名通过 GetThreadIfo(LSI_THREAD_PROC) 函数来收集。出于适用性考虑，错误在生成时被使用 nLog.logError 函数记录到日志数据库。

　　清单 15. createTopic 示例
 Function createTopic(topic As TopicDTO, fault As DiscussionError) As TopicDTO
 On Error Goto FAULT
 …
 Exit Function
FAULT:
 Set fault = throwFault(fault, GetThreadInfo(LSI_THREAD_PROC), database.FileName)
 nLog.LogError Err, "Error in " & GetThreadInfo(LSI_THREAD_PROC) & " : " & Error & "
   Line : " & Erl
 Exit Function
End Function
   
　　Lotus Domino V7.0.2 没有返回 SOAP 错误子类型成员数据。结果，不管在 Lotus Domino V7.0.2 中使用的自定义类是什么，所有的错误在运行时都被客户机视为 AxisFault 异常而不是自定义错误。例如，Axis 1.4 生成了一个自定义异常类，但是 Web 服务在运行时决不会抛出该异常。我们尚未找到此问题的解决方法。

　　安全性

　　Web 服务提供的用户访问权限与 Lotus Notes 客户机施加的权限一致。在 Lotus Domino 中，每个文档都有一个 Authors 字段和一个 Readers 字段；请参阅 Lotus Domino Designer 文档。Authors 字段决定了谁能够编辑或更新文档。Readers 字段控制谁能够阅读文档。为达到 Lotus Notes 客户机和 Web 服务之间的一致性，当创建一个主题或响应的时候，用户被添加到 Authors 字段。如果用户选择将主题或响应设为私有，则用户被添加到 Readers 字段。主题和响应有一个 Boolean 字段可将它们标记为私有或公有。

　　部署 DiscussionProfileManager

　　在本节中，我们将描述如何配置 Lotus Domino 来公开安全 Web 服务并部署这些服务。 在本例中，我们将展示如何部署为 Discussion 数据库开发的 DiscussionProfileManager Web 服务。 您可以按照同样的步骤部署针对此解决方案开发的另外两个 Web 服务：DiscussionThreadManager 和 DiscussionViewManager。

　　配置安全性

　　为使用户能够以一种安全的方式访问 Web 服务，Lotus Domino 应使用带有 HTTPS 协议的嵌入式 Web 服务器。

　　要配置服务器，应执行以下操作：

　　启动 IBM Lotus Domino Administrator 客户机。
　　选择 Configuration 附签。
　　打开 Server 文档。
　　选择 Ports 附签。
　　选择 Internet Ports 附签。
　　单击 Edit Server 按钮。
　　作出更改启用 HTTPS 并禁用 HTTP。
　　要验证用户，必须启用 Internet 口令。 此口令可在 Domino Directory 中进行设置，方法是使用 Notes 客户机编辑个人文档。

　　手工部署 DiscussionProfileManager

　　要部署此 Web 服务，请按照以下步骤执行：

　　在 Lotus Domino Designer 中打开目标数据库。
　　选择 Shared Code，然后在 Navigator 中选择 Web Services。
　　单击 New Web Service。
　　在 Web Service 属性框中输入 Web 服务名，比如 DisscussionProfileManager。
　　输入 DiscussionProfileManager 作为 Port Type Class，如图 3 所示。

　　图 3. Web Service 属性框
 
　　选择 Web Service 属性框的 Security 附签，如图 4 所示。
选择 “Run as web user” 选项。这使得用户可以使用自己的用户名和 Internet 口令来调用 Web 服务。

　　图 4. Web Service 属性框的 Security 附签
 
　　选择 Web Service 属性框的 Advanced 附签。
为 Port 类型名、Service 元素名和 Service 端口名输入适当的名称（如果这些字段留空则 Lotus Domino 将自动填充这些字段）。图 5 给出了一个 DiscussionProfileManager 的例子。
选择所需的编码方法。

　　图 5. Web Service 属性框的 Advanced 附签
 
　　关闭 Web Service 属性框。
　　从选项区删除文本 Option Base。
　　在文本编辑器（如 Microsoft Notepad）中打开 DiscussionProfileManager.lss。
　　复制 DiscussionProfileManager.lss 中的所有文本。
　　在 Lotus Domino Designer 中选择新 Web 服务的 Declarations 段，如图 6 所示。

　　图 6. Web 服务的 Declarations 段
 
　　在 Web 服务中粘贴。
　　保存并关闭 Web 服务。
　　现在可用以下地址获得 Web 服务：

　　http://<DominoServer>/<Database Path>/DiscussionProfileManager

　　注意：根据默认，Web 服务引擎被配置为单线程引擎。要更改此默认配置，需要使用 Lotus Domino Administrator 客户机连接到服务器，选择左侧窗格上的 Server 图标，打开列表，选择 Current Server Document，转到 Internet Protocols 附签，单击 Domino Web Engine 附签，然后将 Web Agents 设置 “Run Web agents concurrently?” 条目从 Disabled 改为 Enabled，如图 7 所示。然后执行 HTTP 任务重新启动或重新启动服务器。

　　关于咨询 IBM Redpaper 的更多详细信息，请参阅 “IBM Lotus Domino for iSeries, performance, and tuning”。

　　图 7. Web Agents 并发设置
 
　　WS-I 依从性

　　WS-I 依从性的目标是保证 Discussion 数据库 Web 服务之间的互操作性，允许客户机通过其他支持 Web 服务的技术来使用这些服务。例如，J2ME 客户机要求所有的 Web Service Description Language (WSDL) 定义都满足 WS-I 依从性。

　　Web Services Interoperability Organisation 开发了一个测试工具，用来评估 Web 服务对 Basic Profile 1.1 的依从性。此工具使用一个非侵入式的黑盒方法来测试 Web 服务实现。该工具的测试重点在于 Web 服务和用户应用程序之间的交互。 要执行这些测试，我们可以使用 Interoperability Testing Tool 1.1。

　　该测试工具包含一个 Monitor、一个 Analyzer（见图 8）和各种支持文件。Monitor 用作消息捕获和日志记录的工具。它将截取消息而记录器对这些消息重新定义格式并将它们存储到一个消息日志中以便以后进行分析。Monitor 使用中间方法中的 man 截取和记录消息来实现。Analyzer 是一个分析工具，用来验证 Web 服务对 WS-I Profiles 的依从性。它将分析发送到 Web 服务的消息和从 Web 服务发出的消息，前提是 Monitor 已经将这些消息记录到消息日志中。

　　有关更多的详细信息，请参阅 WS-I Organization 中的参考资料，使 Web 服务开发人员能够创建互操作的 Web 服务并验证其结果是否符合 WS-I 指南。

　　图 8. 互操作性测试工具
 
　　工具中附带了关于 Interoperability Test Tool 的使用方法的说明。

　　针对 Discussion 数据库 Web 服务执行的测试

　　Lotus Domino 允许使用以下编码发布 Web 服务：

　　Document Wrapped
　　Document Literal
　　RPC Literal
　　RPC Encoded
　　RPC-encoded Web 服务不受 WS-I Basic Profile 1.1 支持，因此，本文不再对它进行讨论。在 Web 服务开发期间，对于其他三种编码 Document Wrapped、Document Literal 和 RPC Literal，我们针对 Lotus Domino V7.0.2 和 Lotus Domino V8 都执行了静态和动态 WS-I 依从性测试。

　　静态测试指使用 Analyzer 对每个 Web 服务 WSDL 执行静态分析。 动态测试指使用 Monitor 记录 Web 服务和客户机之间的 SOAP 消息；在本例中，客户机一个基于 Axis 1.4 的 JUnit Test Suite。Monitor 将 SOAP 消息记录到一个日志文件中，Analyzer 工具稍后将分析这个日志文件。生成的依从性报告文件指明 Web 服务是否满足 WS-I 依从性。

　　Lotus Domino V7.0.2 和 V8 WS-I 失败

　　Lotus Domino V7.0.2 生成的 WSDL 在以下情形下会使 WS-I Interoperability Tests 失败：

　　使用 Document Literal 和 Document Wrapped 编码时
　　在 Web 服务中使用数组时
　　RPC Literal 编码的 Web 服务包含 SOAP 错误时
　　Document Literal 编码的 Web 服务中的方法使用多个参数时

　　Lotus Domino V8 生成的 WSDL 在以下情形会使 WS-I Interoperability Tests 失败：

　　RPC Literal 编码的 Web 服务包含 SOAP 错误时
　　Document Literal 编码的 Web 服务中的方法使用多个参数时
　　Document Literal 编码的 Web 服务的参数不惟一时

　　这里通过一些错误的 WSDL 示例对这些 WS-I 失败作出了详细解释，并说明了使其满足 WSDL 依从性所需进行的更改。如 Lotus Domino Designer 文档 中所述，有些 WSDL 或 XML 模式结构对到 LotusScript 或 Java 的映射只提供了有限的支持或者不支持。当它们尝试导入 WSDL 时得不到 Lotus Domino Designer 的支持。