使用 IBM Lotus Quickr 8.1.1 services for WebSphere Portal 中的 REST 文档服务管理定制字段

本文介绍了 IBM® Lotus® Quickr™ 8.1.1 services for IBM WebSphere® Portal(也称为 Java™ 2 Platform, Enterprise Edition (J2EE) 版本的 Lotus Quickr)中的 Representational State Transfer (REST) 文档服务的定制字段支持。解释了定制字段的概念,讨论了使用 Lotus Quickr REST 文档服务管理定制字段的编程模型,并通过一个业务场景展示了如何扩展文档属性的核心部分。

Xiao Pei Liu, 软件工程师, IBM

Xiao Pei Liu 是北京 IBM Lotus Quickr 团队的 API 测试软件工程师。



Bing Feng Han, 软件工程师, IBM

Bing Feng Han 是 IBM 位于北京的 Lotus Quickr Connector 团队的软件工程师。



Zhang Zi Xuan, 软件工程师, IBM

Zhang Zi Xuan 是 IBM 位于北京的 Lotus Quickr Service 团队的软件工程师。



2010 年 3 月 15 日

编者注:很了解该主题?希望分享专业知识吗?请立即加入到 IBM Lotus 软件 wiki 项目。

先决条件

本文档对希望从支持定制属性的现有内容存储库迁移或集成内容的用户非常有帮助。要从本文获得最大收益,您应该了解:

  • Lotus Quickr services for WebSphere Portal
  • REST 服务
  • Atom Syndication Format 和 Atom Publishing Protocol (AtomPub)
  • Java 编程
  • Apache Abdera,它是 Atom 和 AtomPub 协议的 Java 实现

Lotus Quickr 8.1.1 中的定制字段支持概述

Lotus Quickr 是一款能够帮助您在线分享内容、协调工作和加快工作进度的团队协作软件。Lotus Quickr 的文档库组件为您提供在协作环境中管理所有团队文件的高级功能,包括版本化支持,工作流管理和向文档添加定制字段。

定制字段

一般而言,我们都需要使用元数据来描述主要的文档内容。Lotus Quickr 中的每个文档都有一组标准的元数据字段。普通的元数据集包括文件名、作者、创建时间和更新时间;不过,对于某些情况,普通的元数据集不足以描述文件的属性。

因此引入了定制字段,它是一组用户针对特定类型的文档定义的扩展属性。这些定制字段为在 Lotus Quickr 中搜索内容提供较大帮助。在 Lotus Quickr 中,定制字段由一个属性表定义,并根据文档类型与文档关联。

属性表

属性表包含几个由用户设计以满足特定业务需求的字段。字段类型、选项、默认值和字段顺序等都由用户定义,从而为文档添加定制的数据元素。

属性表通常在本地文档库中定义和使用,但是 Lotus Quickr 管理员能够定义共享属性表,这种属性表可以在 Lotus Quickr 服务器中的任何文档库中使用。

要创建属性表,在 Web 用户界面(UI)中进入主页,展开 Manage Document Elements,选择 Property Sheets 然后单击 Create Property Sheet(见图 1)。

图 1. 在 Web UI 上创建属性表
在 Web UI 上创建属性表

要向属性表添加字段,单击 Create Property Sheet 窗口右侧的 Add Fields,接着输入字段名、选项值、显示样式和默认值等(见图 2)。

图 2. 向属性表添加字段
向属性表添加字段

文档类型

属性表提供可重用的字段定义集。可以将多个属性表附加到同一个文档,文档可以使用的属性表的数量由该文档的文档类型决定。

文档类型提供一个可以定义文档行为的机制,包括文档模板、版本化、工作流定义和定制字段。当上传特定类型的文档时,所有这些预定义的参数都将生效。

如前所述,定制字段不是在文档类型中直接定义的;相反,它们是在属性表中定义的,然后再添加到文档类型。类似于属性表,文档类型通常是在文档库作用域中定义的,但是 Lotus Quickr 管理员可以为所有文档库定义文档类型。

要管理所有文档类型,从 Web UI 进入主页,展开 Manage Document Elements 并选择 Document Types。在创建或更新文档类型时,可以从文档类型选择需要添加或删除的属性表。

要在创建文档类型时添加属性表,单击 Property Sheets 部分的 Add an existing property sheet 链接,然后在 Choose Property Sheet 窗口选择想要添加的属性表(这里是 New Property Sheet;见图 3)。

图 3. 将属性表添加到已创建的文档类型
将属性表添加到已创建的文档类型

向文档应用定制字段

创建了属性表和文档类型之后,就可以上传或创建文档并选择想要的文档类型。然后,您必须输入在属性表中定义的属性;您输入的值将成为文档的元数据。

要选择文档类型并输入属性表中定义的字段,请遵循以下步骤:

  1. 在主页选择 Upload,然后在 Upload Files 窗口中单击 Document type 部分的 Change 链接(见图 4)。
  2. 选择您想要在 Choose Document Type 窗口中使用的文档类型(在这里为 New Document Type)。

注意,现在文档类型中的属性显示在页面底部新出现的 Document type properties 部分中。

图 4. 在属性表中选择文档类型和字段
在属性表中选择文档类型和字段

Lotus Quickr 公共服务中的定制字段支持

Lotus Quickr 还包含一组公共服务(API),用于访问 Lotus Quickr 管理的内容。您可以使用这些服务来构建定制的应用程序,或将 Lotus Quickr 内容与其他应用程序集成。

REST 文档服务是 Lotus Quickr 公共服务的主要部分,它允许您使用 REST 式编程模型以编程的方式访问和更新 Lotus Quickr 文档库中的许多信息,所使用的 REST 式编程模型遵循 Atom Publishing Protocol (RFC 5023) 并实现 Atom Syndication Format (RFC 4287)。

REST 文档服务从 Lotus Quickr 8.0 开始提供创建、获取、更新和删除 Lotus Quickr 文档库中的文档的功能,但是从 Lotus Quickr 8.1.1(2008 年 12 月发布)开始才支持定制字段。

在本文的下面几节中,我们将介绍在 REST 文档服务中管理定制字段的编程模型,并通过一个示例程序演示如何在真实的应用程序中使用这些服务。


使用 REST 编程模型管理定制字段

注意:在本文的上一节中,我们使用同一个术语 “属性表” 来描述定制字段的定义和在文档中实现的定制字段。但是,在 REST 编程模型中使用术语 “属性表类型” 来描述定制字段的定义。文档实现了属性表类型之后,属性表类型的定制字段的值称为 “属性表”。在下文中,我们在 REST 编程模型中使用这些新的术语。

创建属性表类型

要在库中创建属性表,您可以在 HTTP 请求体中提供一个 property-sheet-type Atom 条目来向属性表类型的提要 URL http://<host>:<port>/dm/atom/library/<libraryId>/propertysheettypes/feed 发送一个 POST 请求(见清单 1)。

清单 1. 请求创建属性表类型
 POST /library/08ca5f0044ab2d6a858eed71ca20d4cf/propertysheettypes/feed HTTP/1.1 
 Host: example.com 
 Content-Type: application/atom+xml 
 Content-Length: nnnn 
 Authorization: Basic ... 

 <entry xml:lang="en" xmlns:td="urn:ibm.com/td"> 
    <id>urn:lsid:ibm.com:td:8b40f50049641d8789a2d97accc4bd33</id> 
    <td:uuid>8b40f50049641d8789a2d97accc4bd33/<td:uuid> 
    <category term="propertysheettype" scheme="tag:ibm.com,2006:td/type" 
    label="propertySheetType"></category> 
    <author> 
      <uri>uid%3Dquikradm%2Co%3Ddefault+organization</uri> 
      <name>quikradm</name> 
      <email></email> 
    </author> 
    <title type="text">example</title> 
    <updated>2008-04-23T00:40:42.141Z</updated> 
    <summary type="text">example Property Sheet Type</summary> 
 <content type="application/atom+xml" 
 src="library/108c368048681104a123e3be2a21d9f5/propertysheettype"> 
  <meta:propertySheetTemplate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:clb="http://content.ibm.com/clb/1.0" 
  xmlns:meta="http://metadata.model.xsd.clb.content.ibm.com/1.0"> 
  <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
  maxLength="2048" multiple="false" propertyId="clb:ps1" 
  propertyName="clb:p_a6aa8d78-bc9e-4a35-a243-000aaaa8af12" 
  readonly="false" required="false" searchable="true"> 
    <meta:label label="Name" lang="en" /> 
    <meta:style name="ibm:textVariant" value="medium" /> 
  </meta:property>    <meta:property xsi:type="meta:ClbPropertyType" 
  dataType="boolean" multiple="false" propertyId="clb:ps2" 
  propertyName="clb:p_f4179b4b-9c29-45ea-a18b-3e507002015d" 
  readonly="false" required="false" searchable="true"> 
    <meta:label label="Gender" lang="en" /> 
  </meta:property> 
 </meta:propertySheetTemplate> 
 </content> 

    <td:contrainedMimeType>application/atom+xml<td:contrainedMimeType> 
    <td:isExtracted>true<td:isExtracted> 
 </entry>

以上的 Atom 条目包含一个 <content> 元素,它存储支持定义定制字段的 property-sheet 模板 XML 定义。

<propertySheetTemplate> 元素可以包含 0 个或多个在系统中定义单个定制字段的 <property> 元素。

每个元素必须包含一个 propertyId 属性,该属性在单个 <propertySheetTemplate> 中定义一个唯一的属性标识符。

此外,还有几个受支持的属性。表 1 列出了所有在 <property> 元素中受支持的属性。

表 1. 在 <property> 元素中受支持的属性
属性说明
datatype这个必选属性包含一个来自枚举选项集的字符串,该选项集为元数据属性指定基本数据类型。基本数据类型决定 ClbPropertySheet 上的哪个动态映射包含该元数据值。该属性支持以下基本数据类型值:
  • String
  • Double
  • Long
  • dateTime
  • Boolean

默认情况下,如果没有在 PropertySheetType XML 模板中指定值,那么数据类型则为 string。
multiple这个可选属性包含一个布尔值,该值决定属性是否支持多个值。默认值为 false。
indexable这个可选属性包含一个布尔值,该值决定是否将属性添加到索引。默认值为 false。
propertyId这个必选的字符串属性包含属性表模板中的每个属性的标识符。
propertyName这个必选字符串属性包含后端存储库中的属性的限定名。这个名称必须以 clb: 前缀的方式定义,并且必须在存储库中是唯一的。它是动态映射中包含该属性值的数据类型的键。
readonly这个可选属性包含一个布尔值,该值指定属性在内容存储库中是否是只读的。默认值为 false。
required这个可选属性包含一个布尔值,该值指定属性是否是内容库中的必选值。默认值为 false。
searchable这个可选属性包含一个布尔值,该值指定属性是否支持文本搜索。默认值为 true。
maxLength这个可选属性指定字符串属性的最长长度限制。如果没有指定,默认的最大长度为 252 个字符。

除了这些属性之外,每个 <property> 元素还可以包含:

  • 一些可选的子元素,包括一组 <label> 元素,这组元素中的每个元素都映射到一个位置
  • 一组 <style> 元素,它们为属性的可视表示提供提示
  • 一个 <option> 元素列表,它为属性定义一组可能使用的值
  • 一个 <defaultValue> 元素列表,如果在使用应用程序时没有指定应用到属性的值,那么该元素列表会为其定义默认值

清单 2 是一个示例属性元素。

清单 2. <property> 元素的代码示例
 <property 
  propertyId="prop1"
  dataType="string"
  multiple="false"
  propertyName="clb:p1234"
  readonly="false"
  required="true"
  searchable="false"> 
 <label label="Gender" lang="en" /> 
  <style name="ibm:selectionType" value="radio" /> 
  <defaultValue>Female</meta:defaultValue> 
  <option> 
      <value>Female</meta:value> 
      <label label="Female" lang="en" /> 
  </option> 
  <option> 
      <value>Male</meta:value> 
      <label label="Male" lang="en" /> 
  </option> 
 </property>

除了创建属性表类型之外,您还可以通过向属性表类型 URL 发送一个 GET 请求来获取一个属性表类型列表。此外,您也可以通过向以下 property-sheet-type 条目 URL 发送 GET、PUT 或 DELETE 操作来获取、更新或删除指定的属性表类型:

http://<host>:<port>/dm/atom/library/<libraryId>
/propertysheettypes/< propertysheettype-id>/entry

要详细了解 Lotus Quickr REST Document Service 中的 property-sheet-type 操作,请在 Lotus Quickr wiki 中查看 Documents Services主题。

创建文档类型

要在库中创建文档类型,您可以向文档类型的 Feed URL

http://<host>:<port>/dm/atom/library/<libraryId>/documenttypes/feed发送一个 POST 请求,方式是在 HTTP 请求体中提供一个文档类型 Atom 条目(见清单 3)。

清单 3. 请求创建文档类型
 POST /library/08ca5f0044ab2d6a858eed71ca20d4cf/documenttypes/feed HTTP/1.1 
 Host: example.com 
 Content-Type: application/atom+xml 
 Content-Length: nnnn 
 Authorization: Basic ... 

 <entry xml:base="http://example.com/dm/atom/library/ 
 08ca5f0044ab2d6a858eed71ca20d4cf/" xmlns="http://www.w3.org/2005/Atom"> 
    <id>urn:lsid:ibm.com:td:4e05cb0044f7e4f1937e932188721110</id> 
    <td:uuid>4e05cb0044f7e4f1937e932188721110/<td:uuid> 
    <category term="documenttype" scheme="tag:ibm.com,2006:td/type" 
    label="documentType"></category> 
    <author> 
      <uri>uid%3Dquikradm%2Co%3Ddefault+organization</uri> 
      <name>quikradm</name> 
      <email></email> 
    </author> 
    <title type="text">word doc</title> 
    <updated>2008-04-23T00:40:42.141Z</updated> 
    <summary type="text">word Document Type</summary> 
    <content type="application/atom+xml" 
    src="library/08ca5f0044ab2d6a858eed71ca20d4cf/documenttype"></content> 
    <td:defaultExtension>doc<td:defaultExtension> 
    <td:template>209c511448682203a123e3bd1a328f82<td:template> 
    <td:propertysheettype>103f553208383112a333b3bd1a319d81 
    <td:propertysheettype>    
    <td:propertysheettype>201d33530848122a333b4cd2a419c914 
    <td:propertysheettype>    <td:propertysheettype> 
    1029c238299d122c332d99f1c491d882<td:propertysheettype> 
    <td:versioning>none<td:versioning> 
    <td:approvalEnabled>true<td:approvalEnabled> 
    <td:approvalType>serial<td:approvalType>    
    <td:approvers>uid%3Dquikradm%2Co%3Ddefault+organization 
    <td:approvers> 
    <td:expandGroupApprovers>false<td:expandGroupApprovers> 
 </entry>

条目中的 <td:propertysheettype> 元素包含该文档类型要使用的属性表类型的 Unique Identifier (UUID)。

除了创建文档类型之外,您还可以通过向文档类型 Feed URL 发送一个 GET 请求来获取文档类型列表。此外,您也可以通过向以下 document-type 条目 URL 发送 GET、PUT 或 DELETE 操作来获取、更新或删除指定的属性表类型:

http://<host>:<port>/dm/atom/library/<libraryId>
/documenttypes/< documenttype-id>/entry

要详细了解 Lotus Quickr REST Document Service 中的文档类型操作,请在 Lotus Quickr wiki 中查看 Documents Services主题。

使用属性表创建和更新文档

在创建了文档类型之后,您可以为定制字段提供值并上传特定类型的文档。此外,您也可以向 Library Feed URL

http://<host>:<port>/dm/atom/library/<libraryId>/feed?doctype=
<documentTypeId>&includePropertySheets=true

或 Folder Feed URL

http://<host>:<port>/dm/atom/library/<libraryId>/folder/
<folderId>feed?doctype=<documentTypeId>&includePropertySheets=true

发送一个 POST 请求,方式是在请求体中提供带有定制字段值的文档 Atom 条目。定制字段值由包含在文档 Atom 条目中的 <snx:field> 元素描述,它们仅在 URL 参数 includePropertySheets 设置为 true 时生效。

URL 参数 doctype 的值被指定为文档的文档类型。表 2 描述了 <snx:field> 元素的属性。

表 2. <snx:field> XML 元素的属性
属性是否必需描述
fid在 clb 名称空间中为该资源属性定义 propertyName。
name该资源属性的 propertysheettype 的标题。
pstId该资源属性的 propertysheettype 的 UUID。
type定义字段类型。支持以下值:
  • date
  • string
  • double
  • boolean
  • long

清单 4 中的示例代码显示了用于创建带有定制字段的文档的 HTTP 请求。注意,请求体是一个表示文档的 Atom 条目,并且包含几个 <snx:field> 元素。

清单 4. 请求创建带有定制字段值的文档
 POST /library/bd03fd75-99c2-46bb-b438-2d151faa7348/ 
 feed?doctype= 4e05cb0044f7e4f1937e932188721110 
 &includePropertySheets=true HTTP/1.1 
 Host: example.com:9080 
 Content-Type: application/atom+xml; charset="utf-8"
 User-Agent: Thingio/1.0 

 <entry xmlns="http://www.w3.org/2005/Atom"> 
	 <category term="document" scheme="tag:ibm.com,2006:td/type" 
	 label="document"></category> 
	 <summary type="text">Test posting an ATOM document with 
	 metadata values</content> 
	 <title type="text">testPostAtomDocument.txt</title> 
	 <author> 
		 <name>mshani</name> 
	 </author> 
 <snx:field 
  name="pst1"
  fid="clb:ps0"
  pstId="CF2432219C73BB73162A79E0A995292402C7"
  type="date" > 
   2008-06-12T04:00:00Z 
 </snx:field> 
 <snx:field 
  name="pst2"
  fid="clb:ps1"
  pstId="F23432219C73BB73162A79E0A9952922520F"
  type="string" > 
    string example text 
 </snx:field> 
 <snx:field 
  name="pst3"
  fid="clb:ps2"
  pstId="DD2232219C73BB73162A79E0A99529242C77"
  type="long" > 
   2302 
 </snx:field> 
 <snx:field 
  name="pst4"
  fid="clb:ps3"
  pstId="DD2112219C73BB73162A79E0A995292513C8"
  type="double" > 
   123.12345 
 </snx:field> 
 <snx:field 
  name="pst5"
  fid="clb:ps4"
  pstId="DD1232219C73BB73162A79E0A99529251D78"
  type="boolean" > 
   true 
 </snx:field> 
 </entry>

您还可以通过向文档条目 URL 发送一个 GET 或 PUT 操作来获取或更新文档的定制字段值:

http://<host>:<port>/dm/atom/library/<libraryId>/document/< document-id>/entry?includePropertySheets=true

在本节中,我们讨论了针对定制字段的 REST 编程模型,该模型包含属性表类型和文档类型的操作,以及带 <snx:field> 元素的文档的创建,其中 <snx:field> 元素表示 Atom 条目中的定制字段值。接下来,我们通过一个样例书店应用程序演示如何操作定制字段。


在样例应用程序中使用定制字段

在我们的现实场景中(一个简单的在线书店应用程序),我们使用文档库来存储关于图书的文档,并使用定制字段来描述图书的各种属性。

然后我们演示如何通过创建属性表类型和文档类型来创建定制字段,如何创建带定制字段的文档,以及如何更新定制字段中的值。

背景知识

我们的在线书店使用 Lotus Quickr 来管理图书信息。我们为书店的每本书创建文档,并且为了完全地描述关于图书的信息,我们使用定制字段来扩展常规文档。

如前所述,我们在 Lotus Quickr 中通过创建属性表类型来描述定制字段。表 3 列出了我们描述一本书时属性表类型包含的属性。

表 3. 属性表类型中的属性
属性名属性类型
CatalogString
ISBNString
PriceDecimal
Publish dateDate(默认值为 1/1/99)
GenreSingle Choice (Fiction/Comic/Biography)

图 5 显示了在 Web UI 中的 Edit Property Sheet 窗口。

图 5. Edit Property Sheet 窗口
Edit Property Sheet window

现在,我们向文档添加定制字段。这些定制字段通过向图书文档添加属性表类型来描述图书。图 6 展示了一个图书文档示例,其中在 Web UI 上添加了定制字段。

图 6. 带有定制字段的图书文档
带有定制字段的图书文档

准备使用演示示例

为了更好地解释该实现,我们在本文的下载部分提供一个演示例子,它是一个纯 Java 程序。要使用样例应用程序,您必须首先:

  1. 在 Lotus Quickr 中使用 Library 模板创建一个库。
  2. 要获取在第一步中创建的库的 UUID,请遵循以下步骤:

    • 在 Web 浏览器中输入该库。
    • 单击页面右侧的 Subscribe to this library;库提要将显示在浏览器中。
    • 注意浏览器导航栏中的 URL;它类似于(位于 “library” 和 “folder” 之间的 ID 正是我们所需的):

      http://<host>:<port>/dm/atom/library/<uuid>/folder/.....

现在您可以使用该程序了。请遵循以下步骤:

  1. 从本文的下载部分提取附件 example.zip,然后在 target\classes 目录中编辑文件 example.properties,将 server.base.url 的值更改为

    http://<host>:<port>/dm/atom/library/<uuid>
  2. 根据您的 Lotus Quickr 服务器设置更改 user.name 和 user.password 的值。
  3. 确保您的系统安装有 Java Development Kit (JDK) 1.5.0 或更新版本,然后下载 Apache Abdera 0.4.0。该样例程序需要使用 Apache Abdera 0.4.0 来构建和解析 Atom XML,并发出 HTTP 操作。
  4. 为了在应用程序中更轻松地使用 Abdera,我们像清单 5 那样设置了 Microsoft® Windows® 环境变量 ABDERA_HOME 和 ABDERA_CLASSPATH。如果在使用 Linux® 或 UNIX®,您需要调用类似的命令来设置环境变量。
清单 5. 设置环境变量 ABDERA_HOME 和 ABDERA_CLASSPATH
 Set ABDERA_HOME=<The folder where Abdera package is unzipped> 
 Set ABDERA_CLASSPATH=%ABDERA_HOME%/abdera-0.4.0-incubating.jar;%ABDERA_HOME%/ 
 lib/axiom-api-1.2.5.jar;%ABDERA_HOME%/lib/axiom-impl-1.2.5.jar;%ABDERA_HOME%/lib/ 
 commons-beanutils-1.7.0.jar;%ABDERA_HOME%/lib/commons-codec-1.3.jar;%ABDERA_HOME%/lib/ 
 commons-collections-3.2.jar;%ABDERA_HOME%/lib/commons-httpclient-3.1-rc1.jar; 
 %ABDERA_HOME%/lib/commons-lang-2.3.jar;%ABDERA_HOME%/lib/commons-logging-1.0.4.jar; 
 %ABDERA_HOME%/lib/ezmorph-1.0.4.jar;%ABDERA_HOME%/lib/ 
 geronimo-activation_1.0.2_spec-1.1.jar;%ABDERA_HOME%/lib/ 
 geronimo-stax-api_1.0_spec-1.0.1.jar;%ABDERA_HOME%/lib/htmlparser-1.0.5.jar; 
 %ABDERA_HOME%/lib/jaxen-1.1.1.jar;%ABDERA_HOME%/lib/jetty-6.1.5.jar; 
 %ABDERA_HOME%/lib/jetty-util-6.1.5.jar;%ABDERA_HOME%/lib/json-lib-2.2.1-jdk15.jar; 
 %ABDERA_HOME%/lib/servlet-api-2.5-6.1.5.jar;%ABDERA_HOME%/lib/stax-api-1.0.1.jar; 
 %ABDERA_HOME%/lib/stax-api.jar;%ABDERA_HOME%/lib/wstx-asl-3.2.1.jar;%ABDERA_HOME%/lib/ 
 xalan-2.7.0.jar;%ABDERA_HOME%/lib/xmlsec-1.3.0.jar;.

运行演示示例

现在,您可以运行样例应用程序了。

应用程序 1
com.ibm.clb.custom.field.example.CreateCustomFields

这个应用程序创建本文的 “背景知识” 部分描述的属性表类型和文档类型。要运行该程序,转到目录 target\classes 并输入以下命令:

java – cp “%ABDERA_CLASSPATH%” com.ibm.clb.custom.field.example.CreateCustomFields

如果一切正常,该应用程序将打印在客户端和 Lotus Quickr 服务器之间传递的请求和响应信息。在该程序退出之后,它保存在 example.properties 文件中创建的属性表类型的 UUID 和文档类型。它们如下所示:

created.pst.id=53791f0040f5e84eba81faa681ef10bf
created.doctype.id=bc6b918040f5e864ba82faa681ef10bf

注意:如果您将样例项目导入到 Eclipse 或其他 Java Integrated Development Environment (IDE) 中,您可能需要手动地从 bin/classes(或构建类所在的位置)将 example.properties 文件同步到 src/(或源代码所在的位置)。

您还可以从 Web 浏览器登录到 Lotus Quickr 服务器,查看已创建的属性表类型和文档类型。

应用程序 2
com.ibm.clb.custom.field.example.CreateDocumentWithCustomFields

这个应用程序创建一个带有您所创建的属性表类型和文档类型的条目文档:

java – cp “%ABDERA_CLASSPATH%”
com.ibm.clb.custom.field.example.CreateDocumentWithCustomFields

注意:在运行该命令之前,您必须确保属性 created.pst.id 和 created.doctype.id 已经位于 example.properties 文件中。

这个应用程序也打印 Lotus Quickr 接收到或发送的消息。打印消息的最后一行显示我们创建的文档的 UUID:

document uuid: ce8f7000411626fdbab3faa681ef10bf

将 UUID 记录下来;将其用作下一个示例应用程序的输入。

应用程序 3
com.ibm.clb.custom.field.example.UpdateDocumentWithCustomFields

这个应用程序以文档的 UUID 为输入更新现有文档的定制字段:

java – cp “%ABDERA_CLASSPATH%”
com.ibm.clb.custom.field.example.UpdateDocumentWithCustomFields
<document-uuid>

在下面几节中,我们详细讨论这些样例应用程序。

创建定制字段

要创建定制字段,必须先创建属性表类型。如前所述,执行该步骤需要将一个表示属性表类型的 Atom 条目发送到属性表类型的 Feed URL。

如 “使用 REST 编程模型管理定制字段” 小节所述,property-sheet-type 条目中的关键元素是条目的内容元素中的 propertySheetTemplate XML。

例如,对于在 “背景知识” 小节提到的属性表类型,propertySheetTemplate XML 类似于清单 6 所示。

清单 6. PropertySheetTemplate XML 文档
 <?xml version="1.0" encoding="UTF-8" ?> 
  <meta:propertySheetTemplate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:clb="http://content.ibm.com/clb/1.0" xmlns: 
  meta="http://metadata.model.xsd.clb.content.ibm.com/1.0"> 
  <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
  maxLength="2048" multiple="false" propertyId="clb:ps1" 
  propertyName="clb:p_a6aa8d78-bc9e-4a35-a243-000aaaa8af12" readonly="false" 
  required="false" searchable="true"> 
    <meta:label label="Catalog" lang="en" /> 
    <meta:style name="ibm:textVariant" value="medium" /> 
  </meta:property> 
    <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
    maxLength="254" multiple="false" propertyId="clb:ps2" 
    propertyName="clb:p_f4179b4b-9c29-45ea-a18b-3e507002015d" readonly="false" 
    required="false" searchable="true"> 
    <meta:label label="ISBN" lang="en" /> 
    <meta:style name="ibm:textVariant" value="medium" /> 
  </meta:property> 
  
  <meta:property xsi:type="meta:ClbPropertyType" dataType="double" 
  multiple="false" propertyId="clb:ps3"
 propertyName="clb:p_73020b22-ea33-4c14-b8dd-68791bdec517" readonly="false" 
 required="false" searchable="true"> 
    <meta:label label="Price" lang="en" /> 
  </meta:property> 

  <meta:property xsi:type="meta:ClbPropertyType" dataType="dateTime" 
  multiple="false" propertyId="clb:ps4" 
  propertyName="clb:p_c5c61619-44d7-4a12-bbba-9c5c7e245958" readonly="false" 
  required="false" searchable="true"> 
    <meta:label label="Publish Date" lang="en" /> 
    <meta:style name="ibm:dateVariant" value="date" /> 
    <meta:defaultValue>1999-01-01T00:00:00Z</meta:defaultValue> 
  </meta:property> 

  <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
  multiple="false" propertyId="clb:ps5" 
  propertyName="clb:p_946e09da-2e11-4bf8-9139-cb49c713bbe4" readonly="false" 
  required="false" searchable="true"> 
    <meta:label label="Genre" lang="en" /> 
    <meta:style name="ibm:selectionType" value="radio" /> 
    <meta:defaultValue>fiction</meta:defaultValue> 
    <meta:option> 
      <meta:value>fiction</meta:value> 
      <meta:label label="Fiction" lang="en" /> 
    </meta:option> 
    <meta:option> 
      <meta:value>comic</meta:value> 
      <meta:label label="Comic" lang="en" /> 
    </meta:option> 
    <meta:option> 
      <meta:value>biography</meta:value> 
      <meta:label label="Biography" lang="en" /> 
    </meta:option> 
  </meta:property> 
 </meta:propertySheetTemplate>

我们需要用 Java 代码准备这样的 XML 文档,并将其输入到 property-sheet-type 条目内容中。为了简单起见,我们的例子通过连接字符串来构造 XML 文档;不过,在现实的项目中,您可能需要使用 Document Object Model (DOM) 或类似的 XML API。

清单 7 显示了用于构建该 XML 文档的代码片段。这些代码均来自我们的例子的源代码中的 com.ibm.clb.custom.field.example.CreateCustomFields 类。

清单 7. 构建 propertySheetTemplate XML 的代码
 // start building propertySheetTemplate 
 StringBuilder pstTpl = new StringBuilder(); 
 // add xml root tag start 
 pstTpl.append("<?xml version=\"1.0\" encoding=\"UTF-8\"?> 
 <meta:propertySheetTemplate xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" 
 xmlns:clb=\"http://content.ibm.com/clb/1.0\" xmlns: 
 meta=\"http://metadata.model.xsd.clb.content.ibm.com/1.0\">"); 
 pstTpl.append(new MetaPropertyElementBuilder().setDataType("string"). 
 setMaxLength("2048").setPropertyId("clb:ps1").setLabelName("Catalog"). 
 setStyleName("ibm:textVariant").setStyleValue("medium").build()); 
 // ...similarly add other properties... 

 // add xml root tag end 
 pstTpl.append("</meta:propertySheetTemplate>");

实用类 MetaPropertyElementBuilder 用于在 XML 代码中构建一个 <meta:property> 元素。在这个类中,将各种属性聚合起来构成一个有效的 <meta:property> 元素。注意,propertyName 属性是通过 java.util.UUID 类随机生成的。

准备好 propertySheetTemplate XML 之后,我们将它放到一个 ATOM 条目中。不过,我们必须先使用 Apache Abdera 来生成 ATOM 条目。请遵循以下步骤:

  1. 生成一个空条目,然后添加 <atom:category> 来声明它代表一个属性表类型:

    Entry entry = abdera.newEntry();
    entry.addCategory("tag:ibm.com,2006:td/type", "propertySheetType",
    "propertySheetType");
  2. 设置属性表类型的标题:

    String pstTitle = "custom-fields-example-" + System.currentTimeMillis();
    entry.setTitle(pstTitle);
  3. 将生成的 propertySheetTemplate XML 设置为条目的内容:

    entry.setContent(pstTpl.toString());

    在这个步骤中,Abdera 通过一些 String 操作来转义 XML 字符。如果您在此时打印条目,打印出来的条目会很奇怪。

  4. 最后,我们准备 HTTP 请求并将其发送到 property-sheet-type 提要 URL:

    RequestOptions opt = new RequestOptions();
    opt.setUseChunked(false);
    opt.setContentType("application/atom+xml");
    ClientResponse response = client.post(loader.getPstFeedUrl(), entry, opt);

如果服务器一切正常(创建了 201 条消息),则调用成功。我们可以从 HTTP POST 调用接收的响应对象读取状态码。我们还可以从该响应获得已创建的属性表类型的条目:

Entry retPstEntry = (Entry) response.getDocument().getRoot();
String retPstId = Utils.getUuidFromEntry(retPstEntry);

在创建了属性表类型之后,我们必须将它添加到文档类型,这样才能在文档中将该属性表类型用作定制字段。通过使用 HTTP POST 调用文档类型的提要 URL 来完成该步骤。

创建这种文档类型很容易:创建一个 Atom 条目并将其作为 <td:propertySheetType> 元素放到返回的属性表类型 UUID 中,如清单 8 所示。

列表 8. 创建文档类型 Atom 条目并设置属性表类型
 entry = abdera.newEntry(); 
 entry.addCategory("tag:ibm.com,2006:td/type", "documentType", "documentType"); 
 String docTypeTitle = "doctype-example-" + System.currentTimeMillis(); 
 entry.setTitle(docTypeTitle); 
 // extension elements for doctype 
 ExtensibleElement el = entry.addExtension("urn:ibm.com/td", "propertySheetType", "td"); 
 el.setText(retPstId);

条目准备好之后,我们需要将它发送到服务器以创建它。

我们现在创建了一个属性表类型和一个包含它的文档类型。我们的定制字段可以使用了。

创建带定制字段的文档

我们已经拥有描述定制字段所需的属性表类型并将其添加到文档类型中,接下来可以创建带定制字段的文档。

让我们通过对库提要 URL 使用 HTTP POST 命令来创建一个文档,并以创建带定制字段的 Atom Entry 为例子。以下步骤中的代码来自 com.ibm.clb.custom.field.example.CreateDocumentWithCustomFields。

  1. 首先构造一个常规的文档条目:

    Entry entry = abdera.newEntry();
    entry.addCategory("tag:ibm.com,2006:td/type", "document", "document");
    entry.setTitle("document-example-" + System.currentTimeMillis());
    entry.setSummary("A test piece of entry.");
  2. 接下来,告诉服务器将文档类型添加到文档。记住,我们可以通过将 documenttype 参数添加到 URL 来完成该步骤,也可以通过将一个元素作为 <td:documenttype> 元素添加到文档条目来完成。在这里我们使用后一种方法:

    ExtensibleElement el = entry.addExtension("urn:ibm.com/td", "documenttype", "td");
    el.setText(loader.getCreatedDoctypeId());

    现在,文档已经带有我们定义的定制字段。

    我们可以通过将一个 <snx:field> 元素添加到文档条目来给每个字段添加值。像例子中的 propertySheetTemplate XML 代码一样,我们通过连接字符串来构建 <snx:field>。需要再次提醒一下,在现实的项目中,需要考虑使用 XML API,比如 DOM。

  3. 首先,我们通过指定其属性 ID 从 propertySheetTemplate XML 找到属性信息:

    ExtensibleElement customFieldEl =
    Utils.findCustomFieldElementByPropertyId(pstTplEl, "clb:ps1");
    其中实用方法 findCustomFieldElementByPropertyId() 通过属性 ID 从 propertySheetTemplate 包含的所有已创建属性中搜索指定属性。
  4. 最后,我们根据要求将属性和 property-sheet-type 信息合并起来构建 <snx:field> 元素(见表 2):

    new SnxFieldBuilder(entry).setFid(customFieldEl.getAttributeValue
    ("propertyName")).setName(pstName).setPstId(pstId).setType
    ("string").setValue("1, prelude\n2, middle\n3, end. " + 
    System.currentTimeMillis()).build();

现在,构建表示带定制字段的文档的 Atom 条目的步骤已经完成。清单 9 显示了完整的文档条目。

列表 9. 带 <snx:field> 的 POSTed 文档条目
 <entry xmlns="http://www.w3.org/2005/Atom" xmlns:td="urn:ibm.com/td" 
 xmlns:snx="http://www.ibm.com/xmlns/prod/sn"> 
  <category term="document" scheme="tag:ibm.com,2006:td/type" 
  label="document" /> 
  <title type="text">document-example-1263702859296</title> 
  <td:documenttype>62a16d0041064cd6ba95faa681ef10bf</td:documenttype> 
  <summary type="text">A test piece of entry.</summary> 
  <snx:field fid="clb:p_a6aa8d78-bc9e-4a35-a243-000aaaa8af12" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="string">1, prelude 
 2, middle 
 3, end. 1263702859359</snx:field> 
  <snx:field fid="clb:p_f4179b4b-9c29-45ea-a18b-3e507002015d" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="string">1-2-3-4</snx:field> 
  <snx:field fid="clb:p_73020b22-ea33-4c14-b8dd-68791bdec517" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="double">12.34</snx:field> 
  <snx:field fid="clb:p_c5c61619-44d7-4a12-bbba-9c5c7e245958" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="date">2010-01-07T20:32:00Z</snx:field> 
  <snx:field fid="clb:p_946e09da-2e11-4bf8-9139-cb49c713bbe4" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="string">comic</snx:field> 
 </entry>

条目已经准备完毕。我们使用类似于发布属性表类型和文档类型的代码将其发送到服务器。如果创建成功,服务器将以 201 条创建消息响应。您可以从响应对象获取已创建的文档条目。

注意:这个例子演示了如何使用 Atom 条目创建文档;不过,使用 Lotus Quickr REST 服务时,我们还可以通过上传文档二进制内容来创建带定制字段的文档。

要完成该工作,首先要上传具有合适的文档类型的文档二进制文件,然后使用 <snx:field> 更新该文档。要了解更多关于如何通过上传二进制内容创建文档的信息,请查看 Lotus Quickr wiki 中的 Documents Services 主题。

http://www-10.lotus.com/ldd/lqwiki.nsf/dx/documents-services

更新带定制字段的文档

更新带定制字段的文档与创建它们非常相似。为此您需要构建一个文档条目,并通过一个 HTTP PUT 命令来将其发送到文档条目 URL,比如:

http://<host>:<port>/dm/atom/library/<lib-id>
/document/<document-id>/entry

现在我们有一个带有定制字段的文档条目,接下来要更新它的字段。您还可以从头构建字段,前提是文档条目中必须包含正确的文档 UUID。

为了获取文档条目,我们对文档条目 URL 使用一个 HTTP GET 命令:

ClientResponse response = client.get(loader.getDocumentEntryUrl(docId));
Entry docEntryWithPropertySheet = (Entry) response.getDocument().getRoot();

和创建文档时一样,我们通过将定制字段作为 <snx:field> 放到文档条目中来更新它们:

ExtensibleElement customFieldEl = 
Utils.findCustomFieldElementByPropertyId(pstTplEl, "clb:ps3");
new SnxFieldBuilder(docEntry).setFid(customFieldEl.getAttributeValue
("propertyName")).setName(pstName).setPstId(pstId).setType
("double").setValue("15.57").build();

在更新文档时仅需在文档 Atom 条目中包含已更新的字段;在上一个代码片段中,我们更新了 Price 字段。

接下来将已更新的条目发送到服务器:

RequestOptions opt = new RequestOptions();
opt.setUseChunked(false);
opt.setContentType("application/atom+xml");
response = client.put(loader.getDocumentEntryUrlWithLockTrue(docId), docEntry, opt);

如果更新成功服务器发出 200 个 OK 响应消息,更新的文档也包含在响应中。


结束语

在本文中,我们介绍了 Lotus Quickr 8.1.1 REST 文档服务中的定制字段支持。讨论了 REST 文档服务中的编程模型,并通过一个简单的书店应用程序演示了如何通过以下步骤使用它:

  • 创建一个包含定制字段的属性表类型
  • 创建一个与属性表类型相关联的文档类型
  • 通过关联文档类型和在 Atom Entry 中指定属性值来创建带定制字段的文档
  • 更新文档的定制字段

根据 REST 文档服务提供的定制字段支持,用户可以开发出能够处理 Lotus Quickr 中的定制字段的应用程序。


下载

描述名字大小
example.zip28KB

参考资料

学习

获得产品和技术

讨论

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Lotus
ArticleID=474277
ArticleTitle=使用 IBM Lotus Quickr 8.1.1 services for WebSphere Portal 中的 REST 文档服务管理定制字段
publish-date=03152010