Meenakshi Guruaribam Khanna, 资深软件工程师, IBM

Divya Satyavarapu, 助理系统工程师, IBM

Anil R Patlolla, 资深软件工程师, IBM

Anand Bandaru, 资深软件工程师, IBM

简介： 在第 4 部分，您将学习如何使用一个通用 REST 处理程序从 iWidget 调用 REST 服务。

我们为本系列开发的定制小部件是基于 WebSphere V7.0 支持的 Business Space（以下简称 Business Space）中附带的 Dojo 版本，已经在 Mozilla Firefox 3.0.11 中测试过了。只是，我们开发的通用框架概念甚至可以应用到使用 Dojo 的应用程序中，但却不能用于 Business Space。学习本系列需要具备 DOJO 和 iWidget 框架的基本知识。

我们将讨论在基于 Dojo 的应用程序中经常遇到的主题。本系列分为以下几部分：

第 1 部分：使用通用的 markup 处理程序生成 DOJO markup
第 2 部分：使用通用的网格处理程序创建具有分页功能的 Dojo DataGrid 组件
第 3 部分：在 iWidget 中使用多个模板和从基本小部件继承
第 4 部分：使用通用 REST 处理程序从 iWidget 发出可配置的 REST 调用

在第 4 部分，您将学习如何使用一个通用 REST 处理程序从 iWidget 调用一个 REST 服务，该 REST 处理程序基于以下原理设计：

REST URI 通常是动态的，且在调用 REST 服务之前 URI（URL 参数）的一部分将被 iWidget 动态替换。我们的设计根据相应的 REST 关键字从 JSON 文件读取 REST URI。
查询参数是动态替代的。
REST 处理程序目前支持 JSON，但是根据需要很容易增强，支持 XML 和其他类型。
REST 处理程序支持 GET、POST/RAWPOST、PUT、RAWPUT 和 DELETE 操作，也支持文件上传和下载操作。

在本文中，我们将介绍 REST 处理程序的实现以及在您的 iWidget 中如何使用它。

以下文件在 Part4SampleCode.zip 中提供下载：

JSONRestHandler.js：通用 REST 处理程序 Javascript. 类。
restURI.json：包含 REST URI 的 JSON 文件。
testJSONRestHandler.js：Javascript. 类，展示如何在您的代码中使用 JSONRestHandler。

处理程序的实现

JSONRestHandler Javascript. 类加载 loadRESTConfig( ) 方法中含有 REST URI 信息的 JSON 文件。

loadRESTConfig() 方法接受以下参数：

type：操作类型，如 GET/POST/PUT，等等。
restCallKey：JSON 文件中的 keyName，例如 EmployeeList。
restEndPoint：运行 REST 应用程序的 REST 端点；例如 http://:/restAPI。
loadMethod：此方法在 REST URI 成功加载时调用。
errorMethod：如果调用 REST URI 出现错误，该方法被调用。
syncFlag：REST 调用应该是同步或异步（true 或 false）。
thisVar：调用类的引用。
parameters：含有 3 个变量（urlParameters、queryParameters、content）。如果 URI 有 URL 或查询参数，该对象需要用相应的值进行设置。
只有在 POST 请求时内容才被发送。

清单 1. loadRESTConfig( ) 方法，加载 JSON 文件

loadRESTConfig: function(type,restCallKey,restEndPoint,loadMethod,errorMethod,syncFlag,
parameters,thisVar)
	{

		var normalUrl = thisVar.rootContext+ "com/ibm/bcgex/common/restJson/"
+this.fileName; 
				var request = {
				url:normalUrl,
				sync:true,
				handleAs: "json",
				load: dojo.hitch(this, function(data)
{ this._callREST(data,type,restCallKey,restEndPoint,loadMethod,errorMethod,syncFlag,
parameters,thisVar); }),
				error: dojo.hitch(this, "_restConfigError")
				};	
		dojo.xhrGet (request);
	}

loadRESTConfig 方法调用 _callREST 方法成功加载 JSON 文件。

_callREST 方法遍历 JSON 文件中的条目。当条目名称和关键名（页面名）相匹配时，它通过连接 restEndPoint（http://: part）和来自 JSON 文件的 URI 来构造 REST URL。它还检查是否有与特定 REST 调用相关的 URL 参数和查询参数，并构造相关 URL。

对于一个 POST 请求，它从 parameters 对象读取并设置内容。这些操作完成之后，相应的 XHR 调用被执行。

清单 2. _ callREST ( ) 方法遍历 JSON 文件并构造最终 REST URI

   _callREST:function(response,type,restCallKey,restEndPoint,loadMethod,errorMethod,
syncFlag,parameters,thisVar)
	{

		var FUNCTIONNAME = "callREST()";   
		
		var itemsArray = eval(response).items;
		var _restURL = "";
		var urlParameters = "";
		var queryParameters = "";
		var contentParameter = "";
		for (var i = 0; i < itemsArray.length; i++)
		{
			var item = itemsArray[i];
			var entityName=item.name;
			if(entityName==this.functionName)
			{
				var childrenArray = item.children;
				for(var j=0;j< childrenArray.length;j++)
				{
					var child  = childrenArray[j];
					var childName=child.name;
					  if(childName==restCallKey){
						_restURL = child.restURL;
						requestTimeout = child.timeout;
						break;
					  }
				}
			}

		}

				
		if(_restURL=="")
		{
			console.debug("Error: Unable to retrieve the REST URL");
		} else {
		
			if(parameters!=null)
			{
				urlParameters=parameters.urlParameters;
				queryParameters=parameters.queryParameters;
				contentParameter=parameters.content;
			
				if(urlParameters!=null)
				{
					for(var i=0;i0)
						{
							queryString=queryString+"&";
						}
						key = queryParameters.getKey(i);
						queryString=queryString+key+"=
"+encodeURIComponent(queryParameters.item(key));					}
					
					_restURL=_restURL+queryString;
				}
			}
		
			
			console.debug("URL="+restEndPoint+_restURL);
			var request = {
				url: restEndPoint+_restURL,
				handleAs:"json",
				sync: syncFlag,
				preventCache: true,
				mimetype: 'text/json;charset=utf-8',
				load: dojo.hitch(thisVar, loadMethod),
				error: dojo.hitch(thisVar, errorMethod)
			};

			request.headers={};
			if (type == 'GET')
			{
				request.headers["Accept"] = "application/json";
				dojo.xhrGet(request);		 
			} else if (type == "POST" || type == "RAWPOST") {
				request.postData =  contentParameter;
				request.headers["Content-Type"] = 
"application/json; charset=utf-8";
				dojo.rawXhrPost(request);
			} else if (type == "PUT" || type == "RAWPUT") {
					request.putData =  contentParameter;
					request.headers["Content-Type"] = 
"application/json; charset=utf-8";
					dojo.rawXhrPut(request);
			}else if(type == "DELETE"){
				dojo.xhrDelete(request);
			}
		}
	}

REST 处理程序使用 dojo.io.iframe.send API 进行文件的上传和下载。

清单 3. 文件上传和下载

if (type == "FILEPOST") {
	console.debug("restEndPoint+_restURL"+restEndPoint+_restURL);
	//file upload
	var request = {
			url: restEndPoint+_restURL,
			form.:contentParameter,
			preventCache:true,
			timeout: requestTimeout,
			sync: true,
			handleAs:"html",
			load: dojo.hitch(thisVar, loadMethod),
			error: dojo.hitch(thisVar, errorMethod)
		};
		var iframeSend = dojo.io.iframe.send(request);
	}
	else if (type == "FILEGET") {
				// file download
		var request = {
			url: restEndPoint+_restURL,
			preventCache:true,
			timeout: requestTimeout,
			sync: true,
			method:"GET",
			handleAs:"xml",
			load: dojo.hitch(thisVar, loadMethod),
			error: dojo.hitch(thisVar, errorMethod)
		};
		var iframeSend = dojo.io.iframe.send(request);
}

从您的客户端代码调用 REST 处理程序

在这一节，我们将逐步讲解从您的代码中调用 REST 处理程序 Javascript. 类。

第 1 步：在 JSON 文件中定义 REST URI。

所有 REST URI 被定义在一个 JSON 文件中（例如，restURI.json）。在某个特定页面中的 REST 调用归属于 items 标签之下的一个特定主键（名称）。

例如，有一个名为 EmployeeList 的页面，其中有两个 REST 调用 —— 一个用于检索员工列表（fetchEmployeeList），另一个用于检索员工信息（empDetails），单击员工姓名即可检索。REST URI 在 JSON 文件 restURI.json 中定义，如下所示：

清单 4. 来自 restURI.json 的片段

name:'EmployeeList',	
children:[
	{
	name:'fetchEmployeeList',
	restURL:'/employee/list'
	},
	{
	name:'empDetails',
	restURL:'/employee/'
	}

			
]

根据某一个员工 id 检索该员工的详细信息的 REST URI 示例如下：

http://:/restApi/employee/

在上述 URI 中，在调用 REST 服务之前，REST 处理程序使用实际 ID 动态替换 URI 参数。REST 处理程序也确保 REST 端点被附加到 URI（JSON 文件中定义的）之前做前缀；例如 /employee/。

第 2 步：在 JSONRestHandler.js 中使用 JSON 文件名和页面（关键）名调用 setRestHandlerParams() 方法

清单 5. 调用 setRestHandlerParams() 方法

com.ibm.bcgex.common.JSONRestHandler.getInstance().setRestHandlerParams 
("restURI.json","EmployeeList");

第 3 步：实例化参数对象

下一步是实例化参数对象，该对象包含：

URL 参数
查询参数
内容（如果是 POST 请求）或文件上传调用

清单 6. 实例化参数对象和设置 URL 参数

var parameters = new Object();
parameters.content = null;
this.empId=”111202”;
this.urlParamsList = new dojox.collections.SortedList();
this.urlParamsList.add("",this.empId);
parameters.urlParameters=this.urlParamsList;

一些 REST 调用可能需要查询参数，清单 7 展示了如何在 parameters 对象中设置查询参数。

清单 7. 在参数对象中设置名为 dept 的查询参数

this.queryParamsList = new dojox.collections.SortedList();
this.queryParamsList.add("dept",”HR”);
parameters.queryParameters=this.queryParamsList;

如果是 POST 请求，内容也需要在 parameters 对象中设置。对于一个员工创建调用，内容将被设置为如清单 8 所示。

清单 8. 对于 POST 请求将内容放在参数对象中

var content = 	{"name" : “Tom”,
	       	"gender" : “M”,
               	"fullName":”Tom”,
               	"department":”Payroll”,
               	"location:”:”IBM”
              	};	
//serialize the content into JSON
postDataContent = serialize (content);
parameters.content = postDataContent;

当参数对象实例化完成之后，您就准备好了调用 REST 服务。

第 4 步：通过 loadRESTConfig() 方法调用 REST 服务。

为了调用一个典型的 GET 调用，调用 loadRESTConfig() 方法，如清单 9 所示。

清单 9. GET 调用 REST 处理程序

this.restURL  = getRestURLEndpoint();	

com.ibm.bcgex.common.JSONRestHandler.getInstance().loadRESTConfig
("GET","fetchEmployeeList",this.restURL,"_loadEmpList","_onError",true,parameters,this);

为了调用一个典型的 POST 调用，调用 loadRESTConfig() 方法，如清单 10 所示。

清单 10. POST 调用 REST 处理程序

 this.restURL  = getRestURLEndpoint();	
this._jsonRestHandler = new com.ibm.bcgex.common.JSONRestHandler
("restURI.json","EmployeeCreate");

com.ibm.bcgex.common.JSONRestHandler.getInstance().loadRESTConfig 
("POST"," createEmployee",this.restURL,"_saveEmployeeDetails","_onError",
true,parameters,this);

结束语

通过本文，您学习了如何使用 JSON 文件中指定的 REST URI 发出 REST 调用。该方法的优势是不需要对代码做任何改变，即使 URI 发生变化。另外，REST 处理程序还能处理 URI 中的 URL 和查询参数。无论是 GET、POST、PUT 还是 DELETE，所有这些操作都可以使用 REST 处理程序优雅地处理。

原文链接：http://www.ibm.com/developerworks/cn/websphere/library/techarticles/1007_khanna2/1007_khanna2.html

使用 Dojo 开发定制 Business Space 小部件，第 4 部分