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 文件。
符號慣例
名稱空間字首 | 名稱空間 |
---|---|
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 檔。
- 套件到名稱空間的對映:
JAX-RPC 規格未指出 Java 套件名稱到 XML 名稱空間的預設對映。JAX-RPC 規格指定每一個 Java 套件必須對映到單一 XML 名稱空間。 同樣地,每一個 XML 名稱空間必須對映到單一 Java 套件。提供的預設對映演算法會反轉 Java 套件的名稱並加上 http:// 字首,以建構名稱空間。例如,名為 com.ibm.webservice 的套件會對映到 XML 名稱空間 http://webservice.ibm.com。
您可以使用 WSDL2Java 和 Java2WSDL 指令的 -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 - Binding 和 service 建構
產生的 wsdl:binding 符合已產生的 wsdl:portType。產生的 wsdl:service 包含一個埠,此埠參照到已產生的 wsdl:binding。 連結和服務的名稱由 Java2WSDL 指令控制。
- Style 和 use使用 -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/foo 和 http://websphere.ibm.com/bar 對映到 com.ibm.websphere Java 套件。您可以使用 WSDL2Java 和 Java2WSDL 指令的 -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。
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 附件的作業訊息組件會變成為附件類型的參數,而無論所宣告的組件是什麼。例如:
JAX-RPC 規格需要支援下列 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) ...
表 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
- MIME 附件:
- wsdl:service 的對映:
wsdl:service 元素對映到產生的服務介面。產生的服務介面包含方法來存取 wsdl:service 元素中每個埠。 JAX-RPC 規格第 4.3.9 節、第 4.3.10 節和第 4.3.11 節討論產生的服務介面。
此外,wsdl:service 會對映到專用於實作的 ServiceLocator 類別,此類別實作產生的服務介面。
- JAX-RPC 簡式 XML 類型對映:
請參閱「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 屬性。
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>