级别:中级

ShivaNistala,高级Java顾问,AdeaGroup
SukumarKonduru,顾问软件工程师,IBM

2005年8月15日

本文将向您展示如何使用IBMWorkplaceCollaborationServices2.5API工具包开发扩展WorkplaceCollaborationServices环境的应用程序。

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

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

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

本文假定您是一位经验丰富的应用程序开发人员，熟悉WorkplaceCollaborationServices或其他IBMWorkplace产品。有关的更多信息，请参阅IBMWorkplaceapplicationdevelopmentpage。

用WorkplaceCollaborationServices进行应用程序开发

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

WorkplaceCollaborationServices包含一些内置模板，比如Discussion、DocumentLibrary、CustomerSupportTeam和其他可以用来快速构建应用程序的模板。开发人员可以扩展和定制这一模板集。

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

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

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

回页首

API的类别

公共WorkplaceCollaborationServicesAPI可以划分为6个主要类别。

CollaborativeApplicationComponentInterfaces

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

WorkplaceMailMessagingSPI

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

WorkplaceInstantMessagingSPI

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

IBMWorkplaceCollaborationServicesJavaServerPages(JSP)标签

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

IBMWorkplaceClientTechnology平台的API

使用这些API，可以用新的应用程序扩展IBMWorkplaceClientTechnology平台。

ComponentandApplicationInfrastructureServicesAPI

ComponentandApplicationInfrastructureServicesAPI被细分为两类：

• ComponentServicesAPI允许您访问现有WorkplaceCollaborationServices业务组件提供的服务和内容。业务组件的例子包括TeamCalendar、Discussion和DocumentLibrary。
• InfrastructureServicesAPI允许您管理WorkplaceCollaborationServices应用程序、模板和其他实例。

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

回页首

API的设计

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

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

SDO兼容的设计

WorkplaceCollaborationServicesAPI的设计类似于ServiceDataObjects(SDO)编程模型的设计。尽管WorkplaceCollaborationServices2.5中没有使用SDO，但数据模型是以某种将来不用重构数据对象就可以使用SDO的方式设计的。

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

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

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

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

回页首

组件服务API的设计

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

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

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

回页首

示例代码

在本文提供的示例代码中（请参阅“下载”部分），我们根据用户提供的输入，创建了一个简单的JSFportlet，它将调用工具包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类：

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

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

ServiceFactoryfac=FactoryCreator.createServiceFactory();DocumentLibraryServicedocser=fac.createDocumentLibraryService();DataObjectListlist=docser.getLibraryDescriptions();DocumentLibraryDescriptiondocdesc=null;Listdoclibs=list.getObjects();if(doclibs.isEmpty())return"Failed:PleasecreateadocumentLibrary:" libname;Iteratorit=doclibs.iterator();booleanlibexists=false;while(it.hasNext()){docdesc=(DocumentLibraryDescription)it.next();if(docdesc.getName().equals(libname)){doclibid=docdesc.getId();libexists=true;}}if(!libexists)return"Failed:PleasecreateadocumentLibrary:" libname;

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

DocumentFactorydfac=FactoryCreator.createDocumentFactory();Documentdoc=dfac.createDocument();doc.setName(docname);doc.setLibraryId(doclibid);retVal="Success-Youhavecreateddocument:";doc.setContent(content.getBytes());retVal=retVal docser.addEntry(doc);

回页首

我们使用的示例应用程序

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

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

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

• Enterlibraryname是为存储文档而创建的库名。在我们的示例中，此名称为mylibrary1。
• EnterDocName是创建的文档的名称，在这里，此名称为mydocument1。
• EnterContent是文档的内容。

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

回页首

结束语

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