JAX-RPC 應用程式的 Java 語言、WSDL 和 XML 之間的對映

Java™ API for XML-based Remote Procedure Call (JAX-RPC) 應用程式的資料以延伸標記語言 (XML) 的形式傳遞。JAX-RPC 應用程式使用對映來說明 Java 語言和延伸標記語言 (XML) 技術之間的資料轉換,包括應用程式伺服器支援的 XML 綱目、Web 服務說明語言 (WSDL) 和 SOAP。

對於 JAX-RPC 應用程式,Java 語言與 XML 之間的大部分對映是由 JAX-RPC 規格指定。 也支援選用的或 JAX-RPC 中未指定的對映。如需完整的 API 清單,請檢閱 JAX-RPC 規格。如需支援的標準和規格的完整清單,請參閱 Web 服務規格與 API 文件。

符號慣例

表 1. 名稱空間慣例. 說明名稱空間慣例中使用的名稱空間字首和對應的名稱空間。
名稱空間字首 名稱空間
xsd http://www.w3.org/2001/XMLSchema
xsi http://www.w3.org/2001/XMLSchema-instance
soapenc http://schemas.xmlsoap.org/soap/encoding/
wsdl http://schemas.xmlsoap.org/wsdl/
wsdlsoap http://schemas.xmlsoap.org/wsdl/soap/
ns user-defined namespace
apache http://xml.apache.org/xml-soap
wasws http://websphere.ibm.com/webservices/

詳細對映資訊

下列各節識別支援的對映,包括:

Java 到 WSDL 的對映

本節彙總 Java 到 WSDL 的對映規則。Java2WSDL 指令使用 Java 到 WSDL 的對映規則執行由下而上處理。在由下而上處理中會使用現有的 Java 服務實作,建立一個定義 Web 服務的 WSDL 檔。由於下列原因,可能需要另外以手動方式編輯產生的 WSDL 檔:
  • 並不是所有 Java 類別和建構都對應到 WSDL 檔。例如,不符合 Java Bean 規格規則的 Java 類別可能未對映到 WSDL 建構。
  • 部分 Java 類別和建構會多次對映到 WSDL 檔。 例如,java.lang.String 類別可能對映到 xsd:string 或 soapenc:string 建構。 Java2WSDL 指令會選擇其中一個對映,但如果需要不同的對映,您必須編輯 WSDL 檔。
  • 產生 WSDL 建構有多種方式。例如,您可以在 wsdl:message 中使用 type 或 element 屬性來產生 wsdl:part。 Java2WSDL 指令會根據 -style 和 -use 選項設定來做出明智的選擇。
  • WSDL 檔說明 SOAP 訊息中傳送的實例資料元素。如果您想要修改訊息中使用的名稱或格式,則必須編輯 WSDL 檔。 例如,Java2WSDL 指令會將 Java Bean 內容對映成 XML 元素。在某些情況下,您可能會變更 WSDL 檔將 Java Bean 內容對映成 XML 屬性。
  • 如果需要標頭或附件支援,則需要編輯 WSDL 檔。
  • 如果需要多組件 WSDL 檔(使用 wsdl:import 建構),則需要編輯 WSDL 檔。
對於簡單的服務而言,產生的 WSDL 檔已足夠。對於複雜的服務而言,產生的 WSDL 檔是很好的起點。 請參閱「Java API for XML-based Remote Procedure Call (JAX-RPC) 應用程式的 Java2WSDL 指令行工具」,以進一步瞭解此工具。
一般問題
  • 套件到名稱空間的對映:

    JAX-RPC 規格未指出 Java 套件名稱到 XML 名稱空間的預設對映。JAX-RPC 規格指定每一個 Java 套件必須對映到單一 XML 名稱空間。 同樣地,每一個 XML 名稱空間必須對映到單一 Java 套件。提供的預設對映演算法會反轉 Java 套件的名稱並加上 http:// 字首,以建構名稱空間。例如,名為 com.ibm.webservice 的套件會對映到 XML 名稱空間 http://webservice.ibm.com

    您可以使用 WSDL2JavaJava2WSDL 指令的 -NStoPkg 和 -PkgtoNS 選項,置換 XML 名稱空間與 Java 套件名稱之間的預設對映。

  • ID 對映:

    Java ID 直接對映到 WSDL 和 XML ID。

    Java Bean 內容名稱對映到 XML ID。 例如,含有 getInfo 和 setInfo 方法的 Java Bean 對映到名稱為 info 的 XML 建構。

    服務端點介面方法參數名稱(如果有的話)直接對映到 WSDL 和 XML ID。如需進一步瞭解,請參閱 WSDL2Java 指令 -implClass 選項的資訊。

  • WSDL 建構摘要:
    表 2. Java 到 WSDL 或 XML 建構的對映. 說明從 Java 建構到相關 WSDL 和 XML 建構的對映。
    Java 建構 WSDL 和 XML 建構
    服務端點介面 wsdl:portType
    方法 wsdl:operation
    參數 wsdl:input、wsdl:message、wsdl:part
    傳回 wsdl:output、wsdl:message、wsdl:part
    擲出 wsdl:fault、wsdl:message、wsdl:part
    初始類型 xsd 和 soapenc 簡式類型
    Java Bean xsd:complexType
    Java Bean 內容 xsd:complexType 的巢狀 xsd:elements
    陣列 JAX-RPC 定義的 xsd:complexType 或 xsd:element,具有 maxOccurs="unbounded" 屬性
    使用者定義的異常狀況 xsd:complexType
  • Bindingservice 建構

    產生的 wsdl:binding 符合已產生的 wsdl:portType。產生的 wsdl:service 包含一個埠,此埠參照到已產生的 wsdl:binding。 連結和服務的名稱由 Java2WSDL 指令控制。

  • Styleuse
    使用 -style 和 -use 選項產生不同類型的 WSDL 檔。支援的四種組合包括:
    • -style DOCUMENT -use LITERAL
    • -style RPC -use LITERAL
    • -style DOCUMENT -use LITERAL -wrapped false
    • -style RPC -use ENCODED
    以下是每一種組合的簡要說明。
    • DOCUMENT LITERAL:

      Java2WSDL 指令會產生符合 Web 服務 - 交互作業能力 (WS-I) 規格的 document-literal WSDL 檔。 產生的 wsdl:binding 具有內嵌的 style="document" 和 use="literal" 屬性。針對每一個服務端點介面方法產生 xsd:element 來說明要求訊息。 針對每一個服務端點介面方法產生類似的 xsd:element 來說明回應訊息。

    • RPC LITERAL:

      Java2WSDL 指令會產生符合 WS-I 的 rpc-literal WSDL 檔。產生的 wsdl:binding 具有內嵌的 style="rpc" 和 use="literal" 屬性。 針對每一個服務端點介面方法的輸入及輸出產生 wsdl:message 建構。wsdl:message 建構內的 part 元素說明方法的參數。

    • DOCUMENT LITERAL 不包裝:

      Java2WSDL 指令會根據 JAX-RPC 規格產生 document-literal WSDL 檔。 此 WSDL 檔不符合 .NET。DOCUMENT LITERAL 和 DOCUMENT LITERAL 不包裝的主要差異在於是否使用 wsdl:message 建構來定義要求和回應訊息。

    • RPC ENCODED:

      Java2WSDL 指令會根據 JAX-RPC 規格產生 rpc 編碼的 WSDL 檔。 此 WSDL 檔不符合 WS-I 規格。產生的 wsdl:binding 具有內嵌的 style="rpc" 和 use="encoded" 屬性。 使用某些 soapenc 對映來代表類型和陣列。

    許多 Java 類型直接對映到標準 XML 類型。例如,java.lang.String 對映到 xsd:string。 JAX-RPC 規格中說明這些對映。

    wsdl:types 區段中會產生無法直接對映到標準 XML 類型的 Java 類型。 符合 Java Bean 型樣的 Java 類別對映到 xsd:complexType。如需所有對映規則的說明,請檢閱 JAX-RPC 規格。 下列範例說明基本和衍生 Java 類別範例的對映。
    Java:
    
    
    public abstract class Base {  
         public Base() {}  
         public int a;                         // mapped  
         private int b;                        // mapped via setter/getter  
         private int c;                        // not mapped  
         private int[] d;                      // mapped via indexed setter/getter  
    
         public int getB() { return b;}        // map property b  
         public void setB(int b) {this.b = b;}  
    
         public int[] getD() { return d;}      // map indexed property d  
         public void setD(int[] d) {this.d = d;}  
         public int getD(int index) { return d[index];}  
         public void setB(int index, int value) {this.d[index] = value;}  
    
         public void someMethod() {...}        // not mapped  
      }  
    
      public class Derived extends Base {  
         public int x;                         // mapped  
         private int y;                        // not mapped  
      } 
    
    對映到:
    
    <xsd:complexType name="Base" abstract="true">  
    	<xsd:sequence>
    		<xsd:element name="a" type="xsd:int"/> 
    		<xsd:element name="b" type="xsd:int"/> 
    		<xsd:element name="d" minOccurs="0" maxOccurs="unbounded" type="xsd:int"/>
    	</xsd:sequence>
    </xsd:complexType>                                                                             
    
    <xsd:complexType name="Derived">  
    	<xsd:complexContent>
    		<xsd:extension base="ns:Base"> 
    			<xsd:sequence>
    				<xsd:element name="x" type="xsd:int"/>
    			</xsd:sequence>
    		</xsd:extension>
    	</xsd:complexContent>
    </xsd:complexType>                                                                             
        
    
  • 不支援的類別:

    如果類別無法對映到 XML 類型,Java2WSDL 指令會發出訊息,並於 WSDL 檔中產生 xsd:anyType 參照。 在這些情況下,請修改 Web 服務實作來使用符合 JAX-RPC 的類別。

WSDL 到 Java 的對映

WSDL2Java 指令會使用 WSDL 檔中所述的資訊產生 Java 類別。

一般問題:
  • 名稱空間到套件的對映:

    JAX-RPC 不指定 XML 名稱空間到 Java 套件名稱的對映。JAX-RPC 指定每一個 Java 套件對映到單一 XML 名稱空間。同樣地,每一個 XML 名稱空間必須對映到單一 Java 套件。預設對映演算法會省略來自 XML 名稱空間的任何通訊協定,並反轉名稱。 例如,XML 名稱空間 http://websphere.ibm.com 會變成名稱為 com.ibm.websphere 的 Java 套件。

    XML 名稱空間到 Java 套件的預設對映不處理環境定義根目錄。如果兩個名稱空間在第一個斜線之前都相同,則對映到相同的 Java 套件。 例如,XML 名稱空間 http://websphere.ibm.com/foohttp://websphere.ibm.com/bar 對映到 com.ibm.websphere Java 套件。您可以使用 WSDL2JavaJava2WSDL 指令的 -NStoPkg 和 -PkgtoNS 選項,置換 XML 名稱空間與 Java 套件名稱之間的預設對映。

    XML 名稱比 Java ID 更豐富。它們可以包含 Java ID 中不允許的字元。請參閱 JAX-RPC 規格的附錄 20,以瞭解 XML 名稱到 Java ID 的對映規則。

  • Java 建構摘要:
    下表彙總 XML 到 Java 建構。如需這些對映的說明,請參閱 JAX-RPC 規格。
    表 3. WSDL 或 XML 建構到 Java 的對映. 說明 XML 和 Java 建構之間的對映。
    WSDL 和 XML 建構 Java 建構
    xsd:complexType Java Bean 類別、Java 異常狀況類別或 Java 陣列
    巢狀 xsd:element/xsd:attribute Java Bean 內容
    xsd:simpleType(列舉) JAX-RPC 列舉類別
    wsdl:message 通常由 wsdl:message 決定方法參數簽章。 服務端點介面方法簽章
    wsdl:portType 服務端點介面
    wsdl:operation 服務端點介面方法
    wsdl:binding Stub
    wsdl:service 服務介面
    wsdl:port 服務介面中的埠 accessor 方法
  • 對映標準 XML 類型:
    • JAX-RPC 簡式 XML 類型對映:

      許多 XML 類型直接對映到 Java 類型。如需這些對映的說明,請參閱 JAX-RPC 規格。

      WSDL2Java 指令會為 wsdl:types 區段中定義的 XML 綱目建構產生 Java 類型。XML 綱目語言比 JAX-RPC 規格中定義的必要或選用子集更廣泛。WSDL2Java 指令支援必要對映和大部分的選用對映,以及 JAX-RPC 規格中未包括的某些 XML 綱目對映。 WSDL2Java 指令會忽略它不支援的一些建構。例如,此指令不支援 default 屬性。如果定義的 xsd:element 具有 default 屬性,則會忽略 default 屬性。 在某些情況下,此指令會將不支援的建構對映到 Java 介面 javax.xml.soap.SOAPElement。

      JAX-RPC 規格第 4.2.3 節定義標準的 Java Bean 對映。xsd:complexType 定義類型。xsd:sequence 或 xsd:all 群組內的巢狀 xsd:element 對映到 Java Bean 內容。例如:
      XML:
      
       
      <xsd:complexType name="Sample">
      	 <xsd:sequence>
      		<xsd:element name="a" type="xsd:string"/>
      		<xsd:element name="b" maxOccurs="unbounded" type="xsd:string"/> 
      	</xsd:sequence>
      </xsd:complexType>                                                                             
      
      Java:    
        
      public class Sample {  
           // ..  
           public Sample() {}  
      
           // Bean Property a  
           public String getA()             {...}  
           public void   setA(String value) {...}  
      
           // Indexed Bean Property b  
           public String[] getB()           {...}  
           public String   getB(int index)  {...}  
           public void     setB(String[] values) {...}  
           public void     setB(int index, String value) {...}  
      
        }
      
    • wsdl:portType 建構的對映:

      wsdl:portType 建構對映到服務端點介面。wsdl:portType 建構的名稱對映到服務端點介面的類別名稱。

    • wsdl:operation 建構的對映:
      wsdl:portType 內的 wsdl:operation 建構對映到服務端點介面的方法。 wsdl:operation 的名稱對映到方法的名稱。wsdl:operation 包含 wsdl:input 和 wsdl:output 元素,這些元素使用 message 屬性來參照要求和回應 wsdl:message 建構。 wsdl:operation 可以包含 wsdl:fault 元素,此元素參照說明該錯誤的 wsdl:message。這些錯誤對映到延伸 java.lang.Exception 異常狀況的 Java 類別,如 JAX-RPC 規格第 4.3.6 節所討論。
      • 文件文字包裝格式的效果:
        如果 WSDL 檔使用文件文字包裝格式,則會從封套 xsd:element 對映方法參數。WSDL2Java 指令會自動偵測文件文字包裝和文字格式。 必須符合下列準則:
        • WSDL 檔的 wsdl:binding 建構內必須有 style="document"。
        • wsdl:binding 內的 operation 的 input 和 output 建構必須包含 soap:body 元素,而此元素包含 use="literal"。
        • wsdl:operation input 建構所參照的 wsdl:message 必須只有單一組件。
        • 此組件必須使用 element 屬性來參照 xsd:element。
        • 被參照的 xsd:element(即封套元素)必須與 wsdl:operation 同名。
        • 封套元素不能包含任何 xsd:attribute。
        在此情況下,每一個參數名稱都對映自封套元素內包含的巢狀 xsd:element。參數的類型對映自巢狀 xsd:element 的類型。例如:
        WSDL:
        
        <xsd:element name="myMethod"> 
        	<xsd:complexType>
        		<xsd:sequence>
        			<xsd:element name="param1" type="xsd:string"/>
        			<xsd:element name="param2" type="xsd:int"/> 
        		</xsd:sequence>
        	</xsd:complexType>                                                                             
        </xsd:element>
        ... 
        <wsdl:message name="response"/> 
        	<part name="parameters" element="ns:myMethod"/> 
        </wsdl:message name="response"/> 
        
        <wsdl:message name="response"/>
        ...
        <wsdl:operation name="myMethod"> 
        	<input name="input" message="request"/>  
        	<output name="output" message="response"/>  
        </wsdl:operation>
        
        Java: 
        
        void myMethod(String param1, int param2) ... 
      • 參數對映:

        如果未偵測到文件和文字包裝格式,則參數對映遵循 JAX-RPC 規格第 4.3.4 節所規定的一般 JAX-RPC 對映規則。

        每一個參數由參照自 input 和 output 元素的 wsdl:message 組件定義。
        • 要求 wsdl:message 中的 wsdl:part 對映到 input 參數。
        • 回應 wsdl:message 中的 wsdl:part 對映到回覆值。如果回應訊息中存在多個 wsdl:part,它們會對映到 output 參數。
          • 針對每一個 output 參數產生 Holder 類別,如 JAX-RPC 規格第 4.3.5 節所討論。
        • 同時為要求和回應 wsdl:message 的 wsdl:part 對映到 inout 參數。
          • 針對每一個 inout 參數產生 Holder 類別,如 JAX-RPC 規格第 4.3.5 節所討論。
          • wsdl:operation parameterOrder 屬性定義參數的順序。
        XML:
        
        <wsdl:message name="request">
        	<part name="param1" type="xsd:string"/>
        	<part name="param2" type="xsd:int"/>
        </wsdl:message name="response"/>
        
        <wsdl:message name="response"/>  
        ...
        <wsdl:operation name="myMethod" parameterOrder="param1, param2">
        	<input name="input" message="request"/>
        	<output name="output" message="response"/>
        </wsdl:operation>
        
        
        Java: 
        
        void myMethod(String param1, int param2) ... 
    • wsdl:binding 的對映:
      WSDL2Java 指令會使用 wsdl:binding 資訊來產生專用於實作的用戶端 Stub。WebSphere® Application Server 會使用伺服器端的 wsdl:binding 資訊,適當地將要求解除序列化、呼叫 Web 服務,以及將回應序列化。 wsdl:binding 中的資訊不影響服務端點介面的產生,除非使用文件和文字包裝格式,或 MIME 附件存在。
      • MIME 附件:
        對於符合 WSDL 1.1 的 WSDL 檔,在連結中定義為 MIME 附件的作業訊息組件會變成為附件類型的參數,而無論所宣告的組件是什麼。例如:
        XML:
        <wsdl:types>
        	<schema ...>
        		<complexType name="ArrayOfBinary">
        			<restriction base="soapenc:Array">
        			  <attribute ref="soapenc:arrayType" wsdl:arrayType="xsd:binary[]"/>
        			</restriction>
        		</complexType>
        	</schema>
        </wsdl:types>
        
        <wsdl:message name="request">
        	<part name="param1" type="ns:ArrayOfBinary"/>
        <wsdl:message name="response"/>
        
        <wsdl:message name="response"/>
         ... 
        
        	<wsdl:operation name="myMethod">
        		<input name="input" message="request"/>
        		<output name="output" message="response"/>
        	</wsdl:operation>
          ...
        
        <binding ...  
        	<wsdl:operation name="myMethod">
        				<input>
        			<mime:multipartRelated> 
        				<mime:part>
        					<mime:content part="param1" type="image/jpeg"/>
        				</mime:part>
        			</mime:multipartRelated>
        		</input>
        		 ...
        	</wsdl:operation>
        
        Java: 
        
        void myMethod(java.awt.Image param1) ... 
        JAX-RPC 規格需要支援下列 MIME 類型:
        表 4. MIME 類型和 Java 類型的對映. 說明 MIME 類型和 Java 類型之間的對映。
        MIME 類型 Java 類型
        image/gif java.awt.Image
        image/jpeg java.awt.Image
        text/plain java.lang.String
        multipart/* javax.mail.internet.MimeMultipart
        text/xml javax.xml.transform.Source
        application/xml javax.xml.transform.Source
    • wsdl:service 的對映:

      wsdl:service 元素對映到產生的服務介面。產生的服務介面包含方法來存取 wsdl:service 元素中每個埠。 JAX-RPC 規格第 4.3.9 節、第 4.3.10 節和第 4.3.11 節討論產生的服務介面。

      此外,wsdl:service 會對映到專用於實作的 ServiceLocator 類別,此類別實作產生的服務介面。

請參閱「Java API for XML-based Remote Procedure Call (JAX-RPC) 應用程式的 WSDL2Java 指令行工具」,以進一步瞭解此工具。


WSDL 和 SOAP 訊息之間的對映

WSDL 檔定義透過網路連線傳輸的 SOAP 訊息的格式。 WSDL2Java 指令和 WebSphere Application Server 執行時期會使用 WSDL 檔中的資訊,確保 SOAP 訊息已適當地序列化和解除序列化。

如果 wsdl:binding 元素指出使用 RPC 格式傳送訊息,則 SOAP 訊息會包含一個元素來定義作業。 如果 wsdl:binding 元素指出使用文件格式傳送訊息,則 SOAP 訊息不包含 operation 元素。

如果定義的 wsdl:part 元素使用 type 屬性,訊息中會使用組件的名稱和類型。 如果定義的 wsdl:part 元素使用 element 屬性,訊息中會使用元素的名稱和類型。 當 use="encoded" 時,JAX-RPC 規格不支援 element 屬性。

如果 wsdl:binding 元素指出將訊息編碼,訊息中的值會連同 xsi:type 資訊一起傳送。 如果 wsdl:binding 元素指出訊息為文字,則訊息中的值傳送時通常不附帶 xsi:type 資訊。例如:
DOCUMENT/LITERAL
WSDL:

<xsd:element name="c" type="xsd:int"/>
<xsd:element name="method">
	<xsd:complexType>
		<xsd:sequence>
			<xsd:element name="a" type="xsd:string"/>
			<xsd:element ref="ns:c"/>
		</xsd:sequence>
	</xsd:complexType>                                                                             
</xsd:element>
...
		<wsdl:message name="request">	
				<part name="parameters" element="ns:method"/> 
		</wsdl:message>
	... 
	<wsdl:operation name="method"> 
		<input message="request"/> 
	...

Message:
<soap:body>
		<ns:method>
			<a>ABC</a>
			<c>123</a>
		<ns:method>
</soap:body>
RPC/ENCODED
WSDL: 
<xsd:element name="c" type="xsd:int"/>

...
		<wsdl:message name="request">	
				<part name="a" type="xsd:string"/>
				<part name="b" element="ns:c"/>
		</wsdl:message>
	... 
	<wsdl:operation name="method"> 
				<input message="request"/> 
	...

Message:
<soap:body> 
		<ns:method> 
			<a xsi:type="xsd:string">ABC</a>
			<element attribute is not permitted in rpc/encoded mode> 
		</ns:method>
	</soap:body>
 
DOCUMENT/LITERAL  not wrapped 
WSDL:
<xsd:element name="c" type="xsd:int"/>

...
		<wsdl:message name="request">	
				<part name="a" type="xsd:string"/>
				<part name="b" element="ns:c"/>
		</wsdl:message>
	... 
	<wsdl:operation name="method"> 
				<input message="request"/>

...

Message:
<soap:body>
		<a>ABC</a>
		<c>123</a> 
</soap:body>

指出主題類型的圖示 參照主題



時間戳記圖示 前次更新: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwbs_map
檔名:rwbs_map.html