JAX-WS 2.0 代碼優先開發 Web 服務教程：從設計到客戶端調用

教程目標

掌握使用 JAX-WS 2.0（JSR 224）代碼優先方式設計、開發、發布、調用 Web 服務。環境：Java SE 6.0（內置輕量級 HTTP 服務器與 wsgen/wsimport 工具）。

JAX-WS 核心優勢

• 完整 Web 服務棧，簡化開發部署。
• 支持 WS-I Basic Profile 1.1，保證跨語言互操作。
• 內置 JAXB（XML↔Java 綁定）與 SAAJ（SOAP 附件處理）。
• Annotation 驅動：POJO 即服務，@WebService、@WebMethod、@SOAPBinding。
• WSDL 與 Java 類雙向映射，複雜類型遵循 JAXB 規範。

開發訂單處理 Web 服務

1. 領域對象 OrderBean

package com.ibm.jaxws.tutorial.service.bean;

public class OrderBean {
    private Customer customer;
    private Address shippingAddress;
    private OrderItem[] orderItems;
    private String orderId;
    // Getter/Setter 省略
}

2. 服務實現 OrderProcessService

package com.ibm.jaxws.tutorial.service;

import javax.jws.WebMethod;
import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;
import com.ibm.jaxws.tutorial.service.bean.OrderBean;

@WebService(serviceName = "OrderProcess",
            portName = "OrderProcessPort",
            targetNamespace = "https://jawxs.ibm.tutorial/jaxws/orderprocess")
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT,
             use = SOAPBinding.Use.LITERAL,
             parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
public class OrderProcessService {

    @WebMethod
    public OrderBean processOrder(OrderBean orderBean) {
        System.out.println("processOrder called for customer " + orderBean.getCustomer().getCustomerId());
        if (orderBean.getOrderItems() != null) {
            System.out.println("Number of items is " + orderBean.getOrderItems().length);
        }
        orderBean.setOrderId("A1234");
        return orderBean;
    }
}

生成構件並發布

1. 編譯源碼：
   javac com/ibm/jaxws/tutorial/service/*.java com/ibm/jaxws/tutorial/service/bean/*.java
2. 生成 JAX-WS 構件（含 WSDL/XSD）：
   wsgen -cp . com.ibm.jaxws.tutorial.service.OrderProcessService -wsdl
   產生 OrderProcess.wsdl、OrderProcess_schema1.xsd 及 jaxws 包裝類。
3. 發布服務（利用 JDK 內置 Endpoint）：
   java com.ibm.jaxws.tutorial.service.publish.OrderWebServicePublisher
   輸出：The Web service is published at https://localhost:8080/OrderProcessWeb/orderprocess
4. 驗證 WSDL：瀏覽器訪問 https://localhost:8080/OrderProcessWeb/orderprocess?wsdl

發布器代碼

package com.ibm.jaxws.tutorial.service.publish;
import javax.xml.ws.Endpoint;
import com.ibm.jaxws.tutorial.service.OrderProcessService;

public class OrderWebServicePublisher {
    public static void main(String[] args) {
        Endpoint.publish("https://localhost:8080/OrderProcessWeb/orderprocess",
                         new OrderProcessService());
    }
}

WSDL 深度解析

• <types> 導入 OrderProcess_schema1.xsd，目標命名空間與 @WebService.targetNamespace 一致。
• 包裝元素 processOrder/processOrderResponse 對應包裝類 ProcessOrder/ProcessOrderResponse。
• orderBean 複雜類型映射 OrderBean，包含 customer、orderId、orderItems（maxOccurs=unbounded）、shippingAddress。
• 消息定義、portType、binding（document/literal）、service 端點地址均自動生成，符合 @SOAPBinding 規範。

客戶端開發

1. 從 WSDL 生成客戶端構件：
   wsimport -keep -p com.ibm.jaxws.tutorial.service.client https://localhost:8080/OrderProcessWeb/orderprocess?wsdl
   產生：JAXB 類、包裝類、OrderProcess 服務類、OrderProcessService SEI。
2. 客戶端調用代碼：

package com.ibm.jaxws.tutorial.service.client;

import java.net.URL;
import javax.xml.namespace.QName;

public class OrderClient {
    private static final QName QNAME = new QName(
        "https://jawxs.ibm.tutorial/jaxws/orderprocess", "OrderProcess");

    public static void main(String[] args) {
        if (args.length != 1) {
            System.out.println("Specify the URL of the OrderProcess Web Service");
            System.exit(-1);
        }
        try {
            URL wsdlUrl = new URL(args[0]);
            OrderProcess service = new OrderProcess(wsdlUrl, QNAME);
            OrderProcessService port = service.getOrderProcessPort();

            OrderBean order = new OrderBean();
            Customer customer = new Customer();
            customer.setCustomerId("A123");
            customer.setFirstName("John");
            customer.setLastName("Smith");
            order.setCustomer(customer);

            OrderItem item = new OrderItem();
            item.setItemId("11");
            item.setQty(11);
            order.getOrderItems().add(item);

            OrderBean response = port.processOrder(order);
            System.out.println("Order id is " + response.getOrderId());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

運行驗證

1. 編譯客戶端：javac com/ibm/jaxws/tutorial/service/client/OrderClient.java
2. 運行：java com.ibm.jaxws.tutorial.service.client.OrderClient https://localhost:8080/OrderProcessWeb/orderprocess?wsdl
3. 服務端控制台輸出：
   processOrder called for customer A123
Number of items is 1
4. 客戶端輸出：Order id is A1234

總結

JAX-WS 2.0 代碼優先模式讓開發者專注於 Java 類設計，通過 Annotation 生成標準 WSDL/XSD，wsgen/wsimport 自動處理構件生成，Endpoint.publish 快速測試。Document/Literal 風格適合企業級服務契約。客戶端完全屏蔽 SOAP/XML 細節，操作 JAXB 對象即可。