本文将详细介绍如何开发一个可迁移、可动态读写的小组件，并通过它来利用 IBM InfoSphere Business Glossary REST API 以及各种 Web 2.0 技术。这个小组件允许用户查找术语、查看团队的详细信息，以及执行基本的编辑操作。
我们的目标是让用户能够在构建示例小组件的过程中掌握必要的知识，以便能够使用 REST API 创建自己的自定义应用程序。本文面向熟悉各种 Web 2.0 技术的软件工程师，以及能够将此处提供的工具应用于现实场景的产品设计人员。
前提条件
本文面向掌握基本 Web 编程技术（HTML、JavaScript、Ajax、XML、XSLT）并具备使用 Dojo JavaScript 工具包开发小组件的经验的开发人员。要部署示例小组件，您需要具备基本的管理技能，以及在 IBM WebSphere Application Server 上部署 Web 应用程序 WAR 所需的权限。Business Glossary REST API 是 IBM InfoSphere 产品支持的一个部分。本文开发的其他客户端组件基于常用的 Web 编程技术，但它们并不是 IBM 产品的一部分，因此并未得到官方支持。
概述
借助 IBM InfoSphere Business Glossary，您可以创建、管理和共享一个企业词汇和分类系统。Business Glossary 通过一个使用 REST (Representational State Transfer) 服务的 API 公开了丰富的功能。REST 是用于设计 Web 服务的一种开放架构样式，它允许掌握基本 Web 2.0 技术的开发人员快速构建各种应用程序。
本文将详细介绍如何构建一个可以嵌入到任何 Web 页面中的基于 REST 的组件。我们将这个示例组件称作 BGTerm Finder 小组件。它是一款轻量级的工具，支持快速搜索和修改企业的业务词汇。
下面两个示例业务场景演示了如何使用该组件：
主题专家 Tom 正在查阅公司的业务词汇表，并惊讶地发现术语 Actual Net Present Value 的定义并不准确。他立即使用 BGTerm Finder 小组件找到术语并通过实时编辑来纠正其定义。
销售执行官 Lorraine 在阅读一份业务智能报表时遇到了 Actual Net Present Value 这个短语。她需要理解这个术语在自己公司中的准确定义。她使用 BGTerm Finder 小组件查找该术语并理解其上下文和定义。
图 1 显示了 BGTerm Finder 小组件的两个屏幕快照。在第一个屏幕快照中，用户搜索字符串 "act" 并打开了术语 Actual Net Present Value 的详细视图。第二个屏幕快照中展示了用户单击图标对术语进行编辑的操作。
图 1. BGTermFinder Widget 屏幕快照
图片看不清楚？请点击这里查看原图（大图）。
REST API
Business Glossary REST API 允许客户机应用程序访问和创建业务词汇表内容。选择 REST 技术来实现 API 的原因是它提供了一些其他分布式技术所无法比拟的优势。最重要的是，它是轻量型且支持互操作的。
API 将词汇表内容公开为资源。这些资源将通过 URI 来标识，并通过服务器上的 XML 模式定义的 XML 文档来表示。
API 资源
Business Glossary REST API 可以接收的资源主要分为两个数据集：
实体资源集（Entity Resource Set） — 此资源集包含关于 Business Glossary 实体的详细信息，比如说类别、术语、stewards、自定义属性和一些额外的资源。所有这些实体都由 Read API 及其创建、更新和删除功能提供支持。有关更多信息，请参阅 REST API 文档。
操作资源集（Operational Resource Set） — 此资源集为开发客户机应用程序提供易于使用、通用的操作，比如说：
自动完成。为前缀提供来自词汇表的完成建议（支持通配符）。
随处搜索。其搜索方法与 IBM InfoSphere Business Glossary Anywhere 所采用的搜索方法类似（不支持通配符）。
搜索。此操作支持搜索特定模式的词汇。用户可以控制搜索到的特性和类，并对结果进行排序（支持通配符）。
API 事务
API 事务由一个 HTTP 请求和响应组成。不同的操作需要请求使用不同种类的 HTTP 方法。URI 和 HTTP 方法共同定义将要发生的操作。REST 接口提供了以下 HTTP 方法：
POST — 用于创建资源
GET — 用于读取资源
PUT — 用于更新资源
DELETE — 用于删除资源
小组件设计
示例 BGTerm Finder 小组件使用 Web 应用程序的模式-视图-控制器（Model-View-Controller，MVC）体系结构。各层次及其相关技术的概述如下：
模型（XML） — 使用定义良好的 API XML 资源来表示数据模型。
视图（HTML+CSS） — 小组件的 HTML 用于提供结构，而 CSS 负责处理样式。
控制器（JavaScript）— 小组件的 JavaScript 代码用于完成以下任务：
处理用户事件
使用 AJAX 将资源传递（或从中获取）给 REST API
使用 XSL 转换将 XML 资源转换成 HTML 片段
将这些片段注入 DOM
处理用户界面
图 2. 小组件设计
模型（XML）
小组件模型是 REST API 返回的 XML 资源。这些资源是由 REST API 以及服务器上的 XML 模式定义的 XML 文档。示例小组件将使用 searchResource 和 termResource 资源。
清单 1. 搜索资源模型 XML<?xml version="1.0" encoding="UTF-8"?>
<searchResource xmlns="http://www.ibm.com/is/bg/rest"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/is/bg/rest
http://bghost:9080/bgrestapi/xsd/searchResource.xsd">
<searchInput>
<pattern>sa*</pattern>
<queriedClasses>
<value>term</value>
</queriedClasses>
<queriedFeatures>
<value>name</value>
</queriedFeatures>
<status>
<value>ACCEPTED</value>
<value>STANDARD</value>
<value>CANDIDATE</value>
<value>DEPRECATED</value>
</status>
<stopAfterFirstFieldMatch>false</stopAfterFirstFieldMatch>
</searchInput>
<results>
<searchResultItem>
<glossaryObject class="term">
<name>Satisfaction Rating Date</name>
<uri>bgrestapi/term/b1c497ce.e1b1ec6c.232160ba.?
06b1b806-d928-48d3.b91b.222f3e221b7c</uri>
<context>
<category>
<name>Customer</name>
<uri>bgrestapi/category/b1c497ce.?
ee6a64fe.f1020ba.46e95446-d922-42ba.9ae4.2440d424e432</uri>
</category>
</context>
</glossaryObject>
<foundInFields>
<field name="name" value="Satisfaction Rating Date"/>
</foundInFields>
<rank>1</rank>
</searchResultItem>
</results>
<pagination>
<pageNumber>1</pageNumber>
<pageSize>10</pageSize>
<numberOfPages>1</numberOfPages>
<numberOfResults>1</numberOfResults>
</pagination>
</searchResource>
清单 2. 术语资源模型 XML <?xml version="1.0" encoding="UTF-8"?>
<termResource xmlns="http://www.ibm.com/is/bg/rest" .?
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ?
xsi:schemaLocation="http://www.ibm.com/is/bg/rest .?
http://bghost:9080/bgrestapi/xsd/termResource.xsd">
<term>
<name>Satisfaction Rating Date</name>
<uri>bgrestapi/term/b1c497ce.e1b1ec6c.232160ba.?
06b1b806-d928-48d3.b91b.222f3e221b7c</uri>
<context>
<category>
<name>Customer</name>
<uri>bgrestapi/category/b1c497ce.ee6a64fe.f1020ba.?
46e95446-d922-42ba.9ae4.2440d424e432</uri>
</category>
</context>
<authorization>RWD</authorization>
<createdBy>
<uri>bgrestapi/user/bob</uri>
<id>builder</id>
</createdBy>
<createdOn>2009-05-04 04:01:59 PDT</createdOn>
<modifiedBy>
<uri>bgrestapi/user/bgauthor</uri>
<id>bgauthor</id>
</modifiedBy>
<modifiedOn>2009-07-08 07:28:42 PDT</modifiedOn>
<assignedTerms/>
<shortDescription>The date on which the modern Satisfaction Rating was .?
assigned to the Customer.</shortDescription>
<longDescription>The date on which the Satisfaction Rating was assigned.?
to the Customer.</longDescription>
<notes/>
<customAttributes/>
<steward class="user">
<name>Jeff Blight Jeff Blight</name>
<uri>bgrestapi/user/Jeff+B</uri>
<id>Jeff B</id>
</steward>
<parentCategory>
<name>Customer</name>
<uri>bgrestapi/category/b1c497ce.ee6a64fe.f1020ba.?
46e95446-d922-42ba.9ae4.2440d424e432</uri>
</parentCategory>
<status>STANDARD</status>
<abbreviation/>
<additionalAbbreviation/>
<example/>
<usage/>
<isModifier>false</isModifier>
<type>NONE</type>
<replacedByTerm/>
<referencedByCategories/>
<relatedTerms/>
<replacedTerms/>
<synonyms/>
<isPreferredSynonymInGroup>false</isPreferredSynonymInGroup>
<preferredSynonym/>
<assignedAssets/>
</term>
</termResource>
视图（HTML+CSS）
上一节描述的 XML 模式将被转换为 HTML 片段，并注入到小组件 DOM 中。
由于我们开发的是一个可以嵌入到任何 Web 页面中的小组件，因此我们希望保存浏览器资源并避免与所包含的文档发生冲突。以下示例演示了如何通过 HTML 和 CSS 代码来实现此目的：
利用 Dojo 附加点和附加事件（而不是 ID）来简化片段注入
使用唯一的带特定前缀的 CSS 类名
使用 Dojo JavaScript 工具包最大限度减少 HTML 资源占用
清单 3. 小组件 HTML 模板<div class="bgTermFinderWidget_main"
dojoAttachEvent="onclick : clickHandler">
<h1>InfoSphere <a dojoAttachPoint="bg_link" href="#"
target="_blank" title="Go To Business Glossary Browser">Business
Glossary</a> : Term Finder <img class="bgTermFinderWidget_logo"
src="${imagesPath}/ibm_logo_white.gif" /></h1>
<div class="bgTermFinderWidget_ds">
<div class="bgTermFinderWidget_search">
<div class="bgTermFinderWidget_tempText" dojoAttachPoint="tempText"
dojoAttachEvent="onclick: trySetFocus">Start typing to search...</div>
<input type="text" dojoAttachPoint="searchinput"
dojoAttachEvent="onblur:stopTimer,onfocus:startTimer" value="" /> <img
class="bgTermFinderWidget_searchloader" dojoAttachPoint="searchloader"
src="${imagesPath}/loading.gif" style="display: none" /></div>
<div class="bgTermFinderWidget_resultsPanel">
<div class="bgTermFinderWidget_infoHolder" dojoAttachPoint="infoHolder">
<span class="bgTermFinderWidget_info" dojoAttachPoint="info"></span></div>
<div class="bgTermFinderWidget_searchResults"
dojoAttachPoint="searchResults">
<div class="bgTermFinderWidget_showmore" /></div>
</div>
</div>
<div class="bgTermFinderWidget_itemloaderholder"
dojoAttachPoint="itemloaderholder"><img
class="bgTermFinderWidget_itemloader" dojoAttachPoint="itemloader"
src="${imagesPath}/loading_strip_static2.gif"
onclick="window.location.reload()"
title="Status Indicator | Click to reload widget" /></div>
</div>
</div>
SearchResults
SearchResults div 是小组件 HTML 结构中的主要 div。这个 div 负责显示术语以响应用户的输入。
接收的结果将使用 SearchResult Model XML 格式，并被转换为 HTML 片段，然后附加到 SearchResults div。
HTML 搜索结构片段是由 Business Glossary 所使用的相同 Repository ID (RID) 唯一标识的 div 标记。当用户请求时，控制器将使用此 RID 获取完整的术语资源。还需要使用一个额外的自定义 HTML 属性来标识资源的 steward。
清单 4. 搜索结果 HTML<div dojoattachpoint="searchResults"
class="bgTermFinderWidget_searchResults">
<div class="page">
<div class="node"
rid="bgrestapi/term/b1c497ce.e1b1ec6c.232160ba.06b1b806-d928-48d3.b91b.222f3e221b7c">
<div class="title-closed"><a class="doOpen" href="#">Satisfaction
Rating Date</a><a class="doEdit" href="#"
title="Click to edit Description and Steward">Edit</a></div>
</div>
<div class="node"
rid="bgrestapi/term/b1c497ce.e1b1ec6c.1e1aa0bd.a73f37a7-59c2-42bf.aac9.c05e0ac0c965">
<div class="title-closed"><a class="doOpen" href="#">Source Of
Income Type Identifier</a><a class="doEdit" href="#"
title="Click to edit Description and Steward">Edit</a></div>
</div>
<div class="node"
rid="bgrestapi/term/b1c497ce.e1b1ec6c.16dda0ba.5e5d685e-aa69-4925.afd0.e2d33ce2d0bf">
<div class="title-closed"><a class="doOpen" href="#">Special
Terms Flag</a><a class="doEdit" href="#"
title="Click to edit Description and Steward">Edit</a></div>
</div>
</div>
<div class="bgTermFinderWidget_showmore" /></div>
结果节点
结果节点可以具有以下状态之一：
关闭
打开供查看
打开供编辑
各状态都有不同的表示，并由 CSS 进行控制。以下三个图提供了各状态的示例。
图 6. 关闭 — 仅显示术语名
图 7. 打开供查看 — 显示术语详细信息和编辑图标
图 8. 打开供编辑 – 在编辑模式下显示术语详细信息和 steward，同时提供编辑控制
控制器（小组件 JavaScript 代码）
小组件的核心内容是控制器。控制器由 JavaScript 代码组成，可通过调用 REST API 来响应用户操作。然后，通过使用 DOM 操作，控制器将经过转换的 HTML 片段注入到小组件模板中。
DOM 操作和气泡技巧
为了理解控制器所执行的 DOM 操作的逻辑，本节将深入探究 Open Node 场景。Edit Node 场景使用类似的逻辑。
图 9. 序列流 — 打开节点
图片看不清楚？请点击这里查看原图（大图）。
当用户单击某个关闭的节点时，浏览器会将目标节点的 onClick 事件（通过气泡）传递给小组件控制器代码的主 onClick 处理程序。主处理程序将使用 RID 标识目标节点并调用适当的处理程序方法。
事件气泡技巧可用于断开小组件的视图结构与控制器代码之间的连接。此技巧还遵循将所有 onClick 处理集中于一处的 single choice 原则。
清单 5. 单击处理程序函数clickHandler : function(evt) {
var targetNode = evt.target;
var className = dojo.attr(targetNode,"class");
if ( className == "doOpen") {
var div = targetNode.parentNode.parentNode;
this.OnItemClick( div );
}
else if ( className == "doEdit") {
var div = targetNode.parentNode.parentNode;
this.OnItemEditClick( div );
}
else if ( className == "editOK"){
var div = targetNode.parentNode.parentNode.parentNode;
this.OnEditOk (div);
}
else if ( className == "editCancel"){
var div = targetNode.parentNode.parentNode.parentNode;
this.OnEditOk (div);
}
else if ( className == "doShowMore" ) {
this.OnPageClick( dojo.attr( targetNode,"page") );
}
},
//Method is called when user clicked to open/close the node
OnItemClick:function( div){
this._currRID = dojo.attr(div,"rid");
var nodesClosedTitle = dojo.query('.title-closed' , div);
var nodesClosedBody = dojo.query('.body-closed' , div);
//Node is closed and never been open
if ( nodesClosedTitle.length > 0 && nodesClosedBody.length == 0){
//Performing Ajax call to term details
this.RequestItemDetails( this._currRID );
}
//Node is closed and was opened before
else if ( nodesClosedTitle.length > 0 && nodesClosedBody.length > 0){
nodesClosedTitle[0].className = "title-open";
nodesClosedBody[0].className = "body-open";
}
//Node is open
else{
var nodesOpenTitle = dojo.query('.title-open' , div);
var nodesOpenBody = dojo.query('.body-open' , div);
if ( nodesOpenTitle.length > 0 && nodesOpenBody.length > 0){
nodesOpenTitle[0].className = "title-closed";
nodesOpenBody[0].className = "body-closed";
}
}
},
如清单 6 所示，如果节点从未打开过，则控制器将通过调用 RestClient.requestItemDetails 来异步请求术语。
清单 6. RequestItemDetails 函数//Performing AJAX Request to term details
RequestItemDetails:function( rid ){
this.toggleItemLoading(1);
this._bgRestClient.requestItemDetails
( rid,this,this.itemDetailsCallback , this.onError );
},
在清单 7 所示的代码中，控制器的回调方法首先使用 XSLProcessor 模块生成 HTML 片段，然后将其注入到目标节点中。
清单 7. itemDetailsEditCallback 函数//Method will be called when AJAX request to term details returns .
itemDetailsEditCallback :function( xml ) {
//Extracting the rid of the term with XPath
var rid = this.extractStringValue ?
( xml ,"//rest:termResource/rest:term/rest:uri" );
var div = dojo.query('div[rid=\"'+ rid +'\"]' , this.searchResults )[0];
//Processing XML of term details to create HTML edit fragment to be injected.?
var element = this._bgXslProcessor.processItemDetailsEdit( xml );
//Switching display
dojo.query('.doEditBussy' , div)[0].className = "doEdit";
dojo.query('.title-open' ,div )[0].className = "title-edit";
//Injecting the HTML fragment
dojo.place( element , dojo.query('.body-open' ,div )[0] , "replace");
dojo.place( this._selectTag ,dojo.query('.stewardValue' ,div )[0],"only" );
this.toggleItemLoading(0);
},
REST 客户机模块
小组件将使用一个 Dojo JavaScript 类（BGRestClient）来执行针对特定资源的异步 REST 调用。
清单 8 显示了两个主要的帮助器函数，它们用于执行 AJAX GET 和 PUT 异步调用。
清单 8. REST 客户机代码片段 //Performing AJAX Get Request
__performRequest: function( url , callbackMethod , errorMethod ) {
if ( this._xhr != null ) {
this._xhr.cancel();
}
this._xhr = dojo.xhrGet( { //
// The following URL must match that used to test the server.
url: url,
handleAs: "xml",
timeout: this._timeout, // Time in milliseconds
// The LOAD function will be called on a successful response.
load: callbackMethod,
// The ERROR function will be called in an error case.
error: errorMethod
});
},
//Performing AJAX Put Request
__performPutRequest: function ( url , data , callbackMethod , errorMethod ) {
return dojo.rawXhrPut( { //
// The following URL must match that used to test the server.
url: url,
handleAs: "xml",
putData : data ,
timeout: this._timeout, // Time in milliseconds
// The LOAD function will be called on a successful response.
load: callbackMethod,
// The ERROR function will be called in an error case.
error: errorMethod
});
},
查看包含在 bgTermFinderWidget.war 中的 BGRestClient.js 文件，了解 JavaScript REST 客户机的实现。
XSLProcessor Module
XSLProcessor 充当将从 API 接收到的 XML 资源转换为 HTML 片段的跨浏览器包装器。
主 XSLProcessor 转换函数将使用浏览器的 XSL 转换引擎来处理 XML。
清单 9. XSLProcessor 代码片段__transform:function( xml , xsl ,paramsNames,paramsValues) {
var element = null;
if (dojo.isIE)
{
var template = new ActiveXObject("MSXML2.XSLTemplate");
template.stylesheet = xsl;
var processor = template.createProcessor();
processor.input = xml;
if (paramsNames != null ) {
for( i = 0 ;i < paramsNames.length ; i++){
processor.addParameter(paramsNames[i],paramsValues[i]);
}
}
processor.transform();
element = processor.output;
}
else if (dojo.isFF || dojo.isChrome)
{
xsltProcessor=new XSLTProcessor();
xsltProcessor.importStylesheet(xsl);
var i = 0;
if ( paramsNames != null ) {
for( i = 0 ;i < paramsNames.length ; i++){
xsltProcessor.setParameter(null,paramsNames[i]?
,paramsValues[i] );
}
}
//Performing the transformation of a fragment of xml
element = xsltProcessor.transformToFragment( xml , document)
}
return element;
}
Internet Explorer XSL 处理器
Internet Explorer 使用 Microsoft.XMLDOM.transformNode 方法通过指定的 XSL 文档来处理 XML 节点及其子节点。该方法将转换后的节点以纯文本的形式返回。
Firefox XSL 处理器
Firefox 执行转换的方法是创建一个 XSLTProcessor 实例、导入 XSL 文档，并使用 xsltProcessor.transformToFragment 方法来完成转换过程。返回的结果是一个 DOMNode。
XSL
如前所述，本文假定您已经熟悉 XSLT 开发。但是，请注意 Business Glossary REST API XML 资源都使用下面这个指定的 XML 名称空间来声明：
http://www.ibm.com/is/bg/rest
在开发 XSLT 时必须考虑这个名称空间。清单 10 显示了一个例子。.
清单 10. REST API 名称空间<xsl:stylesheet version="1.0"xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:rest="http://www.ibm.com/is/bg/rest" >
清单 11 展示了如何使用声明的 rest 前缀。
清单 11. 使用声明的 “rest” 前缀<div class="description">
<xsl:value-of select="rest:termResource/rest:term/rest:shortDescription"/>
</div>
小组件使用的所有 XSL 文件都包含在 js/bg/resources/xsl 目录下的 bgTermFinderWidget.war 文件中。
部署
使用以下步骤部署小组件：
找到 下载 小节并保存 bgTermFinderWidget.war 文件。
使用 WebSphere Application Server Web Administrative Console 部署 WAR 文件。您必须将它部署到 Business Glossary REST API 所在的主机上，或者部署到一台子域主机上。由于所有主要浏览器都实现了同源策略（same origin policy），因此必须遵循这种部署规则。该策略将防止从一个站点源加载的脚本对另一个不同源的站点执行 AJAX 调用。
找到部署的 WAR 并修改 Main.html 文件中的 RestAPIHost 属性，使之匹配您主机的名称。
要使用小组件，打开浏览器并访问：
http://<host>:<port>/bgTermFinderWidget
小组件支持以下浏览器：
Internet Explorer 版本 6、7 和 8
Firefox 版本 2 和 3
Google Chrome
集成
下面是一些集成在第三方环境中的 BGTerm Finder 小组件示例。
图 10. Lotus Mashup 集成
图片看不清楚？请点击这里查看原图（大图）。
如上所示，我们可以使用 iWidget 标准将示例小组件连接到 Lotus Mashup 框架中的另一个小组件。
图 11. iGoogle
图片看不清楚？请点击这里查看原图（大图）。
图 12. Netvibes
图片看不清楚？请点击这里查看原图（大图）。
结束语
IBM InfoSphere Business Glossary 8.1.1 REST API 为您提供了前所未有的强大功能，允许您通过自定义应用程序将词汇表内容向用户公开。我们希望本文提供的示例能帮助您和您的组织开始通过 REST API 来利用 InfoSphere Business Glossary 的强大功能。
下载
| 描述 | 名字 | 大小 | 下载方法 |
| BGTermFinderWidget 代码示例 | bgTermFinderWidget.war | 9.73MB | HTTP |