lotus designer 8.5中创建JAVA代理（转自genusBIT的空间）

在开发LotusDomino数据库的过程之中，开发人员可以创建Java代理（Agent）程序，方便将 Lotus Notes Java API 和任何第三方的 Java 类库整合到 Domino 数据库中，使得 Notes 数据库具有强大的可扩展性。在 Domino Designer 8.5.1 中，集成了 Eclipse 开发环境，用于 Java 代理的开发。本文将通过一个具体的应用案例，向 Lotus Domino 开发人员介绍如何使用 Domino Designer 8.5.1 开发依赖于第三方 Java 类库的 Java 代理程序，并阐述了如何部署基于事件触发和被调度的代理程序。

应用环境分析

我们需要对一个现有的 Notes 数据库进行改造，这个 Notes 数据库中存在一系列的视图，某些视图中包含的文档包含统一格式的 Excel 附件。我们需要批量地从这些 Notes 文档中提取出 Excel 附件，并将 Excel 文件中的数据保存到DB2数据库中。

客户存在两种不同的需求，一种是手动选择需要处理的 Notes 文档，另一种则是在每个月固定的时间点执行批处理程序，将符合特定条件的 Notes 文档批量进行处理。对于这两种需求，我们都可以通过建立 Java 代理程序来实现。

使用 Domino Designer 8.5.1 创建 Java 代理

在 Domino Designer 8.5.1 中打开 Notes 数据库文件 TestNSF.nsf, 展开 Code 节点，在 Agents 节点上点击右键，在菜单中选择”New Agent”，在弹出的对话框中选择”Java”，命名为”DataExtractionAgent”。如图 1 所示：


图 1. 创建 Java Agent



系统会自动在默认包中创建 JavaAgent.java 文件，该类扩展了 lotus.domino.AgentBase 类，并重载了 NotesMain() 方法。


清单 1. Java 代理程序代码示例
public void NotesMain () {
    try {
        Session session = getSession();
        AgentContext agentContext = session.getAgentContext();
        // (Your code goes here)
    } catch(Exception e) {
        e.printStackTrace();
    }
}



使用 session 对象可以获取当前的代理程序所处的 Notes 数据库或者其他数据库对象，并调用 Notes Java API 实施数据库文档的增删改查，以及元数据的读取等操作。

agentContext对象是 Java 代理的运行环境对象，可用来获取被用户选择的 Notes 数据库文档列表等对象。当 Java 代理被触发时，AgentBase 类的 NotesMain() 方法将被调用。

接下来，我们可以在 Java 代理中继续建立其它的 Java 包和类；如果我们需要在 Java 代理程序中调用第三方的 Java API，我们可以将依赖的 Java 类库拷贝到 Notes 或 Domino 内置的 Jvm 的 lib/ext 目录下。

在 Domino Designer 中，切换到 Java 视图，发现 DataExtractionAgent 作为一个独立的 Java 项目存在，Domino Java Library 下可以看到新增加的 Java 类库，agent.jar 包含了从 Excel 文件中读取数据保存在 DB2 数据库中业务逻辑，而 db2 开头的两个 jar 包提供了操作 DB2 数据库的 API。


图 2. Java 代理程序在 Java 包视图中的显示



在 Java 视图中可以方便的完成 Java 代理程序的开发，之后可以回到 Domino Designer 视图，执行 Java 代理的测试。

选择 Code 节点下的 Agents 项，在右边的窗体中得到所有 Agent 程序的列表，右键点击 DataExtractionAgent，选择”Run”命令，则触发了该 Agent 程序的运行。


图 3. 测试 Java 代理程序



运行的结果是得到一个日志对话框提示 Agent 执行的情况。


图 4. Java 代理程序运行情况



代理被触发的方式主要分为两种，一种通过菜单调用，另一种则通过调度来实现。通过菜单调用的 Java 代理可以部署在 Notes 客户端或者 Domino 服务器；而调度的 Java 代理只能运行在 Domino 服务器上。

调试 Java 代理程序

可以使用 Domino Designer 对新建的 Java 代理程序进行调试。

首先在 Domino Designer 视图中选择 Java Agent，然后在下方的 Properties 选项卡中选择 Security 页面，选择“Compile Java code with debugging information”。


图 5. 设置 Agent 程序的调试信息



然后打开 Tools 菜单，选择 Java 调试首选项，勾选”Client Agents/Applets”，设置端口号。


图 6. 设置 Java 代理调试参数



创建一个”Remote Java Application”调试配置，如图 7 所示。选择 Host 为 localhost，Port 为 8701.


图 7. 设置远程 Java 应用调试配置



在 JavaAgent 的 NotesMain() 方法中添加断点，然后通过工具栏启动调试。


图 8. 启动 Java 代理的调试



切换到 debug 视图，发现远程 debug 的连接已经被建立。进入 Notes 客户端，触发 Java 代理的运行，进入断点，于是可以进行调试了。

Java 代理的触发机制有两种，一种是事件触发，一种是定时触发。

在 Notes 视图中调用 Java agent

在 Java 代理的基本属性页，选择运行时触发方式为”On event”，在下方的下拉列表中选择”Agent list selection”。


图 9. 设置 Java 代理程序的触发



在 Notes 视图的 Action 列表中新建一个 Action，命名为”提取数据”，编辑该 Action 的属性，使之在工具菜单中显示，双击该 Action，设置 click 事件的业务逻辑，选择在客户端运行，调用的程序为 Notes Formula:


图 10. 编写对 Java 代理程序调用的公式



在 Domino 服务器中部署定时调用的 Java 代理程序

使用 Domino Designer 完成 Java 代理的开发并部署到服务器上的 Notes 数据库中，设置调用机制为定时调用。进行保存时，弹出下面的对话框，指明当前的开发人员不具备足够的权限来部署服务器上的 Java 代理程序。

我们设置 Java 代理为定时执行的同时，还需要在 DominoServer端进行配置，打开 Domino Administrator，选择最右方的 Configuration 选项卡，选择右下方工作区中的 Security 页。将管理员的 Notes ID 加入到域”Sign or run restricted LotusScript/Java agents”中。如果 Java 代理程序需要在服务器端的文件系统写文件，则需要在 Full Access administrators 域中也加上管理员的 Notes ID. 完成修改后进行保存。


图 11. 配置 Java 代理程序在 Domino 服务器上运行的权限


总结

本文介绍了如何在 Lotus Domino Designer 8.5.1 中开发 Java 代理程序，并在 Java 代理中调用第三方的类库，另外还介绍了调试 Java 代理的方法以及部署 Java 代理到 Domino 服务器的要点，具有一定的参考价值。