目次


IBM Lotus Quickr 8.1.1 services for IBM WebSphere PortalにおけるRepresentational State Transfer (REST)文書サービスのカスタム・フィールドのサポート

Comments

前提条件

この文書は、カスタム属性をサポートする既存のコンテンツ・リポジトリーからコンテンツを移行または統合するユーザーに特に役立ちます。この記事を活用するには、以下の知識が必要です。

  • Lotus Quickr services for WebSphere Portal
  • REST サービス
  • Atom 配信フォーマットおよび Atom 出版プロトコル (AtomPub)
  • Java プログラミング
  • Atom プロトコルおよび AtomPub プロトコルの Java 実装である Apache Abdera

Lotus Quickr 8.1.1 におけるカスタム・フィールドのサポートの概要

Lotus Quickr は、オンラインでコンテンツを共有して共同作業を行い、素早く作業できるようにするチーム・コラボレーション・ソフトウェアです。Lotus Quickr の文書ライブラリー・コンポーネントを使用すると、バージョン管理サポート、ワークフロー管理などの拡張機能、および文書にカスタム・フィールドを追加する機能を使用して、コラボレーション環境内のすべてのチーム・ファイルを管理できます。

カスタム・フィールド

通常、主要な文書内容を記述するにはメタデータが必要です。Lotus Quickr の各文書に、標準のメタデータ・フィールドのセットがあります。メタデータの一般的なセットには、ファイル名、作成者、作成時刻、および更新時刻が含まれますが、場合によっては、一般的なメタデータの項目ではファイルのプロパティーを記述するのに十分でないことがあります。

そのため、カスタム・フィールドが導入されました。カスタム・フィールドは、ユーザーが特定の種類の文書を定義して用意できる一連の拡張プロパティーです。また、これらのカスタム・フィールドは、Lotus Quickr のコンテンツを検索する場合にも非常に役立ちます。カスタム・フィールドは、プロパティー・シートで定義し、文書タイプによって文書に関連付けられます。

プロパティー・シート

プロパティー・シートには、ユーザーが特定のビジネス・ニーズに合わせて定義したいくつかのフィールドが含まれています。データ要素のカスタム・フォームを文書に添付することにより、フィールドの種類、オプション、デフォルト値、フィールドの順序などを定義します。

通常、プロパティー・シートは、文書ライブラリー内に定義してローカルで使用しますが、Lotus Quickr 管理者は、Lotus Quickr サーバー上の任意の文書ライブラリーで使用できる共有プロパティー・シートを定義できます。

プロパティー・シートを作成するには、Web ユーザー・インターフェース (UI) でプレースのメイン・ページに移動し、「ライブラリー・エレメントの管理」を展開し、「プロパティー・シート」を選択し、「プロパティー・シートの作成」をクリックします (図 1 を参照)。

図 1. Web UI の「プロパティー・シートの作成」
Create Property Sheet on Web UI
Create Property Sheet on Web UI

プロパティー・シートにフィールドを追加するには、「プロパティー・シートの作成」ウィンドウの右側の「フィールドの追加」をクリックし、フィールド名、オプション値、表示スタイル、デフォルト値などを入力します (図 2 を参照)。

図 2. プロパティー・シートにフィールドを追加
Add fields to the property sheet
Add fields to the property sheet

文書タイプ

プロパティー・シートには、再使用可能なフィールド定義のセットが用意されています。1 つの文書に複数のプロパティー・シートを添付可能で、各文書の使用可能な一連のプロパティー・シートは、その文書の関連する文書タイプによって定義されます。

文書タイプにより、文書の振る舞いを定義する仕組みが提供されます。例えば、文書テンプレート、バージョン管理、ワークフロー定義、カスタム・フィールドなどの仕組みがあります。特定のタイプの文書をアップロードすると、これらのすべての定義済みパラメーターが有効になります。

前述のように、カスタム・フィールドは文書タイプには直接定義しません。代わりに、プロパティー・シートに定義し、文書タイプに追加します。プロパティー・シートと同様に、通常、文書タイプは文書ライブラリー・スコープに定義しますが、Lotus Quickr 管理者はすべての文書ライブラリーに対して文書タイプを定義できます。

すべての文書タイプを管理するには、プレースで Web UI のメイン・ページに移動し、「ライブラリー・エレメントの管理」を展開して、「文書タイプ」を選択します。文書タイプを作成または更新するときに、追加または削除するプロパティー・シートを文書タイプから選択できます。

文書タイプを作成しているときにプロパティー・シートを追加するには、「プロパティー・シート」セクションの「既存のプロパティー・シートの追加」リンクをクリックし、「プロパティー・シートの選択」ウィンドウで、追加するプロパティー・シートを選択します。この例では、「新規プロパティー・シート」を選択します (図 3 を参照)。

図 3. プロパティー・シートを追加して文書タイプを作成
Add property sheet to newly created document type
Add property sheet to newly created document type

文書へのカスタム・フィールドの適用

プレースでプロパティー・シートと文書タイプを作成した後、文書をアップロードまたは作成したり、必要な文書タイプを選択したりできます。次に、プロパティー・シートに定義したプロパティーを入力する必要があります。入力した値が文書のメタデータになります。

文書タイプを選択し、プロパティー・シートに定義されたフィールドを入力するには、次の手順を実行します。

  1. プレースのメイン・ページで「アップロード」を選択し、「ファイルのアップロード」ウィンドウで「文書タイプ」セクションの「変更」リンクをクリックします (図 4 を参照)。
  2. 「文書タイプの選択」ウィンドウで、使用する文書タイプを選択します (ここでは、「新規文書タイプ」を選択します)。

ページ下部の新しい「文書タイプ・プロパティー」セクションに文書タイプのプロパティーが表示されます。

図 4. プロパティー・シートの文書タイプとフィールドを選択
Choose document type and fields in property sheet
Choose document type and fields in property sheet

Lotus Quickr 公開サービスでのカスタム・フィールドのサポート

Lotus Quickr には、Lotus Quickr によって管理されているコンテンツにアクセスするための一連の公開サービス (API) も用意されています。これらのサービスを使用すると、カスタマイズされたアプリケーションを作成したり、Lotus Quickr のコンテンツを他のアプリケーションと統合したりできます。

Lotus Quickr 公開サービスの主要な構成要素の 1 つに REST 文書サービスがあります。このサービスでは、次の Atom 出版プロトコル (RFC 5023) に準拠し、Atom 配信フォーマット (RFC 4287) を実装した RESTful プログラミング・モデルを使用して、Lotus Quickr 文書ライブラリー内の多くの情報にプログラムでアクセスして更新できます。

Lotus Quickr 8.0 以降、REST 文書サービスには Lotus Quickr 文書ライブラリーで文書を作成、取得、更新、および削除する機能が用意されていますが、2008 年 12 月に Lotus Quickr 8.1.1 がリリースされるまでは、カスタマイズされたフィールドはサポートされませんでした。

この記事の次のセクションでは、REST 文書サービスでカスタム・フィールドを管理するプログラミング・モデルについて説明し、プログラム例を使用して、実際のアプリケーションでこのサービスを使用する方法を示します。

REST プログラミング・モデルを使用したカスタム・フィールドの管理

注:この記事の前のセクションでは、カスタム・フィールドの定義と、文書に実装されるカスタム・フィールドの両方について説明する際に「プロパティー・シート」という用語を使用しました。一方、REST プログラミング・モデルでは、「プロパティー・シート・タイプ」という用語を使用して、カスタム・フィールドの定義を説明します。文書にプロパティー・シート・タイプが実装されると、プロパティー・シート・タイプのカスタム・フィールドの値は「プロパティー・シート」と呼ばれます。この記事の残りの部分では、REST プログラミング・モデルのこの新しい用語を使用します。

プロパティー・シート・タイプの作成

ライブラリーにプロパティー・シート・タイプを作成するには、HTTP 要求の本文にプロパティー・シート・タイプの 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 エントリーには、カスタム・フィールドを定義できるプロパティー・シート・テンプレート XML 定義を格納する <content> 要素が含まれています。

<propertySheetTemplate> 要素には、システムの個々のカスタム・フィールドを定義する 0 個以上の <property> 要素を格納できます。

それぞれの要素に、1 つの <propertySheetTemplate> 内で一意のプロパティー識別子を定義する propertyId 属性を格納する必要があります。

このほかにも、サポートされる他の属性がいくつかあります。表 1 に、<property> 要素でサポートされるすべての属性を示します。

表 1. <property>要素でサポートされる属性
属性説明
datatype

この必須の属性には、メタデータ・プロパティーの基本データ型を指定する一連の列挙されたオプションのストリングを設定します。基本データ型により、このメタデータ値が保持される ClbPropertySheet で使用できる動的マップが決まります。次の基本データ型の値がサポートされます。

  • String
  • Double
  • Long
  • dateTime
  • Boolean

デフォルトでは、PropertySheetType XML テンプレートに値が指定されていない場合、データ型は String になります。

multipleこの任意指定の属性には、プロパティーが複数の値をサポートするかどうかを指定する Boolean 値を設定します。デフォルト値は false です。
indexableこの任意指定の属性には、プロパティーを索引に追加する必要があるかどうかを指定する Boolean 値を設定します。デフォルト値は false です。
propertyId

この必須のストリング属性には、プロパティー・シート・テンプレート内の個々のプロパティーの ID を設定します。

propertyName

この必須のストリング属性には、バックエンド・リポジトリーのプロパティーの修飾名が格納されます。この名前は、プレフィックス clb: で定義し、1 つのリポジトリー内で一意である必要があります。これは、このプロパティー値が格納されたデータ型の動的なマップのキーです。

readonly

この任意指定の属性には、コンテンツ・リポジトリーのこのプロパティーが読み取り専用の値かどうかを指定する Boolean 値を設定します。デフォルト値は false です。

required

この任意指定の属性には、コンテンツ・リポジトリーのこのプロパティーが必須の値かどうかを指定する Boolean 値を設定します。デフォルト値は false です。

searchable

この任意指定の属性には、このプロパティーがテキスト検索をサポートするかどうかを指定する Boolean 値を設定します。デフォルト値は 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 要求を送信して、プロパティー・シート・タイプのリストを取得することもできます。また、次に示すようなプロパティー・シート・タイプ・エントリー URL への GET、PUT、または DELETE 操作の送信により、特定のプロパティー・シート・タイプを取得、更新、または削除できます。

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

Lotus Quickr REST 文書サービスのプロパティー・シート・タイプ操作について詳しくは、Lotus Quickr wiki の文書サービスに関するトピックを参照してください。

文書タイプの作成

ライブラリーに文書タイプを作成するには、HTTP 要求の本文に文書タイプ Atom エントリーを指定して、文書タイプのフィード URL

http://<ホスト>:<ポート>/dm/atom/library/<ライブラリー Id>/documenttypes/feed に POST 要求を送信します (リスト 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> 要素には、この文書タイプに使用するプロパティー・シート・タイプの汎用固有 ID (UUID) を設定します。

文書タイプの作成に加え、文書タイプのフィード URL に GET 要求を送信して、文書タイプのリストを取得することもできます。また、次に示すような文書タイプ・エントリー URL への GET、PUT、または DELETE 操作の送信により、特定の文書タイプを取得、更新、または削除できます。

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

Lotus Quickr REST 文書サービスの文書タイプ操作について詳しくは、Lotus Quickr wiki の文書サービスに関するトピックを参照してください。

プロパティー・シートを使用した文書の作成および更新

文書タイプを作成した後、特定の文書タイプの文書をアップロードしているときに、カスタム・フィールドの値を設定できます。また、要求本文のカスタム・フィールド値に文書 Atom エントリーを指定して、ライブラリー・フィード URL

http://<host>:<port>/dm/atom/library/<libraryId>/feed?doctype=
<documentTypeId>&includePropertySheets=true
or the Folder Feed URL

http://<host>:<port>/dm/atom/library/<libraryId>/folder/
<folderId>feed?doctype=<documentTypeId>&includePropertySheets=true
に POST 要求を送信することもできます。カスタム・フィールド値は、文書 Atom エントリーに含まれる <snx:field> 要素で記述します。カスタム・フィールド値は、URL パラメーター includePropertySheets が true に設定されている場合にのみ有効になります。

URL パラメーター doctype の値は、文書の文書タイプとして指定されます。<snx:field> 要素の属性を表 2 に示します。

表 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 プログラミング・モデルについて説明しました。プロパティー・シート・タイプと文書タイプの操作、Atom エントリーのカスタム・フィールド値を表す <snx:field> 要素のある文書を作成する操作などについて説明しました。次に、サンプルの書店アプリケーションのカスタム・フィールドを操作するいくつかのコードについて説明します。

サンプル・アプリケーションでのカスタム・フィールドの使用

このシナリオでは、単純なオンライン書店アプリケーションで文書ライブラリーを使用して書籍に関する文書を保存し、カスタム・フィールドを使用して書籍のさまざまなプロパティーを記述します。

続いて、プロパティー・シート・タイプと文書タイプを作成してカスタム・フィールドを作成する方法、カスタム・フィールドを持つ文書を作成する方法、およびカスタム・フィールドの値を更新する方法について説明します。

背景

このオンライン書店では、Lotus Quickr を使用して書籍情報を管理しています。在庫しているすべての書籍の文書を作成し、書籍情報を完全に記述するために、通常の文書を拡張するカスタム・フィールドを使用します。

前に説明したように、Lotus Quickr では、プロパティー・シート・タイプを作成してカスタム・フィールドを記述します。書籍を記述するプロパティー・シート・タイプのプロパティーを表 3 に示します。

表 3. プロパティー・シート・タイプのプロパティー
プロパティー名プロパティー・タイプ
Catalogストリング
ISBNストリング
Price10 進数
Publish date

日付 (デフォルト値は 1999/1/1)

Genre1 つを選択 (Fiction/Comic/Biography)

図 5 に、Web UI の「プロパティー・シートの編集」ウィンドウを示します。

図 5.「プロパティー・シートの編集」ウィンドウ
Edit Property Sheet window
Edit Property Sheet window

次に、プロパティー・シート・タイプを書籍文書に添付して、書籍を記述するカスタム・フィールドを文書に追加します。図 6 に、カスタム・フィールドを追加した、Web UI の書籍文書の例を示します。

図 6. カスタム・フィールドのある書籍文書
Book document with custom fields
Book document with custom fields

デモンストレーション・サンプル使用の準備

実装方法を詳細に説明するために、この記事の「ダウンロード」セクションにデモンストレーション・サンプル (Java プログラム) を用意しました。サンプル・プログラムを使用するには、まず、次の操作を行います。

  1. Lotus Quickr でライブラリー・テンプレートを使用してプレースを作成します。
  2. 手順 1 で作成したライブラリーの UUID を取得します。次の手順を実行します。
    • Web ブラウザーにライブラリーを入力します。
    • ページの右側にある「このライブラリーをサブスクライブする」をクリックします。ブラウザーにライブラリー・フィードが表示されます。
    • ブラウザーのナビゲーション・バーに URL が表示されます。この URL は次のようになります (「library」と「folder」の間の ID が目的の 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 をダウンロードします。このサンプルで Atom XML を作成して解析し、HTTP 操作を発行するには、Apache Abdera 0.4.0 が必要です。
  4. 次のアプリケーションで Abdera を簡単に使用できるように、Microsoft® Windows® 環境変数 ABDERA_HOME と ABDERA_CLASSPATH をリスト 5 に示すように設定します。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 が保存されます。この UUID は次のようになります。

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

注: サンプル・プロジェクトを Eclipse または別の Java 統合開発環境 (IDE) にインポートする場合、bin/classes (または作成されたクラスの格納場所) から src/ (またはソース・コードの格納場所) に、ファイル example.properties を手動で同期しなければならないことがあります。

また、Web ブラウザーから Lotus Quickr サーバーにログインし、作成されたプロパティー・シート・タイプと文書タイプをチェックできます。

アプリケーション 2
com.ibm.clb.custom.field.example.CreateDocumentWithCustomFields

このアプリケーションは、作成したプロパティー・シート・タイプと文書タイプを使用してエントリー文書を作成します。

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

注: このコマンドを実行する前に、example.properties ファイルにプロパティー created.pst.id と created.doctype.id が既にあることを確認してください。

また、このアプリケーションは Lotus Quickr サーバーが送受信したメッセージを出力します。出力されたメッセージの最後の行は、作成した文書の UUID を示します。

document uuid: ce8f7000411626fdbab3faa681ef10bf

UUID を書き留めます。この UUID は次のサンプル・アプリケーションの入力として使用します。

アプリケーション 3
com.ibm.clb.custom.field.example.UpdateDocumentWithCustomFields

このアプリケーションは、文書の UUID を入力として使用して、既存の文書のカスタム・フィールドを更新します。

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

次のセクションでは、これらのサンプル・アプリケーションのプログラミングの詳細について説明します。

カスタム・フィールドの作成

カスタム・フィールドを作成するには、まず、プロパティー・シート・タイプを作成する必要があります。前に説明したように、この手順を実行するには、プロパティー・シート・タイプを表す Atom エントリーをプロパティー・シート・タイプのフィード URL に POST する必要があります。

『REST プログラミング・モデルを使用したカスタム・フィールドの管理』セクションで説明したように、プロパティー・シート・タイプ・エントリーの重要な要素は、エントリーのコンテンツ要素の 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>

このような XML 文書を Java コードで準備し、これをプロパティー・シート・タイプのエントリー・コンテンツに入力する必要があります。簡潔にするために、このサンプルではストリングを連結してこの XML 文書を作成しますが、実際のプロジェクトでは、Document Object Model (DOM) または同様の XML API の使用が必要になる場合があります。

XML 文書の作成に使用するコード・スニペットをリスト 7 に示します。このコード全体は、サンプルのソース・コードのクラス 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());

    この手順では、XML 文字をエスケープするために、Abdera でストリング操作を行います。この時点でエントリーを出力しても、正常に表示されません。

  4. 最後に、HTTP 要求を準備して、プロパティー・シート・タイプのフィード URL に POST します。

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

サーバーですべてが正常に処理されると呼び出しが成功し、応答 "201 Created" を受信します。HTTP POST 呼び出しから受信した応答オブジェクトで状況コードを参照できます。また、作成されたプロパティー・シート・タイプのエントリーを応答から取得できます。

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

プロパティー・シート・タイプを作成した後、そのプロパティー・シート・タイプを文書のカスタム・フィールドとして使用できるように、文書タイプに追加する必要があります。この手順は、文書タイプのフィード URL に対する HTTP POST 呼び出しを使用して実行します。

このような文書タイプは簡単に作成できます。リスト 8 に示すように、Atom エントリーを作成し、返されたプロパティー・シート・タイプ UUID を <td:propertySheetType> 要素として設定します。

リスト 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);

これでエントリーを準備できました。次に、そのエントリーをサーバーに POST して作成する必要があります。

作成したエントリーにはプロパティー・シート・タイプと文書タイプが含まれています。これで、カスタム・フィールドを使用できます。

カスタム・フィールドのある文書の作成

既に、カスタム・フィールドを記述するプロパティー・シート・タイプを作成して文書タイプに追加してあるので、カスタム・フィールドを使用して文書を作成できます。

ここでは、例として、ライブラリーのフィード URL に対して HTTP POST コマンドを使用して文書を作成し、カスタム・フィールドのある Atom エントリーを作成します。次の手順のコードは、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> を作成します。この場合も、実際のプロジェクトでは DOM などの XML API の使用を検討します。

  3. 最初に、次のようにプロパティー ID を指定して、propertySheetTemplate XML からプロパティー情報を検索します。

    ExtensibleElement customFieldEl =
    Utils.findCustomFieldElementByPropertyId(pstTplEl, "clb:ps1");
    ここで、ユーティリティー・メソッド findCustomFieldElementByPropertyId() は、propertySheetTemplate で作成されたすべてのプロパティーについて、プロパティー ID でプロパティーを検索します。
  4. 最後に、必要に応じてプロパティーとプロパティー・シート・タイプ情報の両方を設定して <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. POST された<snx:field>要素のある文書エントリー
<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>

文書エントリーを取得するために、文書エントリー 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 フィールドを更新しました。

次に、この更新されたエントリーをサーバーにPUT します。

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 エントリーにプロパティー値を指定して、カスタム・フィールドのある文書を作成する。
  • 文書のカスタム・フィールドを更新する。

REST 文書サービスに用意されているカスタム・フィールドのサポートに基づき、カスタム・フィールドを操作できる独自のアプリケーションを Lotus Quickr で開発できます。


ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Lotus
ArticleID=497485
ArticleTitle=IBM Lotus Quickr 8.1.1 services for IBM WebSphere PortalにおけるRepresentational State Transfer (REST)文書サービスのカスタム・フィールドのサポート
publish-date=06252010