?? soap規(guī)范(1).txt
字號:
識別應(yīng)用程序想要的SOAP消息的所有部分 (見4.2.2節(jié))
檢驗應(yīng)用程序是否支持第一步中識別的消息中所有必需部分并處理它。如果不支持,則丟棄消息(見4.4節(jié))。在不影響處理結(jié)果的情況下,處理器可能忽略第一步中識別出的可選部分。
如果這個SOAP應(yīng)用程序不是這個消息的最終目的地,則在轉(zhuǎn)發(fā)消息之前刪除第一步中識別出來的所有部分。
為了正確處理一條消息或者消息的一部分,SOAP處理器需要理解:所用的交換方式(單向,請求/應(yīng)答,多路發(fā)送等等),這種方式下接收者的任務(wù),RPC機制(如果有的話)的使用(如第7節(jié)中所述),數(shù)據(jù)的表現(xiàn)方法或編碼,還有其它必需的語義。
盡管屬性比如SOAP encodingstyle(見4.1.1節(jié))可以用于描述一個消息的某些方面,但這個規(guī)范并不強制所有的接收方也必須有同樣的屬性并取同樣的屬性值。舉個例子,某一特定的應(yīng)用可能知道一個元素表示一條遵循第7節(jié)約定的RPC請求,但是另外一些應(yīng)用可能認(rèn)為指向該元素的所有消息都用單向傳輸,而不是類似第7節(jié)的請求應(yīng)答模式。
(譯者注:交互雙方的SOAP消息并不一定要遵循同樣的格式設(shè)定,而只需要以一種雙方可理解的格式交換信息就可以了)
3. 與XML的關(guān)系
所有的SOAP消息都使用XML形式編碼(更多有關(guān)XML的信息請見[7])
一個SOAP應(yīng)用程序產(chǎn)生的消息中,所有由SOAP定義的元素和屬性中必須包括正確的名域。SOAP應(yīng)用程序必須能夠處理它接收到的消息中的SOAP名域(見4.4節(jié)),并且它可以處理沒有SOAP名域的SOAP消息,就象它們有正確的名域一樣。
SOAP定義了兩個名域(更多有關(guān)XML名域的信息請見[8])
SOAP封裝的名域標(biāo)志符是"http://schemas.xmlsoap.org/soap/envelope/"
SOAP的編碼規(guī)則的名域標(biāo)志符是"http://schemas.xmlsoap.org/soap/encoding/"
SOAP消息中不能包含文檔類型聲明,也不能包括消息處理指令。[7]
SOAP使用"ID"類型"id"屬性來指定一個元素的唯一的標(biāo)志符,同時該屬性是局部的和無需校驗的。SOAP使用"uri-reference"類型的"href"屬性指定對這個值的引用,同時該屬性是局部的和無需校驗的。這樣就遵從了XML規(guī)范[7],XML Schema規(guī)范[11]和XML連接語言規(guī)范[9]的風(fēng)格。
除了SOAP mustUnderstand 屬性(見4.2.3節(jié))和SOAP actor屬性(見4.2.2節(jié))之外,一般允許屬性和它們的值出現(xiàn)在XML文檔實例或Schema中(兩者效果相同)。也就是說,在DTD或Schema中聲明一個缺省值或固定值和在XML文檔實例中設(shè)置它的值在語義上相同。
4. SOAP封裝
SOAP消息是一個XML文檔,包括一個必需的SOAP封裝,一個可選的SOAP頭和一個必需的SOAP體。在這篇規(guī)范剩余部分中,提到SOAP消息時就是指這個XML文檔。這一節(jié)中定義的元素和屬性的名域標(biāo)志符為:"http://schemas.xmlsoap.org/soap/envelope/" 。一個SOAP消息包括以下部分:
在表示這個消息的XML文檔中,封裝是頂層元素。
應(yīng)用SOAP交換信息的各方是分散的且沒有預(yù)先協(xié)定,SOAP頭提供了向SOAP消息中添加關(guān)于這條SOAP消息的某些要素(feature)的機制。SOAP定義了少量的屬性用來表明這項要素(feature)是否可選以及由誰來處理。(見4.2節(jié))
SOAP體是包含消息的最終接收者想要的信息的容器(見4.3節(jié))。SOAP為SOAP體定義了一個Fault元素用來報告錯誤信息。
語法規(guī)則如下所示:
封裝
元素名是 "Envelope"
在SOAP消息中必須出現(xiàn)。
可以包含名域聲明和附加屬性。如果包含附加屬性,這些屬性必須限定名域。類似的,"Envelope"可以包含附加子元素,這些也必須限定名域且跟在SOAP體元素之后。
SOAP頭 (見4.2節(jié))
元素名是"Header"
在SOAP消息中可能出現(xiàn)。如果出現(xiàn)的話,必須是SOAP 封裝元素的第一個直接子元素。
SOAP頭可以包含多個條目,每個都是SOAP頭元素的直接子元素。所有SOAP頭的直接子元素都必須限定名域。
SOAP體 (見4.3節(jié))
元素名是"Body"
在SOAP消息中必須出現(xiàn)且必須是SOAP封裝元素的直接子元素。它必須直接跟在SOAP頭元素(如果有的話)之后。否則它必須是SOAP封裝元素的第一個直接子元素。
SOAP體可以包括多個條目,每個條目必須是SOAP體元素的直接子元素。SOAP體元素的直接子元素可以限定名域。SOAP定義了SOAP Fault元素來表示錯誤信息。(見4.4節(jié)).
4.1.1 SOAP encodingStyle 屬性
EncodingStyle全局屬性用來表示SOAP消息的序列化規(guī)則。這個屬性可以在任何元素中出現(xiàn),作用范圍與名域聲明的作用范圍很相似,為這個元素的內(nèi)容和它的所有沒有重載此屬性的子元素。SOAP消息沒有定義缺省編碼。
屬性值是一個或多個URI的順序列表,每個URI確定了一種或多種序列化規(guī)則,用來不同程度反序列化SOAP消息,舉例如下:
"http://schemas.xmlsoap.org/soap/encoding/"
"http://my.host/encoding/restricted http://my.host/encoding/"
""
第5節(jié)中定義的序列化規(guī)則由URI"http://schemas.xmlsoap.org/soap/encoding/" 確定。使用這個特定序列化規(guī)則的消息應(yīng)該用encodingStyle屬性說明這一點。另外,所有以"http://schemas.xmlsoap.org/soap/encoding/"開頭的URI中的序列化規(guī)則與第5節(jié)中定義的SOAP編碼規(guī)則相一致。
一個零長度的URI("")明確顯示所含元素沒有任何編碼形式。這可以用來取消上一級元素的所有編碼聲明。
4.1.2 封裝版本模型
SOAP沒有定義常規(guī)的基于主版本號和輔版本號的版本形式。SOAP消息必須有一個封裝元素與名域"http://schemas.xmlsoap.org/soap/envelope/"關(guān)聯(lián)。如果SOAP應(yīng)用程序接收到的SOAP消息中的SOAP封裝元素與其他的名域關(guān)聯(lián),則視為版本錯誤,應(yīng)用程序必須丟棄這個消息。如果消息是通過HTTP之類的請求/應(yīng)答協(xié)議收到的,應(yīng)用程序必須回答一個SOAP VersionMismatch 錯誤信息(見4.4節(jié))。
4.2 SOAP頭
SOAP為相互通信的團體之間提供了一種很靈活的機制:在無須預(yù)先協(xié)定的情況下,以分散但標(biāo)準(zhǔn)的方式擴展消息。可以在SOAP頭中添加條目實現(xiàn)這種擴展,典型的例子有認(rèn)證,事務(wù)管理,支付等等。
頭元素編碼為SOAP封裝元素的第一個直接子元素。頭元素的所有直接子元素稱作條目。
條目的編碼規(guī)則如下:
一個條目有它的完整的元素名(包括名域URI和局部名)確定。SOAP頭的直接子元素必須有名域限制。
SOAP encodingStyle屬性可以用來指示條目所用的編碼形式(見4.1.1節(jié))
SOAP mustUnderstand屬性(見4.2.3節(jié))和SOAP actor屬性(見4.2.2節(jié))可以用來指示如何處理這個條目以及由誰來處理。(見4.2.1節(jié))
4.2.1 使用頭屬性
這一節(jié)中定義的SOAP頭屬性確定了SOAP消息的接收者應(yīng)該怎樣按第2節(jié)中所述的方式處理消息。產(chǎn)生SOAP消息的SOAP應(yīng)用程序,應(yīng)該僅僅在SOAP頭元素的直接子元素中使用這些SOAP頭屬性。SOAP消息的接收者必須忽略所有不在SOAP頭元素的直接子元素中SOAP頭屬性。
下面的例子是一個SOAP頭,包括一個元素標(biāo)志符"Transaction","mustUnderstand"取值為"1"和數(shù)值5。這應(yīng)該以如下方式編碼:
<SOAP-ENV:Header>
<t:Transaction
xmlns:t="some-URI" SOAP-ENV:mustUnderstand="1">
5
</t:Transaction>
</SOAP-ENV:Header>
4.2.2 SOAP actor屬性
一個SOAP消息從始節(jié)點到終節(jié)點的過程中,可能沿著消息路徑經(jīng)過一系列SOAP中間節(jié)點。一個SOAP中間節(jié)點是一個可以接收轉(zhuǎn)發(fā)SOAP消息的應(yīng)用程序。中間節(jié)點和終節(jié)點由URI區(qū)分。
可能SOAP消息的終節(jié)點并不需要所有部分,而在消息路徑上的一個和幾個中間節(jié)點可能需要這些內(nèi)容。頭元素的接收者扮演的角色類似于一個過濾器,防止這些只發(fā)給本接受者的消息部分?jǐn)U散到其它節(jié)點。即一個頭元素的接收者必須不轉(zhuǎn)發(fā)這些頭元素到SOAP消息路徑上的下一個應(yīng)用程序。同樣的,接收者可能插入一個相似的頭元素。
SOAP actor全局屬性可以用于指示頭元素的接收者。SOAP actor屬性的值是一個URI。URI "http://schemas.xmlsoap.org/soap/actor/next"指出了第一個處理這個消息的SOAP應(yīng)用程序需要這個頭元素。這類似于HTTP頭中用Connection域表示hop-by-hop范圍模型。
省略SOAP actor屬性表示接收者是SOAP消息的終節(jié)點。
如果這個屬性要生效,它必須出現(xiàn)在SOAP消息實例中。(見第3節(jié)和4.2.1節(jié))
4.2.3 SOAP mustUnderstand屬性
SOAP mustUnderstand全局屬性用來指示接受者在處理消息時這個條目是否必須處理。條目的接收者由SOAP actor屬性定義(見4.2.2節(jié))。MustUnderstand屬性的值是"1" 或 "0"。缺少SOAP mustUnderstand屬性在語義上等同于它的值為"0"。
如果一個頭元素的SOAP mustUnderstand屬性的值是"1",那么條目的接受者必須或者遵守語義(如以元素的全名傳送)并按照語義正確的處理,或者放棄處理消息(見4.4節(jié))。
SOAP mustUnderstand 屬性考慮了消息演變的準(zhǔn)確性(robust evolution)。必須假定包含SOAP mustUnderstand屬性且值為"1"的元素以某種方式修改了它們的父元素或同層元素的語義。以這種方式連接元素確保了語義上的變化不會被那些不能完全理解它的接收者忽略。
如果這個屬性要生效,它必須出現(xiàn)在SOAP消息實例中。(見第3節(jié)和4.2.1節(jié))
4.3 SOAP體
SOAP體元素提供了一個簡單的機制,使消息的最終接收者能交換必要的信息。使用體元素的典型情況包括配置RPC請求和錯誤報告。
體元素編碼為SOAP封裝元素的直接子元素。如果已經(jīng)有一個頭元素,那么體元素必須緊跟在頭元素之后,否則它必須是SOAP封裝元素的第一個直接子元素。
體元素的所有直接子元素稱作體條目,每個體條目在SOAP體元素中編碼為一個獨立的元素。
條目的編碼規(guī)則如下:
一個條目由它的元素全名(包括名域URI和局部名)確定。SOAP體元素的直接子元素可能是名域限制的。
SOAP encodingStyle屬性可能用來指示條目(見4.1.1節(jié))的編碼方式。
SOAP定義了一個Fault條目用來報告錯誤信息。(見4.4節(jié))
4.3.1 SOAP頭和體的關(guān)系
雖然頭和體定義為獨立的元素,它們實際上是有關(guān)系的。體條目和頭條目的關(guān)系如下:體條目在語義上等同于actor屬性為缺省值且mustUnderstand屬性值為"1"的頭條目。不使用actor屬性則表示缺省的actor。(見4.2.2節(jié))
4.4 SOAP錯誤
SOAP錯誤元素用于在SOAP消息中攜帶錯誤和(或)狀態(tài)信息。如果有SOAP錯誤元素,它必須以以體條目的方式出現(xiàn),并且在一個體元素中最多出現(xiàn)一次。
SOAP錯誤元素定義了以下四個子元素:
faultcode
faultcode元素給軟件提供了一個識別此錯誤的算法機制。SOAP錯誤元素必須有faultcode子元素,并且它的值必須是一個合法的名(在[8]節(jié)定義)。SOAP定義一些SOAP faultcode描述基本的SOAP錯誤(見4.4.1節(jié))。
faultstring
faultstring元素提供了一個錯誤解釋,而不是為了軟件處理。faultstring元素類似于HTTP中定義(見[5],第6.1節(jié))的'Reason-Phrase'。SOAP錯誤元素必須有faultstring子元素,并且它應(yīng)該提供一些錯誤本質(zhì)的解釋信息。
faultactor
faultactor元素提供了在消息路徑上是誰導(dǎo)致了錯誤發(fā)生的信息(見第2節(jié))。它類似于SOAP actor屬性(見4.2.2節(jié)),只是SOAP actor指的是頭條目的目的地,faultactor指的是錯誤的來源。faultactor屬性的值是用來區(qū)分錯誤來源的URI。不是SOAP消息的最終目的地的應(yīng)用程序必須在SOAP Fault元素中包含faultactor元素。消息的最終目的地可以使用faultactor元素明確的指示是它產(chǎn)生了這個錯誤(參見下面的detail元素)
detail
detail元素用來攜帶與Body元素有關(guān)的應(yīng)用程序所要的錯誤信息。如果Body元素的內(nèi)容不能被成功的處理,則必須包含detail子元素。它不能用來攜帶屬于頭條目的錯誤信息。頭條目的詳細(xì)出錯信息必須由頭條目攜帶。
Fault元素中沒有detail元素表示這個錯誤與Body元素的處理無關(guān)。在有錯誤的時候,這可以用來區(qū)分Body元素有沒有被正確的處理。
detail元素的所有直接子元素稱作detail條目,并且每個detail條目在detail元素中編碼為獨立的元素。
detail條目的編碼規(guī)則如下(參見例10):
一個detail條目由它的元素全名(包括名域URI和局部名)確定。SOAP體元素的直接子元素可能是名域限制的。
SOAP encodingStyle屬性可能用來指示detail條目(見4.1.1節(jié))的編碼方式。
也可以有其它的Fault子元素,只要它們是名域限制的。
?? 快捷鍵說明
復(fù)制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -