级别: 中级

Shiva Nistala , 高级 Java 顾问, Adea Group
Sukumar Konduru , 顾问软件工程师, IBM

2005 年 8 月 15 日

本文将向您展示如何使用 IBM Workplace Collaboration Services 2.5 API 工具包开发扩展 Workplace Collaboration Services 环境的应用程序。

IBM Workplace Collaboration Services 2.5 是构建在 WebSphere Portal 之上的协作特性和服务的综合集合。Workplace Collaboration Services 2.5 的基础安装提供了一些最常用的协作特性，比如电子邮件、文档管理、日历、在线学习和网络会议。这些特性都是通过策略来管理和维护的。这允许管理员提供针对用户的安全的、受控制的访问。有关 Workplace Collaboration Services 的更多信息，请参阅 developerWorks: Lotus 上的文章“IBM Workplace Collaboration Services 2.5 的新特性”。

Workplace Collaboration Services 2.5 API 工具包 是为了使 Workplace Collaboration Services 2.5 变得可扩展和可定制而设计的编程工具。该工具包公开了许多公共 API，这些 API 允许您与大多数 Workplace Collaboration Services 内置应用程序服务（如电子邮件和网络会议）进行交互。此工具包允许 ISV、业务合作伙伴和其他人构建与 IBM Workplace 基础设施交互和集成的定制应用程序组件。目前，该工具包是作为一个单独的组件提供的，由几个 JAR 文件和一个安装在 Workplace Collaboration Services 2.5 服务器之上的 EAR 文件组成。您可以在这里下载最新的 Workplace Collaboration Services API 工具包。

在本文中，我们将讨论 API 的设计。沿着这一思路，我们将仔细查看一个已经创建好的示例 portlet 应用程序，该应用程序将操作一个文档服务。使用本文中演示的设计和编码方法，您可以开发与其他业务组件交互的应用程序。您还会发现一个部署好的示例 WAR 文件，以及我们的示例的源代码。（可以从本文结尾处的“下载”部分下载该示例。）

本文假定您是一位经验丰富的应用程序开发人员，熟悉 Workplace Collaboration Services 或其他 IBM Workplace 产品。有关的更多信息，请参阅 IBM Workplace application development page。

用 Workplace Collaboration Services 进行应用程序开发

在开始深入研究 API 的细节之前，理解一些与 IBM Workplace Collaboration Services 2.5 相关的应用程序开发概念非常重要。IBM Workplace 应用程序是一个基于模板的页面程序集，在这个程序集中，每个页面都可能由一个或多个组件组成。这是一个将人员、内容和过程组合在一起、成功地完成某一项任务的虚拟场所。每个组件通常都是一个 portlet，因为 portlet 是基于门户的基础设施（如 Workplace Collaboration Services）的、基本的、“不可分割的”元素。

Workplace Collaboration Services 包含一些内置模板，比如 Discussion、Document Library、Customer Support Team 和其他可以用来快速构建应用程序的模板。开发人员可以扩展和定制这一模板集。

在 Workplace Collaboration Services 应用程序开发环境中，通常有三种类型的开发人员角色：

• 组件开发人员使用 Workplace Collaboration Services API 工具包提供的 API 构建 Workplace Collaboration Services 应用程序和组件，同时还使用 J2EE 编程模型。组件开发人员还负责将定制组件与任意第三方系统集成在一起。
• 解决方案提供者和系统集成者使用 Workplace Collaboration Services API 、模板和应用程序来创建应用程序模板，并将组件开发人员开发的定制组件（如果可用）组合在一起。
• 业务用户从现有模板创建 Workplace Collaboration Services 应用程序模板，或者为其他用户定制模板。通常，这些任务不需要什么编码技巧。

所有应用程序都运行在一个协作环境下。例如，默认情况下，所有团队项目应用程序都有一个预先构建的成员 portlet，该 portlet 能够显示任何参与成员的在线感知（online awareness）。此外，应用程序的拥有者（或管理员）可以控制对应用程序的访问，并限制用户可以在此应用程序中所做的事。

回页首

API 的类别

公共 Workplace Collaboration Services API 可以划分为 6 个主要类别。

Collaborative Application Component Interfaces

Collaborative Application Component Interfaces (CACI) API 允许开发定制业务组件，并在 Workplace Collaboration Services 环境中集成这些组件。您可以实现一个或多个 Lifecycle、Membership、Templatable、Sensor 和 Transactional 接口。这使得 Workplace Collaboration Services 能够在发生特定事件期间调用您的实现，比如在创建和毁坏组件的时候。

Workplace Mail Messaging SPI

Workplace Mail Messaging SPI 允许您扩展默认的 Workplace Collaboration Services 邮件服务。您可以检查信封和每条邮件消息的内容，确定每条消息的目标文件夹。这些 API 通常用于病毒扫描和垃圾邮件过滤。

Workplace Instant Messaging SPI

使用 Workplace Instant Messaging SPI，您可以检查 Workplace Collaboration Services 环境中的即时消息传递通信量。这些 API 通常用于聊天记录和聊天事务。（请参阅 developerWorks: Lotus 上的文章“使用 IBM Workplace Instant Messaging SPI 进行翻译”。）您可以在一个 servlet 中实现此接口，并向 Workplace Collaboration Services 注册它。

IBM Workplace Collaboration Services Java Server Pages (JSP) 标签

JSP 标签使您能够向 portlet 添加协作功能（如到场提醒）。尽管 JSP 标签库已经包含在 Workplace Collaboration Services 2.5 服务器中，但您将在随工具包提供的示例中找到大量关于如何使用它们的文档。例如，Noteboard 示例演示了 person 标签的用法。

IBM Workplace Client Technology 平台的 API

使用这些 API，可以用新的应用程序扩展 IBM Workplace Client Technology 平台。

Component and Application Infrastructure Services API

Component and Application Infrastructure Services API 被细分为两类：

• Component Services API 允许您访问现有 Workplace Collaboration Services 业务组件提供的服务和内容。业务组件的例子包括 Team Calendar、Discussion 和 Document Library。
• Infrastructure Services API 允许您管理 Workplace Collaboration Services 应用程序、模板和其他实例。

在本文中，我们将通过演示一个使用 API 调用 Workplace 文档服务的示例 portlet，重点介绍 Component Services API。可以从本文结尾处的“下载”部分下载这一示例。

回页首

API 的设计

此 API 工具包中的对象是为改进易于使用性和一致性而设计的。API 中的对象模型很容易理解，因为它基于 GUI 中使用的命名约定。这使您可以快速地将 API 对象与 GUI 中看到的内容联系起来。例如，可以使用应用程序数据对象来表示 Workplace Collaboration Services 应用程序，这一技术与 GUI Common 对象中使用的技术相同，可以抽象 GUI Common 对象，在整个 API 中表示类似的概念。例如，无论何时需要，都可以在整个 API 中使用相同的人员对象和组对象。多数情况下，还可以看见针对这些服务方法的类似搜索选项和数据检索选项。

这些 API 还根据 Workplace Collaboration Services 访问控制和用户策略的指示，增强了业务服务组件的安全性。因为对这些 API 的调用只在当前已登陆用户的安全上下文中起作用，所以无法忽略业务服务组件的安全性。另一方面，Web 服务使用基本的身份验证和 LTPA 来识别安全上下文。

SDO 兼容的设计

Workplace Collaboration Services API 的设计类似于 Service Data Objects (SDO) 编程模型的设计。尽管 Workplace Collaboration Services 2.5 中没有使用 SDO，但数据模型是以某种将来不用重构数据对象就可以使用 SDO 的方式设计的。

SDO 支持以下三个关键概念：

• 数据对象，支持惟一的数据访问，并提供利用某种“开放式”数据锁定方法，以切断连接的方式来存储数据的能力。
• 数据图，用于存储元数据，并跟踪对数据对象的数据修改。
• 数据调节，其中，调节者服务（mediator service）负责使用来自数据源的数据对象填充数据图，并在必要的时候使用数据图中的更改更新数据存储。调节者服务特定于某一个数据存储，是实现数据存储独立性的组件。有关 SDO 的更多信息，请参阅 developerWorks 上的文章“服务数据对象简介”。

因为 SDO 与平台和语言无关，所以它在受支持的对象类型上强加了某些限制。例如，所有原始类型、包装对象、字符串和日期对象都受支持。您所使用的所有定制对象都必须由受支持的类型组成。此外，所有集合都是列表。最后，受 SDO 支持的数据对象类中的列表字段应该只有 getter，没有 setter。要将某一个项添加到列表字段中，只需获得该列表，并将此项添加到列表中即可。

Workplace Collaboration Services API 工具包使用与 SDO 设计兼容的数据对象。您将发现，无论何时将数据集合对象传递给某一服务，或者从某一服务检索数据集合对象，都将使用 DataObjectList（请参阅此工具包的 Java 文档）。更确切地说，每次检索一个数据图（一个 DataObjectList），都可以通过使用 RetrievalOptions（这是另一个数据对象，请参阅 Java 文档）来指定您想要多少数据。可以将这些检索选项作为服务方法参数传递，指出您所需要的数据量。

回页首

组件服务 API 的设计

公共 API 包括 Java Object Factories、EJB delegates 和一个 a Java EJB 层。这些 API 可以访问公共 API 服务实现。您应该注意到，同一组 API 既可以用在服务器上，也可以用在 IBM Workplace Client Technology 平台上，并且在联机和脱机模式下都可以运行。此外，这些 API 是作为 Web 服务公开的。这意味着任何 Web 服务客户机都可以使用 HTTP/SOAP 来访问业务组件服务。

通常，业务组件服务是在调用内部 Workplace Collaboration Services API 的 Plain Old Java Object (POJO) 中实现的。Workplace Collaboration Services API 工具包在 POJO 实现的服务之上有一个瘦 EJB 层。即使 EJB 只委托对 POJO 实现的调用，它们也要提供对该服务的远程访问。因为 EJB 难以处理，所以在这之上提供了一个委托层。这些委托是根据它们的使用情况（在联机或脱机模式下，在服务器或 Workplace Client Technology 平台上）分别配置的。根据特殊的运行时模式，委托被配置为直接访问服务 EJB 或 POJO 代码（这样就忽略了 EJB 层）。绝对不能直接调用这些委托；它们是通过内部的委托工厂机制动态生成的。 API 推荐利用 FactoryCreator 接口创建所需的 API 服务工厂来使用此工具包。该工厂允许创建 Workplace Collaboration Services API 服务，这适合当前的操作模式。

典型的 API 使用场景是调用工厂类方法来创建服务方法和内容对象。在需要进行特殊类型的调用时，可使用内容对象调用服务对象方法。

回页首

示例代码

在本文提供的示例代码中（请参阅“下载”部分），我们根据用户提供的输入，创建了一个简单的 JSF portlet，它将调用工具包 API 来创建文档的。在这个示例接口中，我们将请求文档库的名称（创建文档库是创建文档的先决条件）、将创建的文档的名称以及表示文档内容的文本。

当用户通过单击提交按钮提交该请求时，可以使用 API 定位文档库。如果找不到指定的文档库，执行将停止，并发送一个错误，指出用户没有在试图创建文档之前创建文档库。如果找到指定的文档库，则在该文档库中继续使用所提供的内容和指定名称创建文档。

我们的应用程序所使用的文档服务创建过程的逻辑流由三个基本步骤组成：

1. 调用 FactoryCreator 的静态方法来创建 ServiceFactory。
2. 调用 ServiceFactory 的实例方法来获得所需要的 DocumentLibraryService。
3. 调用 DocumentLibraryService 上的实例方法 (getLibraryDescriptions) 来获得文档库的列表。该方法将获得 portlet 的输入页面中所指定文档库的惟一标识符。需要重点注意的是，返回类型是 DataObjectList，它是 DocumentLibraryDescription 对象的一个集合。

文档创建顺序（数据对象创建）由以下几个基本步骤组成：

1. 调用 FactoryCreator 的静态方法来创建 DocumentFactory。
2. 调用 DocumentFactory 上的实例方法来创建文档。
3. 调用各种 setter 方法来设置名称、库和文档内容。
4. 使用以前创建的文档来调用服务对象上的实例方法。

示例详解

让我们一块一块地查看示例代码。本文并没有讨论 portlet 的创建和 JSF 代码；而是重点讨论了最终创建文档的页面代码类。首先，要导入随工具包一起提供的必要 API 类：

import com.ibm.workplace.api.factory.FactoryCreator;
            import com.ibm.workplace.api.factory.ServiceFactory;
            import com.ibm.workplace.api.factory.DocumentFactory;
            import com.ibm.workplace.api.document.data.Document;
            import com.ibm.workplace.api.document.data.DocumentLibraryDescription;
            import com.ibm.workplace.api.document.service.DocumentLibraryService;
            import com.ibm.workplace.api.common.data.DataObjectList;
            import com.ibm.workplace.api.common.exception.WorkplaceException;
            

这些类是工具包 JAR 文件的一部分。要确保类路径中包含了所有的 JAR 文件。接着，我们将创建所需的 DocumentLibraryService 对象，并确定指定的文档库存在：

ServiceFactory fac = FactoryCreator.createServiceFactory();
            DocumentLibraryService docser = fac.createDocumentLibraryService();
            DataObjectList list = docser.getLibraryDescriptions();
            DocumentLibraryDescription docdesc = null;
            List doclibs = list.getObjects();
            if (doclibs.isEmpty())
            return "Failed: Please create a document Library: " + libname;
            Iterator it = doclibs.iterator();
            boolean libexists = false;
            while (it.hasNext())
            {
            docdesc = (DocumentLibraryDescription) it.next();
            if (docdesc.getName().equals(libname))
            {
            doclibid = docdesc.getId();
            libexists = true;
            }
            }
            if (!libexists) return "Failed: Please create a document Library: " + libname;
            

最后，将使用指定的属性创建文档对象，并将它放置在文档库中：

DocumentFactory dfac = FactoryCreator.createDocumentFactory();
            Document doc = dfac.createDocument();
            doc.setName(docname);
            doc.setLibraryId(doclibid);
            retVal = "Success - You have created document: ";
            doc.setContent(content.getBytes());
            retVal = retVal + docser.addEntry(doc);
            

回页首

我们使用的示例应用程序

要使用我们的示例应用程序，则必须先安装 Workplace Collaboration Services 2.5 API 工具包。然后，安装从本文的“下载”部分可以获得的一个简单的 doc.war 文件，并定制一个页面来包括 SimpleDoc portlet。在设置好 portlet 之后，可转至 Documents 页面，并创建一个叫作 mylibrary1 的库，如图 1 所示。

接下来，转至为 SimpleDoc portlet 创建的页面，并输入所需的信息（参见图 2）。

完成图 2 中所示的以下字段。

• Enter library name 是为存储文档而创建的库名。在我们的示例中，此名称为 mylibrary1。
• Enter Doc Name 是创建的文档的名称，在这里，此名称为 mydocument1。
• Enter Content 是文档的内容。

在完成这些字段之后，单击 Submit。随后将显示消息“Success - You have created document”。现在回到 Documents 页面，并单击 mylibrary1 查看新文档（参见图 3）。

回页首

结束语

在本文中，我们讨论了可在 Workplace Collaboration Services 2.5 API 工具包中使用的 API 的一般类别，查看了 API 的设计，以及如何将它们与 SDO 编程模型联系在一起。我们还查看了组件服务 API 工作方式的一些细节。并研究了本文提供的示例应用程序，向您展示如何使用 API 来调用 DocumentLibraryService 对象上的方法，从而创建一个文档。使用其他 DataObjects 和调用其他服务 API（比如使用 MailService 发送邮件和使用 CalendarService 创建事件条目）与我们的示例非常相似。