您的位置:首页 > 理论基础 > 计算机网络

作者:Don Box 简单对象访问协议(SOAP)初级指南

2001-10-25 17:20 405 查看
元素内(后面会更多讨论这两个元素)。下面是一个最简单的SOAP方法请求:
POST /string_server/Object17 HTTP/1.1
Host: 209.110.197.2
Content-Type: text/xml
Content-Length: 152
SOAPMethodName: urn:strings-com:IString#reverse
Hello, World
SOAPMethodName头必须与下的第一个子元素相匹配,否则调用将被拒绝。这允许防火墙管理员在不解析XML的情况下有效地过滤对一个具体方法的调用。
SOAP响应的格式类似于请求格式。响应体包含方法的[out]和 [in,out]参数,这个方法被编码为一个显著的响应元素的子元素。这个元素的名字与请求的调用元素的名字相同,但以Response后缀来连接。下面是对前面的SOAP请求的SOAP响应:
200 OK
Content-Type: text/xml
Content-Length: 162
dlroW ,olleH
这里响应元素被命名为reverseResponse,它是方法名紧跟Response后缀。要注意的是这里是没有SOAPMethodName HTTP头的。这个头只在请求消息中需要,在响应消息中并不需要。
图6和图7表明SOAP是怎样与以前讨论的ORPC协议相互对应的。让许多SOAP新手困惑的是SOAP中没有关于SOAP服务器怎样使用请求头来分发请求的要求;这被留为一个实现上的细节。一些SOAP服务器将映射请求-URIs到类名,并分派调用到静态方法或到在请求持续期内存活的类的实例。其它SOAP服务器则将请求-URIs映射到始终存活的对象,经常是用查询字符串来编码一个用来定位在服务器进程中的对象关键字。还有一些其它的SOAP服务器用HTTP cookies来编码一个对象关键字,这个关键字可被用来在每次方法请求中恢复对象的状态。重要的是客户对这些区别并不知道。客户软件只是简单遵循HTTP和XML的规则来形成SOAP请求,让服务器自由以它认为最合适的方式来为请求服务。
SOAP体的核心
SOAP的XML特性是为把数据类型的实例序列化成XML的编码模式。为了达到这个目的,SOAP不要求使用传统的RPC风格的代理。而是一个SOAP方法调用包含至少两个数据类型:请求和响应。考虑这下面个COM IDL代码:
[ uuid(DEADF00D-BEAD-BEAD-BEAD-BAABAABAABAA) ]
interface IBank : IUnknown {
HRESULT withdraw([in] long account,
[out] float *newBalance,
[in, out] float *amount
[out, retval] VARIANT_BOOL *overdrawn);
}
在任何RPC协议下,account和amount参数的值将出现在请求消息中,newBalance,overdrawn参数的值,还有amount参数的更新值将出现在响应消息中。
SOAP把方法请求和方法响应提升到了一流状态。在SOAP中,请求和响应实际上类型的实例。为了理解一个方法比如IBank::withdraw怎样映射一个SOAP请求和响应类型,考虑下列的数据类型:
struct withdraw {
long account;
float amount;
};
 
这是一个所有的请求参数被打包成为一个单一的数据类型。同样下面的数据表示打包所有响应参数到一个单一的数据类型。
struct withdrawResponse {
float newBalance;
float amount;
VARIANT_BOOL overdrawn;
};
再给出下面的简单的Visual Basic程序,它使用了以前定义的Ibank接口:
Dim bank as IBank
Dim amount as Single
Dim newBal as Single
Dim overdrawn as Boolean
amount = 100
Set bank = GetObject("soap:http://bofsoap.com/am")
overdrawn = bank.withdraw(3512, amount, newBal)
你能够想象底层的代理(可能是一个SOAP,DCOM,或IIOP代理)看上去象图8中所表示的那样。这里,在发送请求消息之前,参数被序列化成为一个请求对象。同样被响应消息接收到的响应对象被反序列化为参数。一个类似的转变同样发生在调用的服务器端。
当通过SOAP调用方法时,请求对象和响应对象被序列化成一种已知的格式。每个SOAP体是一个XML文档,它具有一个显著的称为的根元素。标记名由SOAP URI (urn:schemas-xmlsoap-org:soap.v1)来划定范围,所有SOAP专用的元素和属性都是由这个URI来划定范围的。SOAP Envelope包含一个可选的元素,紧跟一个必须的元素。元素也有一个显著的根元素,它或者是一个请求对象或者是一个响应对象。下面是一个IBank::withdraw请求的编码:
3512100

 
下列响应消息被编码为:
05true

注意[in, out]参数出现在两个消息中。
 
在检查了请求和响应对象的格式后,你可能已经注意到序列化格式通常是:
;
field1valuefield2value
在请求的情况下,类型是隐式的C风格的结构,它由对应方法中的[in]和[in, out]参数组成。对响应来说,类型也是隐式的C风格的结构,它由对应方法中的[out]和[in, out]参数组成。这种每个域对应一个子元素的风格有时被称为元素正规格式(ENF)。一般情况下,SOAP只用XML特性来传达描述包含在元素内容中信息的注释。
象DCOM和IIOP一样,SOAP支持协议头扩展。SOAP用可选的元素来传载被协议扩展所使用的信息。如果客户端的SOAP软件包含要发送头信息,原始的请求将可能如图9所示。在这种情况下命名causality的头将与请求一起序列化。收到请求后,服务器端软件能查看头的名域URI,并处理它识别出的头扩展。这个头扩展被http://comstuff.com URI识别,并期待一个如下的对象:
struct causality {
UUID id;
};
在这种情况下的请求,如果头元素的URI不能被识别,头元素可以被安全地忽略。
但你不能安全的忽略所有的SOAP体中的头元素。如果一个特定的SOAP头对正确处理消息是很关键的,这个头元素能被用SOAP属性mustUnderstand=’true’标记为必须的。这个属性告诉接收者头元素必须被识别并被处理以确保正确的使用。为了强迫前面causality头成为一个必须的头,消息将被写成如下形式:
362099cc-aa46-bae2-5110-99aac9823bff
SOAP软件遇到不能识别必须的头元素情况时,必须拒绝这个消息并出示一个错误。如果服务器在一个SOAP请求中发现一个不能识别的必须的头元素,它必须返回一个错误响应并且不发送任何调用到目标对象。如果客户端在一个SOAP请求中发现一个不能识别出的必须的头元素,它必须向调用者返回一个运行时错误。(在COM情况下,这将映射为一个明显的HRESULT)
SOAP数据类型
在SOAP消息中,每个元素可能是一个SOAP结构元素,一个根元素,一个存取元素或一个独立的元素。在SOAP中,soap:Envelope, soap:Body和 soap:Header 是唯一的三个结构元素。它们的基本关系由下列XML Schema所描述:

在SOAP元素的四种类型中,除了结构元素外都被用作表达类型的实例或对一个类型实例的引用。
根元素是显著的元素,它是soap:Body 或是 soap:Header的直接的子元素。其中soap: Body只有一个根元素,它表达调用、响应或错误对象。这个根元素必须是soap:Body的第一个子元素,它的标记名和域名URI必须与HTTP SOAPMethodName头或在错误消息情况下的soap:Fault相对应。而soap:Header元素有多个根元素,与消息相联系的每个头扩展对应一个。这些根元素必须是soap:Header的直接子元素,它们的标记名和名域URI表示当前存在扩展数据的类型。
存取元素被用作表达类型的域、属性或数据成员。一个给定类型的域在它的SOAP表达将只有一个存取元素。存取元素的标记名对应于类型的域名。考虑
4000
下列Java 类定义:
package com.bofsoap.IBank;
public class adjustment {
public int account ;
public float amount ;
}
在一个SOAP消息中被序列化的实例如下所示:
3514100.0
在这个例子中,存取元素account和amount被称着简单存取元素,因为它们访问对应于在W3C XML Schema规范 (见 http://www.w3.org/TR/XMLSchema-2) 的Part 2中定义的原始数据类型的值。这个规范指定了字符串,数值,日期等数据类型的名字和表达方式以及使用一个新的模式定义中的结构来定义新的原始类型的机制。
对引用简单类型的存取元素,元素值被简单地编码为直接在存取元素下的字符数据,如上所示。对引用组合类型的存取元素(就是那些自身用子存取元素来构造的存取元素),有两个技术来对存取元素进行编码。最简单的方法是把被结构化的值直接嵌入在存取元素下。考虑下面的Java类定义:
package com.bofsoap.IBank;
public class transfer {
public adjustment from;
public adjustment to;
}
如果用嵌入值编码存取元素,在SOAP中一个序列化的transfer对象如下所示:
3514-100.03518100.0
在这种情况下,adjustment对象的值被直接编码在它们的存取元素下。
在考虑组合存取元素时,需要说明几个问题。先考虑上面的transfer类。类的from和to的域是对象引用,它可能为空。SOAP用XML Schemas的null属性来表示空值或引用。下面例子表示一个序列化的transfer对象,它的from域是空的:
3518100.0
在不存在的情况下, xsd:null属性的隐含值是false。给定元素的能否为空的属性是由XML Schema定义来控制的。例如下列XML Schema将只允许from存取元素为空:

/>

在一个元素的Schema声明中如果没有nullable属性,就意味着在一个XML文档中的元素是不能为空的。Null存取元素的精确格式当前还在修订中要了解用更多信息参考最新版本的SOAP规范。
与存取元素相关的另一个问题是由于类型关系引起的可代换性。由于前面的adjustment类不是一个final类型的类,transfer对象的from和to域实际引用继承类型的实例是可能的。为了支持这种类型兼容的替换,SOAP使用一个名域限定的类型属性的XML Schema约定。这种类型属性的值是一个对元素具体的类型的限制的名字。考虑下面的adjustment扩展类:
package com.bofsoap.IBank;
public class auditedadjustment extends adjustment {
public int auditlevel;
}
给出下面Java语言:
transfer xfer = new transfer();
xfer.from = new auditedadjustment();
xfer.from.account = 3514; xfer.from.amount = -100;
xfer.from.auditlevel = 3;
xfer.to = new adjustment();
xfer.to.account = 3518; xfer.from.amount = 100;
在SOAP中transfer对象的序列化形式如下所示:
3514-100.033518100.0
在这里xsd:type属性引用一个名域限定的类型名,它能被反序列化程序用于实例化对象的正确类型。因为to存取元素引用到一个被预料的类型的实例(而不是一个可代替的继承类型),xsd:type属性是不需要的。
刚才的transfer类设法回避了一个关键问题。如果正被序列化的transfer对象用下面这种方式初始化将会发生什么情况:
transfer xfer = new transfer();
xfer.from = new adjustment();
xfer.from.account = 3514; xfer.from.amount = -100;
xfer.to = xfer.from;
基于以前的议论,在SOAP 中transfer对象的序列化形式如下所示:
3514-100.03514-100.0
这个表达有两个问题。首先最容易理解的问题是同样的信息被发送了两次,这导致了一个比实际所需要消息的更大的消息。一个更微妙的但是更重要的问题是由于反序列化程序不能分辨两个带有同样值的adjustment对象与在两个地方被引用的一个单一的adjustment对象的区别,两个存取元素间的身份关系就被丢失。如果这个消息接收者已经在结果对象上执行了下面的测试,(xfer.to == xfer.from)将不会返回true。
void processTransfer(transfer xfer) {
if (xfer.to == xfer.from)
handleDoubleAdjustment(xfer.to);
else
handleAdjustments(xfer.to, xfer.from);
}
(xfer.to.equals(xfer.from))可能返回true的事实只是比较了两个存取元素的值而不是它们身份。
为了支持必须保持身份关系的类型的序列化,SOAP支持多引用存取元素。目前我们接触到的存取元素是单引用存取元素,也就是说,元素值是嵌入在存取元素下面的,而且其它存取元素被允许引用那个值(这很类似于在NDR中的[unique]的概念)。多引用存取元素总是被编码为只包含已知的soap:href属性的空元素。soap:href属性总是包含一个代码片段标识符,它对应于存取元素引用到的实例。如果to和from存取元素已经被编码为多引用存取元素,序列化的transfer对象如下所示:

这个编码假设与adjustment类兼容的一个类型的实例已经在envelope中的其它地方被序列化,而且这个实例已经被用soap:id属性标记,如下所示:
3514-100.0
对多引用存取元素,把代码段的标识符(例如#id1)分解到正确的实例是反序列化程序的工作。
前面的讨论解释了多引用存取元素怎样与它的目标实例相关联。下面要讨论的是目标实例在哪里被序列化。这就关系到独立元素和包的概念。
独立元素
在SOAP中,一个独立元素表示至少被一个多引用存取元素引用的类型的实例。所有的独立元素用soap:id属性作标记,而且这个属性的值在整个SOAP envelope中必须是唯一的。独立的元素被编码就好象是它们被一个存取元素打包,这个存取元素的标记名是实例的名域限制的类型名。在上面的例子中,实例的名域限制的类型名是t:adjustment。
SOAP限制独立元素能被编码的场所。SOAP定义了一个能适用于任何元素的属性:(soap:Package)。这个属性被用于控制独立元素能在哪里被解码。SOAP序列化规则指出独立元素必须编码为soap:Header元素或soap:Body元素的直接子元素,或者是任何其它标记为soap:Package=‘true’的元素。通过把一个元素注释为包,你能保证编码那个实例的XML元素是完全自包含的,并且在这个包以外没有任何引用到这个元素的多引用存取元素。
假设transfer 类对应于一个方法请求。如果transfer类型不是一个包,被to和from存取元素引用的独立元素将作为soap:Body元素的直接子元素出现,如图10所示。如果transfer类型是一个合法的SOAP包类型,编码可能象图11所示。注意,因为transfer元素是一个包,所有多引用存取器元素都引用被包含的元素。这使得把transfer元素看成一个能从它的父辈元素中分离出的独立的XML代码段变得更为容易。
多引用存取元素总是引用独立元素的模型是有一个例外的。SOAP允许包含字符串和二进值数据的存取元素是多引用存取元素的目标。这意味着下面的代码是合法的:
Hello, SOAP
尽管事实是存取元素2有一个soap:id属性,它实际上是一个存取元素而不是独立元素。
SOAP数组
数组被编码为组合类型的一个特殊的例子。在SOAP中,一个数组必须有一个秩(维数)和一个容量。一个数组被编码为一个组合类型,其中每一个数组元素被编码为一个子元素,这个子元素的名字是元素的名域限制的类型名。
假设有下面的COM IDL类型定义:
struct POINTLIST {
long cElems;
[size_is(cElems)] POINT points[];
};
 
这个类型的实例将被序列化为:
3347519
如果points域被标记为[ptr]属性,这个编码将用一个多引用存取元素,如下所示:
 
3347519
当把一个数组编码为一个独立元素时,标记名是带前缀ArrayOf的类型名。
象NDR和CDR一样,SOAP支持部分转换的数组。如果子元素的数量少于所声明的容量,这些元素被假设正从数组的末尾丢失。这能够通过在正包含的数组元素上使用soap:offset属性来被忽略。
19
soap:offset属性表示出现在数组中的第一个元素的索引。在上面的例子中,元素0,2到4都是不被转换的。SOAP也支持稀疏数组,这是通过使用soap:position属性来把每个元素用它的绝对索引来注释而实现的:
3445
在这个例子中,元素0到2,4到6,以及8到9都不是被转换的。
请注意,在SOAP中数组的精确语法在这篇文章写作时还在被重新审查以调整到即将推出的W3C XML Schema规范中。要不断了解SOAP规范的最新版本来获得更多的细节。
错误处理
一个服务器有时将不能正确地为一个方法请求提供服务。这可能是由于一般的HTTP错误造成的(如请求-URI不能被映射到本地的资源或一个HTTP级的安全违反)。也可能是在SOAP翻译软件中的问题,如马歇尔打包错误或一个必须的头不能被认出。其它可能的原因包括一个请求不能正确地被服务,或者应用/对象代码决定要返回一个应用级的错误给调用者。这些情况在SOAP规范中都被清楚地加以处理。
如果在分发对任何SOAP代码的调用之前一个错误发生在HTTP层,一个纯HTTP响应必须被返回。标准的HTTP状态代码编号将被采用,400级的代码表示一个客户引发的错误,500级的代码表示服务器引发的错误。这通常在代码执行前由Web服务器软件自动处理。
假设在HTTP层一切正常,错误发生的下一个地方是在那些翻译和分发对应用代码(如COM对象和CORBA伺服对象)的SOAP调用。如果错误发生在这一层,服务器必须返回一个错误消息来代替一个标准的响应消息。一个错误消息是下列被编码为soap:Body的根元素的类型的实例。

 

faultcode存取元素必须包含一个用已知的整数表示的SOAP错误代码或者一个专门应用的名域限制的值。当前的SOAP 错误代码如图12所示。Faultstring存取元素包含对发生的错误的可读性的描述。runcode 存取元素包含一个字符串,它的值必须是Yes, No或 Maybe,表明被请求的操作实际上是否在错误产生之前被执行。Detail存取元素是可选的,用于包含一个专门应用的异常对象。
下面是一个对应于一个包含无法识别的必须的头元素的请求的SOAP错误的例子:
;
200
Unrecognized 'causality' header
No

假设具体应用的错误需要被返回,你可能看到如图13所示的代码。在应用定义的错误的情况下,考虑应用的异常/错误对象时detail存取元素起到了soap:Body 元素的作用。
奥秘
一个遗留的HTTP问题还需要进一步阐明。SOAP支持(但不需要)HTTP扩展框架约定来指定必须的HTTP头扩展。这些约定主要有两个目的。首先,它们允许任意的URI被用于限定给定的HTTP头的范围(象XML名域一样)。第二,这些约定允许把必须的头与可选的头区分开来(象soap:mustUnderstand)。下面是一个使用HTTP扩展框架来把SOAPMethodName头定义成为一个必须的头扩展:
M-POST /foobar HTTP/1.1
Host: 209.110.197.2
Man: "urn:schemas-xmlsoap-org:soap.v1; ns=42"
42-SOAPMethodName: urn:bobnsid:IFoo#DoIt
Man头映射SOAP URI到前缀为42的头,并表示没有认出SOAP的服务器必须返回一个HTTP错误,状态代码为501 (没有被实现) 或 510 (没有被扩展)。HTTP方法必须是M-POST,表明目前是必须的头扩展。
结论
SOAP是一个被类型化的序列化格式,它恰巧用HTTP 作为请求/响应消息传输协议。SOAP被设计为与正将出现的XML Schema规范密切配合,并支持在Internet的任何地方运行的COM, CORBA, Perl, Tcl, 和 Java-language, C, Python, 或 PHP 等程序间的互操作性。
希望本文给了你一个对这个协议具体细节的更清晰的理解。我鼓励你用SOAP进行实验,或者试着使用SOAP使能的系统之一(列在http://www.develop.com/soap/),或者自己做一些工作。我本人发现采用脚本语言(Jscript),使一个基本的SOAP客户与服务器建立并运行只花费了不到一个小时。针对你对HTTP和XML的熟悉程度,以及你的目标平台的成熟度,你所花费的时间会有所不同。
内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息