Java 对 Domino Objects 的访问，第 1 部分

级别: 初级

Robert Perron, 文档架构师, Lotus
Steve Nikopoulos, 高级软件工程师, Lotus
Kevin Smith, 顾问软件工程师, Lotus

2004 年 12 月 06 日

本文将向 Java 编程人员介绍 Domino Objects，并讲述本地访问和远程访问的一些基本知识，然后将介绍访问控制。本文的重点是开发 Java 应用程序。

<!--START RESERVED FOR FUTURE USE INCLUDE FILES--><!-- include java script once we verify teams wants to use this and it will work on dbcs and cyrillic characters --><!--END RESERVED FOR FUTURE USE INCLUDE FILES-->

如果没有本文中讲述的一些基本知识，从 Java 转向 Domino Objects 可能会比较困难。不仅代码必须准确，而且客户机和服务器环境也必须准确。本文首先将介绍本地访问和远程访问的一些基本知识，然后说明访问控制。本文的重点是 Java 应用程序。在接下来的续篇中，我们将讨论 SSL 加密、servlet、连接池、单点登录、防火墙、超时和回收，而且还包括故障检修部分。本文假设您熟悉 Domino Java API。

概述

Java 对 Domino Objects 的访问是通过高级包 lotus.domino 进行的。根据运行时环境，这个包中的接口是在其他两个包中的一个包中实现的：

• lotus.domino.local 提供了从同一计算机上的 Notes/Domino 软件进行调用。
• lotus.domino.cso 提供了从通过远程连接访问的 Domino 服务器进行调用。

对于本地访问，Java 程序运行在安装有 Notes 客户机或者 Domino 服务器的计算机上。本地类由 JNI（Java Native Interface）构建来，用于访问与 JVM（Java Virtual Machine）相同的进程中的 Notes/Domino 二进制文件。

对于远程访问，Java 程序使用 CORBA（Common Object Request Broker Architecture）请求 Domino 服务器所提供的服务。远程类使用 CORBA 通过 TCP/IP 网络访问服务器。远程访问由以下两个部分组成：

• 客户机通过 HTTP 协议获得服务器的初始对象，作为 IOR （Interoperable Object Reference）。
• 客户机通过 IIOP 连接进一步获得其他对象。

图 1. Java 通过 HTTP 和 IIOP 的远程访问

在 lotus.domino 中，NotesFactory 类提供了 createSession 和其他方法，以便在 Java 应用程序和 servlet 中启用对 Domino Objects 的访问。特殊的调用方式确定了访问是本地还是远程的。

要编译使用 lotus.domino 包的 Java 程序，类路径必须包含 Notes.jar（本地）或者 NCSO.jar（远程）。例如：

set classpath=%classpath%;c:/lotus/domino/Notes.jar

或者

set classpath=%classpath%;c:/lotus/domino/data/domino/java/NCSO.jar

其中 Notes.jar 可以在任何 Notes/Domino 安装的程序目录中找到。NCSO.jar 可以在 Domino Designer 或 Domino 服务器数据目录下的 domino/java 目录中找到。

回页首

本地调用

createSession 的调用没有参数，第一个参数为 null 或者第一个参数为空字符串都表示本地调用。下列代码是等价的：

Session s = NotesFactory.createSession()
Session s = NotesFactory.createSession((String)null)
Session s = NotesFactory.createSession("")

将 null 转换成 String，以避免过载冲突。

要从应用程序和 servlet 中实现本地调用，路径中必须包含 Notes/Domino 的程序目录，类路径中必须包含 Notes/Domino 程序目录中的 Notes.jar。例如：

set path := %path%;c:/lotus/domino
set classpath := %classpath%;c:/lotus/domino/Notes.jar

Notes.jar 中包含 lotus.domino 和 lotus.domino.loca 包。

本地调用需要用 NotesThread 类管理线程。NotesThread 类扩展了 java.lang.Thread，包含专门针对 Domino 的初始化和终止代码。您有以下三种选择：

• 通过继承来执行线程。
• 通过 Runnable 接口来执行线程。
• 通过静态方法来执行线程。

通过继承来执行线程

要通过继承来执行线程，需要扩展 NotesThread，而不是 Thread，并且需要包含 runNotes 方法，而不是 run 方法。NotesThread 线程可以和任何其他线程一样通过 start 方法来启动。这种方式比静态方法（稍后讨论）容易使用，且不易出错。

import lotus.domino.*;
public class myClass extends NotesThread
{
    public static void main(String argv[])    
    {    
        myClass t = new myClass();        
        t.start();        
            }            
            public void runNotes() // entry point for Notes thread            
            {            
            try            
                {                
                    Session s = NotesFactory.createSession();                
                    // Operational code goes here                
                }                
                catch (Exception e)
            {            
                e.printStackTrace();
        }
    }
}

通过 Runnable 接口来执行线程

要通过 Runnable 接口来执行线程，需要实现 Runnable 并包含 run 方法，这与使用线程的任何类相同。当您因为正在扩展其他类而不能扩展 NotesThread 时，可以使用这种方式。

import lotus.domino.*;
public class myClass implements Runnable
{
    public static void main(String argv[])    
    {    
        myClass t = new myClass();        
        NotesThread nt = new NotesThread((Runnable)t);        
        nt.start();        
        }        
            public void run() // entry point for thread
        {        
            try            
            {            
                Session s = NotesFactory.createSession();                
                // Operational code goes here
                }            
                catch (Exception e)            
                {            
                e.printStackTrace();
            }
        }    
    }

通过静态方法来执行线程

要通过静态方法来执行线程，需要调用 sinitThread() 来初始化线程，调用 stermThread() 来终止线程。stermThread() 的调用必须与 sinitThread() 的调用严格一一对应；推荐将 stermThread 放在“finally”程序块里。静态方法适用于不可能进行继承的线程，或者适用于需要更好地控制基于事件的线程。

import lotus.domino.*;
public class myClass
{
    public static void main(String argv[])    
    {    
       try    
           {        
               NotesThread.sinitThread(); // start thread            
               Session s = NotesFactory.createSession();            
               // Operational code goes here
           }        
               catch(Exception e)
           {        
               e.printStackTrace();
           }        
               finally
           {        
               NotesThread.stermThread(); // must terminate every thread
           }
        }    
    }

进行本地调用的每个应用程序的线程都必须初始化一个 NotesThread 对象。它包含了访问 Domino Objects 的 AWT 线程。监听器线程必须使用静态方法，因为无法从 NotesThread 中继承它们。

既进行本地调用又进行远程调用的应用程序可以动态地决定何时使用静态方法 sinitThread 和 stermThread。运行本地线程时，也可以进行远程调用；但不要将通过一个会话获得的对象用于对其他会话的调用。

应该避免使用多线程，除非有非常充分的理由，比如处理文件输入/输出和 Web 请求时，要继续进行操作。观察遵循以下指导原则：

• 在同一会话中，可以跨线程共享、同步和回收 Domino Objects。如果每个线程使用不同的会话，那么就会失去这些功能；必须明确地在每个线程的基础上管理同步和回收。
• 不要跨线程使用 DbDirectory。
• 允许在多线程中访问现有文档，但只在一个线程中进行访问文档将简化内存管理。将访问限制在一个线程，这样就可以不检查其他线程直接进行回收。跨线程创建文档始终是安全的，并且这些对象可以不管其他线程就进行回收。
• 配置文件文档是基于每个线程进行缓存的。如果出现更新竞争，那么将保留最后一个线程的更新。
• 注意不要删除其他线程中通过视图或集合进行导航所需的文档。
• 当子对象被用于其父对象之外的其他线程时，父线程要等所有子线程都结束后才能结束。当在 AWT 事件处理程序中使用 Domino Objects 时，这一点尤其重要。

回页首

远程调用

在进行远程调用时，createSession 签名的第一个参数是非空字符串。第一个参数通常用来标识 Domino 服务器所在的计算机。例如：

Session s = NotesFactory.createSession("myhost.east.acme.com")

或者

Session s = NotesFactory.createSession("myhost.east.acme.com:63148")

第二个示例指定了端口号，这样就无需在 myhost.east.acme.com 上运行 Domino Web 服务器。有关的详细信息，请参阅本文后面的“获取 IOR”部分。

要从应用程序或者 servlet 执行远程调用，客户机计算机的类路径中必须包含 NCSO.jar。NCSO.jar 包含 lotus.domino 包、lotus.domino.cso 包、lotus.domino.corba 包以及 ORB 类，ORB 类包含用于远程类的实现代码。对于已安装的 Domino Designer 和 Domino 服务器软件，NCSO.jar 位于 Domino 数据目录下的 domino/java 子目录中。对于没有安装 Domino 软件的计算机，必须从安装该软件的计算机上复制归档文件。

类路径必须包含归档文件，例如：

set classpath := %classpath%;c:/lotus/domino/data/domino/java/NCSO.jar

编码

编码比较简单。远程调用不使用 NotesThread。只需使用主机名称和（可选）端口号进行 createSession 调用即可。

不使用线程时，模板将如下所示：

import lotus.domino.*;
public class myClass
{
    public static void main(String argv[])    
    {    
        try    
            {        
                String host = "myhost.east.acme.com:63148";            
                Session s = NotesFactory.createSession(host);            
                // Operational code goes here
            }        
                catch(Exception e)
            {        
                e.printStackTrace();
            }
        }    
    }

下列模板将使用线程：

import lotus.domino.*;
public class myClass implements Runnable
{
    public static void main(String argv[])    
    {    
        myClass t = new myClass();    
        Thread nt = new Thread((Runnable)t);    
        nt.start();    
        }    
        public void run()    
        {    
        try    
            {        
                String host = "myhost.east.acme.com:63148";            
                Session s = NotesFactory.createSession(host);            
                // Operational code goes here
            }        
                catch(Exception e)
            {        
                e.printStackTrace();
            }
        }    
    }

管理

远程访问还需要设置 Domino 服务器和进行 TCP/IP 连接。安装服务器的计算机必须能够通过 TCP/IP 进行访问。在计算机的网络设置中，需要检查 TCP/IP 属性中的主机和域名的 DNS 配置。必须能够用 Internet 名称从客户机计算机 ping 到服务器计算机。例如，如果 Domino 服务器的主机名称是 myhost，那么域名将是 east.acme.co：

图 2. TCP/IP Properties 框

下列命令应该得到客户机计算机的有效响应：

> ping myhost.east.acme.com

在服务器 Domino Directory（names.nsf）的 Server 文档 Bsiscs 选项卡的“Fully qualified Internet host name”字段中，必须显示主机和域。通常，安装服务器安装时已设置了主机名，例如：

图 3. Server 文档 —— Basic 选项卡

如前面的编码示例所示，Internet 名称是 createSession 主机的（第一个）参数。也可以使用服务器的 IP 地址。例如，如果 myhost.east.acme.com 的 IP 地址是 9.95.73.30，那么下列任何一个调用都有效：

Session s = NotesFactory.createSession("myhost.east.acme.com:63148")

或者

Session s = NotesFactory.createSession("9.95.73.30:63148")

必须运行服务器上的 DIIOP（Domino IIOP）任务。HTTP 任务可能也需要运行，这取决于如何获取 IOR。检查 Domino Directory 中 Server 文档。转至 Ports 选项卡，然后转向 Internet Ports 选项卡。查看 Web 选项卡（用于 HTTP）并找到 DIIOP 选项卡。这些部分有用于指定端口号以及启用/禁用端口的字段。通常，HTTP 的端口号是 80，DIIOP 的端口号是 63148。下列屏幕显示了 DIIOP 选项卡：

图 4. Server 文档 —— DIIOP 选项卡

如果访问数据库时不知道文件名称（例如，要使用 DbDirectory.getFirstDatabase），那么必须允许通过网络浏览文件名。转至 Internet Protocols 选项卡、HHTP 选项卡和 R5 Basics 选项卡。然后将“Allow HTTP clients to browse databases”设为 Yes。

图 5. Server 文档 —— HTTP 选项卡

要在服务器上启动 HTTP 和 DIIOP 任务，需要确保这些任务在 Notes.ini 文件 ServerTasks 变量的任务列表中，如果正确配置了 Server 文档该文件，那么这些任务应该包含在任务列表中。Notes.ini 文件应该包含类似于下面的行：

ServerTasks=Update,Replica,Router,AMgr, AdminP,CalConn,Sched,DIIOP,HTTP,LDAP

从运行的服务器，可以在控制台中输入下列命令来加载任务：

> load http > load diiop

可以在控制台用 tell 命令停止任务：

> tell http quit > tell diiop quit

可以刷新 DIIOP 任务：

> tell diiop refresh

可以重新启动 HTTP 任务：

> tell http restart

获取 IOR

在 Domino 服务器上，IOR 是一个名为 diiop_ior.txt 的文件，位于 Domino 数据目录下的 domino/html 子目录中。IOR 是对象的字符串编码，包含对服务器的 CORBA 访问的识别信息。客户机会将字符串 IOR 解码，并用它来建立远程会话。

默认情况下，远程客户机通过 Web 服务器端口（其通常支持 HTTP 请求）来请求服务器 IOR，然后通过 DIIOP 端口进行会话请求。可以分别执行这两个请求。例如：

String ior = NotesFactory.getIOR("myhost.east.acme.com"); 
// Get IOR using Web server port
Session s = NotesFactory.createSessionWithIOR(ior); 
// Create session using DIIOP port

等价于：

Session s = NotesFactory.createSession("myhost.east.acme.com");

在 NotesFactory 调用中，可以在主机名称或 IP 地址后面添加冒号和端口号，来指定用于获取 IOR 的主机端口。如果 Web 服务器没有运行，可以使用这种机制，通过 DIIOP 端口支持 IOR 的 HTTP 请求，例如：

String ior = NotesFactory.getIOR("myhost.east.acme.com:63148"); 
// Get IOR using DIIOP port
Session s = NotesFactory.createSessionWithIOR(ior); 
// Create session using DIIOP port

然而，两步式编码顺序并不是必需的。可以将其简化为：

Session s = NotesFactory.createSession("myhost.east.acme.com:63148");

不能用 DIIOP 端口获取除 diiop_ior.txt 之外的文本文件。

如果通过 Web 服务器端口来获取 IOR，Web 服务器端口，那么必须允许进行匿名访问。在 Domino Directory 的 Server 文档中，转至 Ports 选项卡，然后转至 Web 选项卡。确保 Authentication options 下的 Anonymous 字段被设为 Yes。

图 6. Authentication options

指定 DIIOP 端口来获取 IOR 的能力是 Notes/Domino 6 的新功能。现在就可以使用远程调用，无需允许对 Web 服务器的匿名访问，甚至无需启动 Web 服务器。

也可以通过其他方法获取 IOR，然后使用 createSessionWithIOR。例如，可以将 diiop_ior.txt 文件从服务器计算机复制到客户机计算机上。如果客户机上包含对将使用的服务器有效的 diiop_ior.txt 文件，那么可以使用下列代码：

import lotus.domino.*;
import java.io.*;
public class platformior
{
    public static void main(String argv[])    
    {    
        try        
            {            
                FileInputStream fin = new FileInputStream(            
                "c://Lotus//NotesR6//diiop_ior.txt");            
                InputStreamReader fisr = new InputStreamReader(fin);            
                BufferedReader br = new BufferedReader(fisr);            
                String ior = br.readLine();            
                fin.close();            
                Session s = NotesFactory.createSessionWithIOR(ior);            
                //Operational code goes here            
                }            
                catch(Exception e)            
                {            
                e.printStackTrace();            
                }
            }
        }

注意 IOR 设置可能会失效。服务器上的以下任何更改都会使客户机上的 diiop_ior.txt 文件失效：

• 更改 DIIOP 端口号。
• 启用或禁用 DIIOP 端口。
• 更改 TCP/IP 地址。

可以通过指定服务器主机名称而不是服务器的 TCP/IP 地址来避免最后一项。在 Server 文档中，转至 Internet Protocols 选项卡，然后转至 DIIOP 选项卡。在“Host name/Address”字段中指定服务器的 Internet 主机名。

图 7. DIIOP 选项卡中的 Host name/Address 字段

这将强制 diiop_ior.txt 使用服务器的主机名而不是使用 IP 地址。也可以通过 Notes.ini 变量 DIIOPIORHost 来强制使用主机名。

回页首

访问控制

授予用户的对客户机上 Domino 服务器或者 Notes/Domino 软件的访问级别取决于 createSession 如何进行编码以及服务器或者客户机的设置。

访问控制是通过以下两种方式之一实现的：

• Domino Directory 中的名称和相关 Internet 密码
  这种方式用于本地或者远程访问。对于本地访问，运行代码的计算机必须配置为 Domino 服务器。
• 当前 Notes ID（由 Notes.ini 中的 KeyFileName 变量指定）
  这种方式仅用于本地调用。运行代码的计算机可以包含 Notes 客户机或者 Domino 服务器。

通过 Domino Directory 访问

对于通过 Domino Directory 访问，代码将确定用户是以 Anonymous 匿名访问服务器，还是作为 Domino Directory 中列出的用户来访问服务器。在 NotesFactory 调用中，如果仅指定了主机名称，或指定了空字符串作为用户名和密码，那么将以 Anonymous 访问服务器。例如：

Session s = NotesFactory.createSession("myhost.east.acme.com:63148");

或者

Session s = NotesFactory.createSession("myhost.east.acme.com:63148", "", "");

要以 Domino 用户访问服务器，需要指定用户名和 Internet 密码作为参数 2 和参数 3。用户名和密码必须与服务器上 Domino Directory 中的 Person 文档匹配，例如：

Session s = NotesFactory.createSession("myhost.east.acme.com:63148", "Jane Smith/East/Acme", "topS3cr3t");

如果对运行代码的计算机上安装的 Domino 服务器进行本地访问，需要指定主机名称为空字符串，例如：

Session s = NotesFactory.createSession("", "Jane Smith/East/Acme", "topS3cr3t")

对于 Anonymous 访问，需要指定用户名和密码为空字符串：

Session s = NotesFactory.createSession("", "", "")

对于本地访问，则不必运行服务器。

Domino Directory 的 Server 文档中的设置控制着是 Anonymous 访问还是命名访问。在 Server 文档中，转至 Ports 选项卡、Internet Ports 选项卡和 DIIOP 选项卡。下表指定了设置：

客户机代码	Authentication options
createSession(host, "", "")	Anonymous 必须为 Yes，以便访问服务器
createSession(host, name, password)	Name & password 必须为 Yes，以便访问服务器

对于 Name & password 验证，名称必须是服务器上 Domino Directory 中 Person 文档中的用户名，密码必须是同一 Person 文档中的 Internet 密码。可以进一步限制访问，方法是在 Domino Directory 的 Server 文档中，在 Ports 选项卡和 Internet Ports 选项卡下，将 Enforce server access settings 字段设为 Yes，以便使用 DIIOP 端口。然后在 Security 选项卡下的 Server Access 选项卡中指定希望的访问。

Server 文档包含下列字段，用于控制由远程或本地 Java 类创建的 Internet 会话的安全性。在 createSession 使用用户名和密码或 SSO 令牌时，Internet 会话的访问权限等同于 Web 用户。下表列出了 Security 选项卡中的字段。

字段	备注
Security settings
Access server	要通过远程或本地 Internet 会话访问服务器，则您必须位于该列表中
Not access server	如果您在该列表中，则不能进行远程或本地 Internet 会话
Create databases & templates	允许通过后端方法创建新数据库和模板
Create new replicas	允许通过后端方法创建数据库副本
Create master templates	允许通过后端方法创建主模板
Programmability Restrictions
Run unrestricted methods and operations	此列表中显示的后端类的用户可以运行有特权的 Java 方法。该设置不适用于本地 Java 操作，如在本地执行写入文件系统，该操作在远程 Java 程序上执行。（换句话说，此设置仅对 Domino 服务器访问有影响，不阻止使用远程类的客户机访问本机文件系统中的文件。）
Sign agents to run on behalf of someone else	作为 Web 用户运行的代理将以 Internet 会话登录用户的有效用户名进行登录
Sign agents to run on behalf of the invoker of the agent	作为 Web 用户运行的代理将以 Internet 会话登录用户的有效用户名进行登录
(TCP/IP) Anonymous	DIIOP 验证不需要名称和密码
(SSL) Name and Password	DIIOP SSL 验证需要名称和密码
(SSL) Anonymous	DIIOP SSL 验证不需要名称和密码
Internet Access
Internet Authentication	用于 Internet 会话登录用户名。有关其他说明，请参阅字段帮助或者文档

下表列出了 DIIOP 选项卡中的字段：

字段	备注
(TCP/IP) Name and Password	DIIOP 验证需要名称和密码
(TCP/IP) Anonymous	DIIOP 验证不需要名称和密码
(TCP/IP) Enforce server access settings	DIIOP 使用 Security 选项卡下的 Server Access 设置
(SSL) Name and Password	DIIOP SSL 验证需要名称和密码
(SSL) Anonymous	DIIOP SSL 验证不需要名称和密码

下列 Notes.ini 设置会影响通过远程或本地 Java 类获得的 Internet 会话的安全性

Notes.ini 设置	描述
NoAmbiguousWebNames	如果 DIIOP 登录用户名在 $Users 视图中有多个匹配名称，NoAmbiguousWebNames=1 会导致验证失败
WebNameAuthentic	WebNameAuthentic=1 会使 DIIOP 登录名称被视为用户的识别名
NABWebLookupView	NABWebLookupView="xxx" 会使 Domino Directory 中的“XXX”用来搜索 DIIOP 登录名称

同时注意，数据库 ACL“Maximum Internet Name and Password access”设置会影响通过远程或者本地 Java 类获得的 Internet 会话的安全性，因为 DIIOP 登录用户被限制为这一访问级别。

服务器大约半小时刷新一次安全性选项的缓存。控制台命令“tell diiop refresh”可以强制立即刷新。

通过 Notes ID 访问

对于通过当前 Notes ID 的访问，无需指定参数：

Session s = NotesFactory.createSession()

在这种情况下，当需要进行身份验证时（例如，访问数据库），会显示对话框，并要求输入 Notes ID 口令。所选择的 Notes ID 是在搜索路径中第一个 Notes.ini 文件的 KeyFileName 变量中指定的。用户必须输入正确的密码或者单击 Cancel 以继续后续操作。

除了不指定参数外，也可以指定第二个参数为 null（转换为 String），第三个参数为 Notes ID 的密码：

Session s = NotesFactory.createSession((String)null, (String)null, "tops3cr3t")

在服务器上，上述方法会根据 Readers 字段限制访问。要进行完全的访问，可以用以下方法：

Session s = NotesFactory.createSessionWithFullAccess()

或者

Session s = NotesFactory.createSessionWithFullAccess("tops3cr3t")

回页首

结束语

您现在了解了在本地或远程从 Java 应用程序使用 Domino Objects 的一些基本知识。在下一篇文章中，您将了解 SSL 加密、servlet、连接池、单点登录（SSO）、防火墙、超时、回收及故障检修。

参考资料

• 您可以参阅本文在 developerWorks 全球站点上的 英文原文 。
  
  
• Java/CORBA toolkit documentation
  
  
• Java and Domino: Building e-Business Applications for the Web
  
  
• Connecting Domino to the Enterprise Using Java Redbook
  
  
• Domino Designer Help
  

作者简介

		Robert Perron 是位于马萨诸塞州 Westford 的 Lotus 文档架构师。他从二十世纪九十年代初开始就一直为 Lotus Notes 和 Domino 开发文档，主要致力于可编程能力的开发。他曾为 LotusScript 和 Java Notes 类开发文档，并与别人合著了 60 Minute Guide to LotusScript 3 - Programming for Notes 4 一书。他曾为 LDD Today 撰写多篇文章。去年，他为 The View 撰写了“A Comprehensive Tour of Programming Enhancements in Notes/Domino 6”一文。

		Steve Nikopoulos 是 Domino Server Programmability 小组的高级软件工程师。他最近的工作包括远程 Domino Objects、Domino/Websphere 集成和单点登录。他在空余时间喜欢与家人一起骑脚踏车。

		Kevin Smith 是位于 Westford 的 IBM Messaging & Collaboration Development 组织的顾问软件工程师，目前负责 Domino 服务器的可编程功能的开发。他于 1990 年进入 Lotus，是一名 Lotus 1-2-3/M 的技术支持工程师，Lotus 1-2-3/M 是植入有名的 IBM 大型机的著名 PC 电子表格，是最早的 IBM-Lotus 冒险投资工程之一。