SOAP 資料處理常式會以下列方式執行 SOAP 訊息與商業物件之間的轉換作業:
本節提供從 SOAP 主體訊息轉換成商業物件的逐步式說明。
- SOAP 資料處理常式接收 SOAP 訊息。
- 資料處理常式使用 Apache SOAP API 來剖析 SOAP 訊息。
- 資料處理常式擷取 SOAP 訊息的元件:封套、標頭和主體。
- 標頭處理程序如需詳細資訊,請參閱從 SOAP 標頭訊息轉換成商業物件的處理程序。
- 主體處理程序資料處理常式讀取 SOAP 主體的第一個元素,
判斷其是否帶有錯誤或資料。
若主體的內容不是個錯誤,資料處理常式將進行下列作業:
- 執行商業物件解析,以決定要在轉換作業中使用哪個商業物件。
若您已配置自訂名稱處理常式,則不適用下面所討論的預設商業物件解析。
如需有關指定可插入的名稱處理常式的資訊,請參閱指定可插入的名稱處理常式。
- 資料處理常式亦會解析將要用來從事轉換作業的 SOAP Config MO (資料處理常式所建立之
SOAP 商業物件的子項)。
若 SOAP Config MO 的實例不存在,資料處理常式便會建立實例,並讀取其預設值。
資料處理常式會從 ConfigMO 屬性值來讀取商業物件動詞。
資料處理常式會將 SOAP 商業物件實例化,並依情況來設定動詞。
資料處理常式將會嘗試把 SOAP 訊息寫入這個商業物件。
- 資料處理常式繼續剖析 SOAP 訊息,一次一個元素。
若為 rpc,資料處理常式會預期第一個元素為母項。
- 資料處理常式預期商業物件的屬性 (或其應用程式特有資訊:如需進一步資訊,
請參閱從商業物件轉換成 SOAP 訊息之作業中的 ASI) 的名稱應與子元素的名稱相同。
若於商業物件中找不到屬性,資料處理常式便會擲出異常狀況。
子元素可為簡式類型,亦可為複式類型。
複式元素就是具有子元素的那些元素。
- 簡式元素若子元素為簡式元素,依預設,
資料處理常式會預期商業物件屬性的名稱 (或 ASI) 與簡式元素的名稱相同。
資料處理常式會讀取簡式元素的值,並將它設定於商業物件中。
- 複式元素若子元素為複式類型,
資料處理常式會預期商業物件的屬性名稱 (或 ASI) 和類型與子項商業物件相同。
此屬性可為單一基數或是多重基數,需視有無複式 SOAP 元素或 SOAP 陣列而定。
接著,資料處理常式會將子項商業物件實例化 (依預設,屬性的類型會提供子項
商業物件的名稱),並讀取此複式元素的所有子元素,於子項商業物件中設定其值。
資料處理常式在驗證此屬性的基數後,會將此子項商業物件設定於母項商業物件屬性中。
若屬性為基數 n,資料處理常式便會將此商業物件附加至儲存區。
複式元素可以有簡式或複式子元素。這些元素也是以同樣的方式來處理:
若是簡式元素,資料處理常式就會在子項 BO 中設定值;
若是複式元素,資料處理常式就會將子項商業物件實例化。
- 錯誤處理程序資料處理常式會讀取 SOAP 主體第一個元素的
名稱,判斷它是否為錯誤。
若第一個元素的名稱為 Fault,資料處理常式就會認定這是錯誤訊息。
然後進行錯誤商業物件解析,判斷要將此錯誤訊息轉換成哪一種商業物件。
接著資料處理常式會遵循與主體處理程序相同的處理程序來進行。
資料處理常式預期子項商業物件中所指定的商業物件具有下列屬性:
- faultcode:必要的。String 屬性
- faultstring:必要的。String 屬性
- faultactor:非必要的 String 屬性
- detail:非必要的。子項 BO
- 若錯誤處理程序因任何原因而導致失敗,所擲出的異常狀況將會包含來自 SOAP 錯誤
訊息中之 faultcode、faultstring 及 faultactor 元素的文字。
- 註:
- 根據錯誤訊息的 SOAP 規格,faultcode、faultstring 及 faultactor 為簡式元素,
而 detail 為複式元素 (含有子元素的元素)。
此外,faultcode、faultstring、faultactor 及 detail 是屬於 SOAP 封套名稱空間,
而 detail 子元素可能是屬於使用者定義的名稱空間。
本節說明資料處理常式如何將 SOAP 訊息的標頭轉換成商業物件。
- SOAP 資料處理常式處理 SOAP 訊息的主體。主體處理程序會建立 SOAP 商業物件。
- 若 SOAP 訊息具有 SOAP 標頭元素,SOAP 資料處理常式預期由主體處理程序所取得的
商業物件中,會有 SOAP 標頭屬性。
SOAPHeader 屬性為商業物件的子屬性,並以 soap_location=SOAPHeader
作為其應用程式特有資訊。
若無這樣的屬性,SOAP 資料處理常式就會擲出錯誤。
SOAPHeader 屬性的類型必須是「SOAP 標頭儲存區」商業物件。
SOAP 資料處理常式會於步驟 1 中所取得的 SOAP 商業物件中,建立此屬性的實例。
- 對於 SOAP-Env:Header 元素的每個直接子項:
- 資料處理常式預期「SOAP 標頭儲存區商業物件」中有子屬性。
此屬性的名稱必須與標頭元素的名稱相同,且必須符合「SOAP 標頭子項」商業物件。
若資料處理常式找不到這樣的屬性,就會擲出錯誤。
此外,此元素的名稱空間應與此屬性之 elem_ns 應用程式特有
資訊中所指定的相同。
若不同,資料處理常式就會擲出錯誤。
- 資料處理常式建立「SOAP 標頭子項」商業物件的實例,並將其置於步驟 2 所建立的
「SOAP 標頭儲存區」商業物件中。
- 若此標頭元素具有 actor 屬性,資料處理常式便會預期上面所建立的子項商業物件中,
有 actor 屬性的存在。
若找不到 actor 屬性,資料處理常式就會擲出錯誤。
- 註:
- 若您要新增 actor 屬性,請參閱指定 SOAP 屬性。
- 若此標頭元素具有 mustUnderstand 屬性,資料處理常式就會預期上面所建立的
子項商業物件中,有 mustUnderstand 屬性的存在。
若找不到 mustUnderstand 屬性,資料處理常式就會擲出錯誤。
- 註:
- 若您要新增 mustUnderstand 屬性,請參閱指定 SOAP 屬性。
- 對於此標頭元素的每個子元素,資料處理常式都會預期子項商業物件中有一個具有相同名稱的屬性。
將會以處理 SOAP-Env:Body 元素之子元素的相同方式,來處理這些元素。
以下是從商業物件轉換成 SOAP 主體訊息的逐步式說明。
欲參考有關應用程式特有資訊的特殊案例,請參閱從商業物件轉換成 SOAP 訊息之作業中的 ASI
- SOAP 資料處理常式尋找對應其所轉換之 SOAP 商業物件的 SOAP ConfigMO。
- 資料處理常式編製 SOAP 訊息的封套及標頭。
- 資料處理常式解析 SOAP ConfigMO。若 SOAP ConfigMO 的實例不存在,
資料處理常式便會建立實例,並讀取其預設值。
依預設,資料處理常式讀取 SOAP ConfigMO 中的 BodyName 屬性值,以判斷其是否正在處理錯誤商業物件。
若其設定為 soap:fault,則該商業物件會被當作 SOAP 錯誤商業物件。
若不是錯誤商業物件,資料處理常式就會執行下面編製主體所描述的處理程序,或是編製錯誤所描述的處理程序。
- 編製主體下列步驟詳細說明資料處理常式從商業物件編製 SOAP 訊息主體的處理程序:
- 資料處理常式從 SOAP ConfigMO 屬性取得 BodyName 及 BodyNS,然後編製 SOAP 訊息的第一個 (母項) 元素。
依預設,第一個元素的名稱就是 BodyName 的值。於本書中,亦指主體元素。
依預設,主體元素的名稱空間為 BodyNS 所決定的值。
若 SOAP ConfigMO 的 Style 屬性設定為 document,則會跳過這個步驟 (建立第一個主體元素)。
- 然後資料處理常式會讀取商業物件的屬性,並依類型加以處理。各類型之屬性的處理程序說明如下。
- 編製錯誤下列各節將說明資料處理常式編製錯誤訊息的整個過程。
- CxIgnore 處理程序若資料處理常式發現屬性值的設定為 CxIgnore,
資料處理常式就不會為此屬性建立元素。
- CxBlank 處理程序若資料處理常式判斷出屬性值的設定為 CxBlank,
資料處理常式就會為此屬性建立元素,但不會設定其值。
本節僅說明 SOAP 標頭屬性的處理程序。所有其他屬性的處理程序說明,
請見"從商業物件轉換成 SOAP 訊息主體的處理程序"。
- SOAP 資料處理常式從商業物件取得 SOAPHeader 屬性。
此屬性具有 soap_location=SOAPHeader,為其應用程式特有資訊。
僅當此屬性的值為非空值時,SOAP 資料處理常式才會建立 SOAP-Env:Header 元素。
若商業物件包含多個 SOAPHeader 屬性,
則會處理第一個屬性,其他屬性則會被當作主體的一部分。
- SOAP 資料處理常式預期 SOAPHeader 屬性為單一基數子項,
代表「SOAP 標頭儲存區」商業物件。
資料處理常式會處理類型為「SOAP 標頭子項」商業物件的「SOAP 標頭儲存區」商業物件子屬性。
- 針對「SOAP 標頭儲存區」商業物件的每個屬性,資料處理常式將進行下列作業:
- 檢查基數:若此屬性「不是」 1 或 n 基數子項物件,則將之忽略。
- 檢查值:若此屬性的值為「空值」,則將之忽略。
- 若屬性為 1 或 n 基數子項物件,SOAP 資料處理常式就會建立一個標頭元素,
作為步驟 1 所建立之 SOAP-Env:Header 元素的直接子項。此標頭元素的名稱與屬性的名稱相同。
此元素的名稱空間是由此屬性的 elem_ns 應用程式特有資訊所給定的。
- 若屬性為「SOAP 標頭子項」商業物件,則會處理此商業物件的所有屬性。
此屬性可能具有 actor 及 mustUnderstand 屬性。
- 註:
- 若您要新增 mustUnderstand 或 actor 屬性,
請參閱指定 SOAP 屬性。
- 若「SOAP 標頭子項」商業物件具有非空值的 actor 屬性,
資料處理常式便會於步驟 c 中所建立的標頭元素中,建立 actor 屬性。
- 若「SOAP 標頭子項」商業物件具有非空值的 mustUnderstand 屬性,
資料處理常式便會於步驟 c 中所建立的標頭元素中,建立 mustUnderstand 屬性。
- 「SOAP 標頭子項」商業物件的所有其他非空值屬性,皆會變成此標頭元素的子元素。
其編製的方式和 SOAP-Env:Body 元素的子元素相同。
SOAP 規格指定專屬於標頭的錯誤,皆必須傳回至標頭中。
將這些標頭傳回 SOAP 錯誤訊息中。
就像訊息標頭是指定於要求及回應商業物件的 SOAPHeader 屬性中,
錯誤標頭是指定於錯誤商業物件的 SOAPHeader 屬性中。
要求或回應商業物件的每個可能標頭,都可能會導致錯誤。
這種錯誤皆會記錄於錯誤訊息的標頭中。
WSDL 文件有一個 SOAP 連結標頭錯誤元素,可讓您指定錯誤標頭。
如需詳細資訊,請參閱「第 1 章」所列的 SOAP 及 WSDL 規格。
headerfault 的應用程式特有資訊,可讓您為每個標頭指定標頭錯誤。
您可為「SOAP 標頭儲存區」商業物件的每個屬性,指定 headerfault 應用程式特有資訊。
錯誤商業物件之「SOAP 標頭儲存區」商業物件中的屬性清單如下:
headerfault=attr1, attr2, attr3...
若「WSDL 配置精靈」於要求或回應物件的「SOAP 標頭子項」商業物件中,
找到 headerfault 應用程式特有資訊,該公用程式就會在為這些標頭建立的 WSDL 中,
建立 headerfault 元素。請注意,WSDL 可讓您為您的每個要求 (輸入) 及
回應 (輸出) 標頭,指定多重標頭錯誤。
因此,此應用程式特有資訊的值是一個以逗號隔開的屬性清單。
