使用應用程式特有資訊功能

您可指定物件層次及屬性層次的應用程式特有資訊 (ASI),以擴充及加強 SOAP 資料處理常式功能。 表 45 顯示這些屬性,將於下面的一節中加以討論。 表格中的所有輸入項目都是屬性層次的 ASI,除非另有指定。

表 45. SOAP 物件 ASI 摘要
ASI 可能值 說明
soap_location SOAPHeader 將此商業物件屬性指定為標頭屬性
headerfault String 指出錯誤 BO 中對應 SOAP 標頭的 B0 屬性名稱
elem_name String 指定對應此 BO 屬性之 SOAP 元素的名稱
elem_ns String 指定對應此 BO 屬性之 SOAP 元素的名稱空間
type_name String 指定對應此 BO 屬性之 SOAP 元素的類型
type_ns String 指定對應此 BO 屬性之元素的類型名稱空間
xsdtype true 指定 xsd 作為對應此 BO 屬性之元素的名稱空間,並以最新版的 xsd (例如:2001) 置換舊版的 xsd (例如:1999、2000 等等)。
attr_name String 指定對應此 BO 屬性之 SOAP 屬性的名稱
attr_ns String 指定對應此 BO 屬性之 SOAP 屬性的名稱空間
arrayof String 指定必須用來為此元素建立陣列之 n 基數子項商業物件屬性的名稱
dh_mimetype String 指定將用來轉換此複式類型屬性之資料處理常式的 mimeType
cw_mo_* String 此商業物件層次 ASI 指定 Child Config MO 的名稱,SOAP 資料處理常式會將該名稱解譯為 Meta 資料,而不是內容。 只有 cw_mo_soap 可指定被處理為 Meta 資料的 Child Config MO;所有其他的 cw_mo_* 皆 指定不同的元件,所以不包含於 SOAP 資料處理常式的處理程序內。所有其他 cw_mo* 都會被忽略。
cw_mo_soap String 此商業物件層次 ASI 指定於轉換此商業物件時,所應使用之 Child Config MO 屬性的名稱。
cw_mo_jms String 此商業物件層次 ASI 指定所要使用之 JMS Protocol Config MO 的名稱
cw_mo_http String 此商業物件層次 ASI 指定所要使用之 HTTP Protocol Config MO 的名稱
wrapper true 指定此商業物件中之封套物件的屬性名稱。 封套物件用於特定的綱目指示元,絕不可序列化
maxoccurs 整數 指定此商業物件屬性可能出現的次數上限。依據 maxoccurs 的值,商業物件可能會有,也可能沒有封套。
minoccurs 整數 指定此商業物件屬性可能出現的次數下限。 依據 minoccurs 的值,物件可能會有,也可能沒有封套。
全部 String 指定代表綱目中之 all 指示元的子屬性。
choice String 指定代表綱目中之 choice 指示元的子屬性。

從商業物件轉換成 SOAP 訊息之作業中的 ASI

SOAP 資料處理常式使用商業物件的 ASI 來決定建構 SOAP 訊息的方法。 除非另有說明,否則下面一節中討論的所有 ASI,都是指屬性層次 ASI, 且無論情況如何,皆會執行所有字串型的比較作業。

elem_name 及 elem_ns 處理程序

本節中所討論的範例假設屬性名稱為 OrderId, SOAP 元素名稱空間字首為 ns0

  1. 若 elem_name 和 elem_ns 皆未指定,則將 elem_name 預設為屬性名稱, 將 elem_ns 預設為元素母項的名稱空間。不指定 ASI。
    <OrderId>1</OrderId>
     
  2. 若指定了 elem_name,但未指定 elem_ns,則會將 elem_name 設定為 ASI elem_name 值, 並將 elem_ns 預設為「SOAP 主體」的名稱空間。ASI 如下:
    elem_name=CustOrderId
     <CustOrderId>2</CustOrderId>
     
  3. 若指定了 elem_ns,但未指定 elem_name,則會將 elem_name 預設為屬性名稱, 並將 elem_ns 設定為 ASI elem_ns 值。 只有在此元素範圍的其他地方都找不到元素名稱空間時,才會明確地寫入 xmlns 屬性。 若找到了元素名稱空間,就會使用已定義的名稱空間字首。 否則 (若未找到元素名稱空間),就會為 elem_ns 產生專屬的字首。 請參酌下列範例,其假設字首已定義於範圍中 (ns1 代表對應已定義於此元素範圍內之名稱空間的字首)。 ASI 如下:
    elem_ns= http://www.w3.org/2001/XMLSchema
     <ns1:OrderId>3</ns1:OrderId>
     

    下列範例假設並未找到字首 (ns2 代表專屬的字首)。ASI 如下:

    elem_ns=CustOrderIdNamespace
     <ns2:OrderId xmlns:ns2="CustOrderIdNamespace">3</ns2:OrderId>
     
  4. 當 elem_name 和 elem_ns 皆已指定,elem_name 和 elem_ns 都會設定為 ASI 值。 在上述案例 3 中執行的相同檢查 (有關已定義的名稱空間),亦適用於此。 就如於案例 3 一樣,若尚未定義名稱空間,將為 elem_ns 產生專屬的字首。 ASI 如下:
    elem_name=CustOrderId;elem_ns=CustOrderIdNamespace
     <ns2:CustOrderId xmlns:ns2="CustOrderIdNamespace">1</ns2:OrderId>
     

簡式屬性的 type_name 及 type_ns 處理程序

例如本節中的範例,屬性名稱為 OrderId,SOAP 元素名稱空間字首為 ns0, 屬性類型為 String

註:
僅當 Config MO 屬性 TypeInfo 為 true 時, 才會進行 type_name 及 type_ns 處理程序。
  1. 當 type_name 和 type_ns 皆未指定,則會將 type_name 預設為簡式類型, 將 type_ns 預設為 xml 綱目定義的名稱空間 (xsd)。不指定 ASI。
    <OrderId xsi:type="xsd:string">1</OrderId>
     
  2. 當指定了 type_name,而未指定 type_ns,則會將 type_name 設定為 ASI type_name 值, 將 type_ns 預設為元素的名稱空間。ASI 如下:
    type_name=CustString
     <OrderId xsi:type="ns0:CustString">2</OrderId>
     
  3. 當指定了 type_ns,而未指定 type_name,則會將 type_ns 預設為簡式類型名稱, 並將 type_name 設定為 ASI type_ns 值。用來處理字首的方式,可與建立 elem_ns 的方式相比擬。 除非元素範圍內已有名稱空間存在,否則就會產生類型名稱空間的專屬字首。 ASI 如下:
    type_ns=CustStringNamespace
     <OrderId xmlns:ns2="CustStringNamespace" xsi:type=
     "ns2:String">3</OrderId>
     
  4. 當 type_name 和 type_ns 皆已指定,便會將其設定為所指定的 ASI 值, 並產生類型名稱空間的專屬字首。ASI 如下:
    type_name=CustString;type_ns=CustStringNamespace
     <OrderId xmlns:ns2="CustStringNamespace" xsi:type=
     "ns2:CustString">1</OrderId>
     

單一基數屬性的 type_name 及 type_ns 處理程序

於本節中的範例,屬性名稱為 OrderStaus,SOAP 元素名稱空間字首為 ns0, 屬性類型為 OrderStatus

註:
僅當 Config MO 屬性 TypeInfo 為 true 時, 才會進行 type_name 及 type_ns 處理程序。
  1. 當 type_name 和 type_ns 皆未指定,則會將 type_name 預設為商業物件名稱, 並將類型名稱空間預設為元素的名稱空間。不指定 ASI:
    <OrderStatus  xsi:type="ns0:OrderStatus">1</OrderStatus>
     
  2. 當指定了 type_name,但未指定 type_ns,則會將 type_name 設定為所指定的 ASI 值,將 type_ns 預設為元素的名稱空間。ASI 如下:
    type_name=CustOrderStatus
     <OrderStatus  xsi:type="ns0:CustOrderStatus">1</OrderStatus>
     
  3. 當指定了 type_ns,但未指定 type_name,則會將 type_name 預設為商業物件名稱, 將 type_ns 設定為所指定的 type_ns 值。並產生類型名稱空間的專屬字首。ASI 如下:
    type_ns=CustTypeNS
     <OrderStatus  xsi:type="ns2:SOAP_OrderStatusLine
     " xmlns:ns2="CustTypeNS">1</OrderStatus>
     
  4. 當 type_name 和 type_ns 皆已指定,便會將其設定為所指定的 ASI 值, 並產生類型名稱空間的專屬字首。ASI 如下:
    type_name=CustOrderStatus;type_ns=CustTypeNS
     <OrderStatus
     xsi:type="ns2:CustOrderStatus" xmlns:ns2="CustTypeNS">1</OrderStatus>
     

多重基數屬性的 type_name 及 type_ns 處理程序

本節中的所有範例皆假設屬性名稱為 MultiLines,SOAP 元素名稱空間字首為 ns0。 並假設屬性類型為 OrderStatus。

註:
僅當 Config MO 屬性 TypeInfo 為 true 時, 才會進行 type_name 及 type_ns 處理程序。
  1. 若 type_name 和 type_ns 皆未指定,則會將 type_name 預設為商業物件名稱, 並將 type_ns 預設為元素的名稱空間。ASI 如下:
    <MultiLines SOAP-ENC:arrayType="ns0:OrderStatus[2]"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
     xsi:type="SOAP-ENC:Array">
     
  2. 若指定了 type_name,而未指定 type_ns,則會將 type_name 設定為所指定的 ASI type_name 值, 將 type_ns 預設為元素的名稱空間。ASI 如下:
    type_name=CustOrderStatus
     <MultiLines SOAP-ENC:arrayType="ns0:CustOrderStatus[2]"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
     xsi:type="SOAP-ENC:Array">
     
  3. 當指定了 type_ns,但未指定 type_name,則會將 type_name 預設為商業物件名稱, 將 type_ns 設定為所指定的 ASI type_ns 值,並產生類型名稱空間的專屬字首。ASI 如下:
    type_ns=CustTypeNS
     <MultiLines SOAP-ENC:arrayType="ns2:OrderStatus[2]"
     xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/
     " xmlns:ns2="CustTypeNS" xsi:type="SOAP-ENC:Array">
     
  4. 當 type_name 和 type_ns 皆已指定,便會將其設定為所指定的 ASI 值, 並產生類型名稱空間的專屬字首。ASI 如下:
    type_name=CustOrderStatus;type_ns=CustTypeNS
     <MultiLines SOAP-ENC:arrayType="ns2:CustOrderStatus[2
     ]" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
     xmlns:ns2="CustTypeNS" xsi:type="SOAP-ENC:Array">
     

註:
代表各「陣列」元素母項的項目元素,皆具有與 arrayType 相同的類型及名稱空間。

簡式、單一及多重基數類型的 xsdtype

若為簡式、單一及多重基數類型,請將類型名稱的 xsdtype ASI 屬性設定為 true, 以符合 SOAP 訊息的現行 XSD。 當 type_name 和 type_ns 內容皆已設定,則 xsdtype 為唯讀內容。 在已指定 type_name 及 type_ns 的情況下,SOAP 資料處理常式會先嘗試使用 SOAP API, 將該配對對映至 Java 類型。 然後資料處理常式會嘗試使用「SOAP訊息」的現行 XSD,將 Java 類型轉換回 SOAP 元素類型。 比方說,若現行 XSD 為

http://www.w3.org/2001/XMLSchema
 

且具有下列 ASI:

type_name=timeInstant;type_ns=http://www.w3.org/1999/XMLSchema;xsdtype=true
 

則會將 SOAP 訊息類型寫成:


<OrderDate xsi:type="xsd:dateTime">
 

因為 2001 XSD 的 dateTime 同等於 1999 XSD 的 timeInstant

xsdtype 及簡式類型陣列

若為多重基數物件,您可建立簡式類型陣列,如下所示:

<MultiLines SOAP-ENC:arrayType="xsd:string[4]"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xsi:type="SOAP-ENC:Array">
 

欲達成此作業,請將 type_name 內容設定為所需的簡式類型 (例如:string), 並將 type_ns 內容設定為適當的 XSD 規格。 然後,將 xsdtype 內容設定為 true,將類型轉換為現行的 XSD 類型。 最後,arrayOf 內容應設定為要保存該簡式類型值之儲存區中屬性的名稱。 下面為字串陣列 ASI 的樣式範例:

arrayof=size;type_name=string;type_ns=http://www.w3.org/2001/XMLSchema;xsdtype=true
 

ASI 對錯誤處理程序的影響

faultcode、faultactor、faultstring 及 detail 元素應遵循下列規則:

  1. 這些屬性中的任何 elem_name、elem_ns、type_name 及 type_ns ASI 皆會被忽略。
  2. detail 元素的所有子項,都會完全按照主體處理程序中所描述的方法來寫入。

ASI 對標頭處理程序的影響

您可以使用標頭子項物件層次以下的所有 ASI 內容 (請參閱表 45)。

指定 SOAP 屬性

簡式類型的 attr_name 處理程序

此項不受支援。商業物件屬性必須為複式 (1 或 n 基數) 類型,才能建立 SOAP 屬性。

單一及多重基數類型的 attr_name 處理程序

您可以指定 ASI,將商業物件屬性轉換為 SOAP 屬性,而非轉換為 SOAP 元素。 資料處理常式僅支援將 SOAP 屬性新增至複式單一及 n-card 類型。 請參酌下列範例:

<CustInfo City="4" State="5" Street="2" Zip="6">
    <Name xsi:type="xsd:string">1</Name>
    <Street2 xsi:type="xsd:string">3</Street2>
 </CustInfo>
 

假設商業物件定義結構如下 (屬性層次 ASI 指定於圖 45 中, 每個屬性的右邊),資料處理常式會遵循下列處理步驟:

圖 45. attr_name 商業物件


  1. 當遍訪複式屬性時,資料處理常式會先為此複式商業物件屬性產生對應的標籤。 在此範例中,CustInfo 代表複式商業物件屬性。
  2. 資料處理常式會在複式商業物件的子項之間往返。 僅考慮以簡式類型屬性來建立屬性。 若簡式類型具有名為 attr_name 的 ASI 內容, 資料處理常式便會將此簡式類型當成屬性寫入 SOAP 元素。 於此範例中,元素 (CustInfo) 將會有四種屬性:Street、City、State 及 Zip。
  3. 至於商業物件的其餘屬性,則會使用標準的「主體」處理程序來將其寫入。 這表示,即使是沒有 attr_name ASI 的商業物件屬性,還是會為其評估所有相關的 ASI。

處理多重基數類型的邏輯,與處理單一基數類型的邏輯相同。 尤其,每個 <item> 標籤都會對應於多重基數物件中的每個商業物件實例, 且皆使用 ASI 加以處理。 例如,假設此多重基數商業物件定義結構具有對應的 ASI:

圖 46. attr_name 多重基數商業物件


若傳送至資料處理常式的事件具有此多重基數物件的二個實例,則所建立的 SOAP 訊息外觀如下:

<CustInfo>
    <item City="Armonk" Street="Main Street">
       <Name>IBM</Name>
       <Street2>None</Street2>
    </item>
    <item City="Burlingame" State="Ca" Street="577 Airport Blvd" Zip="94010">
       <Name>Burlingame Labs</Name>
       <Street2>Suite 600</Street2>
    </item>
 </CustInfo>
 

請注意,item 標籤會被視為複式元素類型。 BO 定義中的任何屬性將成為對應之 item 標籤的 SOAP 屬性。

arrayof 處理程序

使用 arrayof ASI 內容,將 SOAP 屬性指定給該陣列元素本身 (不是 child 標籤)。 將 arrayof 內容新增至單一基數複式類型的 ASI。 arrayof 內容的值必須是 SOAP 訊息所要代表之多重基數子項的名稱。 建立好 SOAP 訊息之後,多重基數子項即代表陣列的 child 標籤。

圖 47 顯示商業物件定義, 包括 arrayof 元素及對應的 ASI。

圖 47. arrayof 商業物件


若傳送至資料處理常式的事件具有此基數 n 物件的二個實例,則所建立的 SOAP 訊息外觀如下:

<Customer ID="12">
    <CustInfo City="4" State="5" Street="2" Zip="6">
       <Name>1</Name>
       <Street2>3</Street2>
    </CustInfo>
    <CustInfo City="10" State="11" Street="8" Zip="12">
       <Name>7</Name>
       <Street2>9</Street2>
    </CustInfo>
 </Customer>
 

請注意,arrayof 內容可用來建立名稱不是 item 的陣列項目。 於此範例中,item 標籤為 CustInfo 標籤所取代。 此元素名稱是從 arrayof ASI 內容所指之商業物件屬性的名稱衍生而來。

attr_name 及 attr_ns 處理程序

您可能需要提供一個對應於已建立之 SOAP 屬性的名稱空間。 若要這麼做,您可以為簡式類型指定 attr_ns ASI 內容。 只有當 attr_name 存在於相同屬性的 ASI 時,資料處理常式才會處理 attr_ns 內容。 attr_name 及 attr_ns 遵循下列規則:

  1. 若 attr_name 和 attr_ns exist 都不存在,就會將商業物件屬性轉換成 SOAP 元素。
  2. 僅當設定 attr_name,SOAP 屬性的名稱空間會預設為元素的名稱空間:
    <CustInfo Street="577 Airport"></CustomerInfo>
     
  3. 當僅設定 attr_ns,就會忽略該內容,並將商業物件屬性轉換成 SOAP 元素。
  4. 當 attr_name 和 attr_ns 皆存在,就會建立 SOAP 屬性,如下所示:
    <CustInfo ns2:Street="577 Airport" xmlns:ns2=
     "AttrNS"></CustomerInfo>
     

dh_mimetype:呼叫資料處理常式

SOAP 資料處理常式可呼叫另一個資料處理常式, 將商業物件撰寫為目前存在之資料處理常式的任何格式。 若要這麼做,請在將 SOAP 子項商業物件轉送至「SOAP 字串」時, 將已編碼的文字新增至 SOAP 訊息。

RNIF 文件為用來將 SOAP 元素值編碼的其中一種格式。 若要使用這項功能,請在任何層次的 SOAP 子項商業物件中,新增 RNIF BO。 若要通知 SOAP 資料處理常式,於 RNIF 商業物件轉換成字串時, 呼叫另一個資料處理常式,請在屬性的 ASI 中,新增 dh_mimetype 內容。 dh_mimetype ASI 內容的值必須是指定於 MO_DataHandler_Default Meta 物件中的合法的 mimeType。 mimeType 可用來決定要呼叫哪一個資料處理常式來處理商業物件。

圖 48 顯示 SOAP 子項商業物件, 其中 CustomerInfo 為複式子項,RNET_Pip3A2PriceAndAvailabilityQuery 為 RNIF 商業物件:

圖 48. 具有 dh_mimetype 的 RNIF 商業物件


從此商業物件所建立的 SOAP 訊息,看起來就像下面這個樣子:

<CustomerInfo>
 <Name>IBM Corporation</Name>
 <CustID>95626</CustID>
 <RNIFexample
 xsi:type="xsd:base64Binary">1AWERYER238W98EYR9238728374871892787ASRJK23423
 JKAWERJ234AWERIJHI423488R4HASF1AWERYER238W98EYR9238728374871892787ASRJK234
 34JKAWERJ234AWERIJHI423488R4HASF1AWERYER238W98EYR9238728374871892787ASRJK2
 4234JKAWERJ234AWERIJHI423488R4HASF1AWERYER238W98EYR9238728374871892787ASRJ
 234234JKAWERJ234AWERIJHI423488R4HASFWR234
 </RNIFexample>
 </CustomerInfo>
 

請注意,RNIF 範例元素包含 RNIF 編碼的字串,且該字串已用 base64 二進位碼來編碼為其元素值。 另請注意,elem_name、elem_ns、type_name、type_ns 及 xsdtype ASI 內容仍會為此商業物件屬性保持其關聯性。 於此範例中,所指定的 elem_name 會在建立訊息時,指定 SOAP 元素的名稱。

註:
若所呼叫之資料處理常式傳回的元素值是已編碼的文字, 則 type_name 內容必須設定為 base64Binary,type_ns 必須對應 xsd 名稱空間, 而 xsdtype 必須設定為 true

xsd:base64Binary

當您設定 type_name 及 type_ns 來解析成 xsd:base64Binary 時, SOAP 資料處理常式會先從商業物件來將該值編碼,再設定對應元素的值。 資料處理常式使用 Apache API 來查詢 base64Binary 序列化常式的登錄, 將所呼叫之資料處理常式傳回的字串序列化,並設定元素的值。

綱目 complexType 指示元

下面的一節將討論綱目 complexType 指示元對商業物件的影響。指示元包含:

簡式類型的 maxOccurs 及 minOccurs 指示元

maxOccurs 指示元指定元素可出現在複式類型中的次數上限。 minOccurs 指示元指定元素應出現在複式類型中的次數下限。

請參酌下面這個綱目:

<xs:element name="Address" type="Address">
 <xs:complexType name="Address">
      <xs:sequence>
         <xs:element name="AddressLine" type="xsd:string" maxOccurs="10"/>
         <xs:element name="SuiteNumber" type="xsd:string" minOccurs="3"
                              maxoccurs="unbounded"/>
         <xs:element name="City" type="xsd:string"/>
      </xs:sequence>
      </xs:complexType>
 </xs:element>
 

上述範例指出 AddressLine 元素最多可出現在 Address 元素中 10 次, 而 SuiteNumber 元素則必須至少出現 3 次。 對應此綱目的商業物件必須針對具有下列 ASI 的每個 maxoccurs/minoccurs 指示元, 各有一個 N 基數封套物件:

maxOccurs=N;wrapper=true
 

minOccurs=3;wrapper=true;
 

wrapper=true ASI 指示此物件是一個封套,因此不會明確地寫入 SOAP 訊息中。 但是此封套物件中必須有一個簡式類型的子項。在執行時期,為了進行從 SOAP 轉換成商業物件的作業, 資料處理常式會讀取封套的 N 子項物件,並為每個子項物件建立對應的元素。 當執行從商業物件轉換成 SOAP 訊息的作業時,資料處理常式會針對它所遇到的每個元素, 在 N 基數封套中建立子項物件。

對應的 SOAP 商業物件類似 圖 49 所顯示的物件。

圖 49. SOAP 商業物件中之簡式類型 ASI 的 minOccurs 及 maxOccurs


對應於圖 49 中所顯示之商業物件的 SOAP 訊息如下:

<Address xsi:type="ns0:Address">
     <AddressLine xsi:type="xsd:string">Line1</AddressLine>
     <AddressLine xsi:type="xsd:string">Line2</AddressLine>
     <SuiteNumber xsi:type="xsd:string">600</SuiteNumber>
     <SuiteNumber xsi:type="xsd:string">650</SuiteNumber>
     <SuiteNumber xsi:type="xsd:string">700</SuiteNumber>
      <City xsi:type="xsd:string">San Francisco</City>
 </Address>
 

註:
SOAP 資料處理常式處理 maxOccurs 及 minOccurs 指示元的方式是相同的, 不會驗證元素出現次數的上限或下限。 資料處理常式只會提供儲存區結構,以存放具有 maxOccurs 及 minOccurs 指示元之 特定元素的多重實例。 此作業適用於簡式及複式類型。

複式類型的 maxOccurs 及 minOccurs 指示元

<maxOccurs> 指示元指定元素可出現在複式類型中的次數上限。 <minOccurs> 指示元指定元素應出現在複式類型中的次數下限。 請參酌下列綱目中的 maxOccurs 指示元:

<xs:element name="Address" type="Address">
 <xs:complexType name="Address">
      <xs:sequence>
      <xs:element name="AddressInfo" type="AddressInfo" maxOccurs="3"/>
      <xs:element name="City" type="xsd:string"/>
   </xs:sequence>
   </xs:complexType>
 </xs:element>
  
 <xs:complexType name="AddressInfo">
      <xs:sequence>
      <xs:element name="StreetLine" type="xsd:string"/>
      </xs:sequence>
   </xs:complexType>
 </xs:element>
 

上述範例指出 AddressInfo 複式類型元素最多可出現在 Address 元素中 3 次。 此綱目的對應商業物件將不會有封套物件,因為 complexType AddressInfo 本身即屬於 N 基數。 下列 ASI 將會置於 N 基數屬性中:maxoccurs=3

圖 50 顯示對應的 SOAP 商業物件。

圖 50. SOAP 商業物件中之複式類型 ASI 的 minOccurs 及 maxOccurs


對應於 圖 50 中所顯示之商業物件的 SOAP 訊息如下:

<Address xsi:type="ns0:Address">
      <AddressInfo xsi:type="ns0:AddressInfo">
         <StreetLine xsi:type="xsd:string">100 Market St.</ StreetLine>
         <StreetLine xsi:type="xsd:string">Apt 15</ StreetLine>
      </AddressInfo>
   <City xsi:type="xsd:string">San Francisco</City>
 </Address>
 

all 指示元

依預設,all 指示元指定此 complexType 的子元素可以任何順序出現, 而每個子元素必須出現零或一次。請參酌下列綱目:

<complexType name="Item">
      <all>
         <element name="quantity" type="xsd:int"/>
         <element name="product" type="xsd:string"/>
      </all>
 </complexType>
 

上述範例指示元素 quantityproduct 可於 SOAP 訊息中,以任何順序出現。 quantity 元素可先出現,然後出現 product 元素,反之亦然。

圖 51 顯示對應於此綱目片段的商業物件。

圖 51. SOAP 商業物件中 ALL 指示元 ASI


對應的 SOAP 訊息片段如下:

<Item xsi:type="ns0:Item">
     <quantity xsi:type="xsd:string">12</quantity>
     <product xsi:type="xsd:string">2</product>
 </Item>
 

sequence 指示元

sequence 指示元指定子元素必須以 complexType 中所指定的順序出現。

<complexType name="Item">
      <sequence>
         <element name="quantity" type="int"/>
         <element name="product" type="string"/>
      </sequence>
 </complexType>
 

SOAP 資料處理常式不需要特殊的 ASI,或是此指示元的封套物件。 依預設,資料處理常式會以商業物件中所指定的順序來讀取及寫入 SOAP 元素。

choice 指示元

choice 指示元指定僅有其中一個 complexType 中的元素可出現於 SOAP 訊息中。 請參酌下列綱目:

<complexType name="Item">
     <choice>
         <element name="quantity" type="int"/>
         <element name="product" type="string"/>
     </choice>
 </complexType>
 

SOAP 資料處理常式不需要特殊的 ASI,或是此指示元的封套物件。 將商業物件轉換為 SOAP 訊息時,資料處理常式會延遲,讓您選擇哪些元素應出現在 SOAP 訊息中。 將 SOAP 訊息轉換成商業物件時,資料處理常式會讀取現有的元素,並移入其所對應的屬性。

從 SOAP 轉換成商業物件之作業中的 ASI

SOAP 資料處理常式使用商業物件的 ASI 來讀取及驗證送入的 SOAP 訊息。 以下為 SOAP 資料處理常式用來進行 ASI 驗證的規則:

註:
除非另有說明,否則下面一節中討論的所有 ASI,皆為屬性層次 ASI。

elem_name 驗證

下列規則適用於簡式、基數 1 及基數 n 屬性的驗證工作:

  1. 若於剖析 SOAP 訊息時遇到元素,資料處理常式將先搜尋商業物件層次的所有 ASI, 並嘗試將元素的名稱與 elem_name 值做比對。
  2. 若找不到相符項,資料處理常式會嘗試將元素的名稱與該商業物件層次的每個屬性名稱做比對。
  3. 若所有搜尋皆不成功,資料處理常式即失敗。

elem_ns 驗證

下列案例適用於簡式、基數 1 及基數 n 屬性的驗證工作:

  1. 若此元素的 SOAP 訊息中沒有 elem_ns ASI,xmlns 亦不存在,則此元素已驗證完成。
  2. 若 elem_ns ASI 不存在,且 SOAP 訊息的對應元素指定了 xmlns, 則資料處理常式會將 elem_ns 預設成從範圍中之商業物件讀取的最後一個 elem_ns。 資料處理常式會將此值與 SOAP 訊息的 xmlns 值比較。 若無相符的項目,驗證作業就會失敗。
  3. 若 elem_ns ASI 確實存在,且 SOAP 訊息的對應元素未指定 xmlns, 資料處理常式會驗證 ASI 中指定的 elem_ns 與 SOAP 訊息現行範圍中的其中一個名稱空間相符。 若無相符的項目,驗證作業就會失敗。

type_name 及 type_ns 驗證

下面的一節將會討論 type_name 及 type_ns 驗證作業。

簡式屬性

若 xsdType 為 true,則下列規則適用於 type_name 及 type_ns 驗證作業:

若 xsdType 為 false,則下列規則適用於 type_name 及 type_ns 驗證作業:

複式屬性 (基數 1 及 n)

若 xsdType 為 true,則下列規則適用於 type_name 及 type_ns 驗證作業:

若 xsdType 為 false,則下列規則適用於 type_name 及 type_ns 驗證作業:

attr_name 及 attr_ns 驗證

將 SOAP 訊息讀入商業物件時,會在每個 SOAP 元素中搜尋 SOAP 屬性。 若找到了,則將這些屬性與對應 BO 的 attr_name 內容值做比較。 例如,您可參酌下面這個 SOAP 訊息:

<CustInfo City="4" State="5" Street="2" Zip="6">
    <Name xsi:type="xsd:string">1</Name>
    <Street2 xsi:type="xsd:string">3</Street2>
 </CustInfo>
 

現在請參照圖 52 中所顯示的商業物件定義結構 (屬性層次 ASI 指定在每個屬性的右邊)。

圖 52. attr_name 及 attr_ns 驗證


資料處理常式將遵循下列處理步驟:

  1. 讀取元素名稱 CustInfo。
  2. 解析對應於此元素名稱的商業物件屬性。
  3. 讀取 SOAP 元素的屬性,並嘗試將其與子屬性的 ASI 做比對。 於此案例中,SOAP 訊息 Street 要比對商業物件屬性 Street1, City 要比對商業物件屬性 City,以此類推。
  4. 讀取和處理 CustInfo 之子元素的方式與主體的其餘部份一樣。

註:
未驗證 attr_ns。

資料處理常式會在所有 SOAP 屬性中巡迴,尋找給定的元素。 每遇到一個屬性,資料處理常式就會在商業物件中搜尋對應的屬性。 若找到了,則將該 SOAP 屬性的值移入商業物件屬性。 若找不到對應的商業物件屬性,資料處理常式就會繼續尋找下一個 SOAP 屬性。

從 SOAP 資料處理常式中呼叫資料處理常式

SOAP 資料處理常式可以使用另一個資料處理常式, 將已編碼的元素值從 SOAP 訊息讀取至商業物件中。 例如,RNIF 文件可能是將 SOAP 元素值編碼的其中一種格式。 若要使用此功能,可於任何層次的 SOAP 子項商業物件中,新增 RNIF 商業物件。 若要對 SOAP 資料處理常式表示,在將此 RNIF 編碼的「字串」轉換成 RNIF 商業物件時, 必須使用另一個資料處理常式,則您必須將 dh_mimetype 內容新增至屬性的 ASI。 dh_mimetype ASI 的值應是指定於 MO_DataHandler_Default 商業物件中的合法 mimeType。 mimeType 可用來決定要用哪個資料處理常式來處理「字串」。 例如,下列的 SOAP 訊息,其中 RNIFExample 是包含 RNIF 編碼「字串」的 SOAP 元素:

<CustInfo>
 <Name>IBM Corporation</Name>
 <CustID>95626</CustID>
 <RNIFexample xsi:type="xsd:base64Binary">
 1AWERYER238W98EYR9238728374871892787ASRJK234234JKAWER
 J234AWERIJHI423488R4HASF1AWERYER238W98EYR923872837487
 1892787ASRJK234234JKAWERJ234AWERIJHI423488R4HASF1AWER
 YER238W98EYR9238728374871892787ASRJK234234JKAWERJ234A
 WERIJHI423488R4HASF1AWERYER238W98EYR92387283748718927
 87ASRJK234234JKAWERJ234AWERIJHI423488R4HASFWR234
 </RNIFexample>
 </CustomerInfo>
  
 

SOAP 商業物件看起來如圖 53 所顯示。

圖 53. RNIFExample 商業物件


請注意,RNIFExample 元素包含 RNIF 編碼的「字串」,以作為其元素值。 另請注意,elem_name、elem_ns、type_name、type_ns 及 xsdtype ASI 內容仍會為 此商業物件屬性保持其關聯性。

註:
若所呼叫之資料處理常式傳回的元素值為已編碼的文字,則 type_name 內容 必須設定為 base64Binary,type_ns 必須對應 xsd 名稱空間,而 xsdtype 必須設定為 true。

預設商業物件解析

為了進行由 SOAP 轉換為商業物件的作業,SOAP 資料處理常式及 Web 服務連接器會 遵循一個特殊的交換資訊合約,解析商業物件名稱。 連接器會為 SOAP 資料處理常式,提供一個對映至 BodyName 和 BodyNamespace 配對的 商業物件名稱清單。 此外,若 TLO 中設定了 defaultfault 商業物件,則將此資訊傳遞給資料處理常式。 在已提供此資訊的情況下,SOAP 資料處理常式會使用下列步驟來進行處理程序:

  1. 資料處理常式接收 SOAP 訊息
  2. 資料處理常式要判斷此為 SOAP 要求、回應或錯誤訊息。
    1. 若為 SOAP 要求或回應訊息,資料處理常式便會從 SOAP-ENV:Body 元素的第一個 子元素來讀取 BodyName 及 BodyNamespace。
    2. 若為 SOAP 錯誤訊息,資料處理常式便會從錯誤訊息中之 detail 元素的第一個子 元素來讀取 BodyName 及 BodyNamespace。 若錯誤訊息中沒有 detail 元素,資料處理常式就會使用 defaultfault 商業物件來進行此轉換作業。
  3. 若尚未選取 defaultfault 商業物件,資料處理常式便會嘗試將在步驟 2 中 所找到的 BodyName 和 BodyNamespace,與在連接器所提供之清單中找到的配對做比對。 若找到了相符的配對,則商業物件解析作業成功。若未找到相符的配對, 則資料處理常式失敗,並產生一則有意義的錯誤訊息。

Copyright IBM Corp. 1997, 2003