为 JAX-WS Web Service 启用 MTOM

使用 Java™ API for XML-Based Web Services (JAX-WS),可以将二进制附件(例如图像或文件)与 Web Service 请求一起发送。JAX-WS 添加了对二进制数据进行优化传输的支持,如 SOAP 消息传输优化机制 (MTOM) 规范中所指定。

关于此任务

JAX-WS 支持使用 SOAP 消息传输优化机制 (MTOM) 来发送二进制附件数据。通过启用 MTOM,可以按最优方式发送和接收二进制数据,而不会带来在 XML 文档中嵌入二进制数据所需的数据编码开销。

应用程序服务器仅对 JAX-WS 应用程序支持使用 MTOM 发送附件。此产品也可让您通过使用新的 MTOM 和 XOP 标准,随 Web Service 安全性 SOAP 消息提供附件。

JAX-WS 应用程序可以将二进制数据作为包含在 XML 文档中的 base64 或 hexBinary 编码数据来发送。但是,为了利用 MTOM 所提供的优化,应使 MTOM 能够将二进制 base64 数据作为包含在 XML 文档外部的附件来发送。缺省情况下,不启用 MTOM 优化。JAX-WS 应用程序要求单独配置客户机和服务器工件以便启用 MTOM 支持。

过程

  1. 为 JAX-WS 应用程序开发 Java 工件,该应用程序包含 XML 模式或 Web 服务描述语言 (WSDL) 文件(用于表示包含二进制附件的 Web Service 应用程序数据)。
    1. 如果要从 WSDL 文件开始,那么通过使用 wsimport 命令来生成必需的 JAX-WS 可移植工件,从 WSDL 文件开发 Java 工件
    2. 如果要从 JavaBeans 组件开始,那么为 JAX-WS 应用程序开发 Java 工件以及(可选)使用 wsgen 命令来生成 WSDL 文件。 XML 模式或 WSDL 文件包括二进制数据的 xsd:base64Binaryxsd:hexBinary 元素定义。
    3. 也可以包括元素上的 xmime:expectedContentTypes 属性以通过 JAXB 影响映射。
  2. 使用下列其中一种方法来对端点实现类启用 MTOM:
    • 在端点上使用 @MTOM 注释。

      要对端点启用 MTOM,请在端点上使用 @MTOM (javax.xml.ws.soap.MTOM) 注释。@MTOM 注释具有两个参数 enabledthresholdenabled 参数具有布尔值并表示是否为 JAX-WS 端点启用 MTOM。threshold 参数具有整数值,该值必须大于或等于零。如果已启用 MTOM,那么任何大小(以字节计)超过阈值的二进制数据都会采用 XML 二进制优化打包 (XOP) 进行编码或者作为附件来发送。如果消息大小小于阈值,那么会将消息作为基本 64 位或 hexBinary 数据直接插入 XML 文档。

      以下示例片段说明了添加 @MTOM 注释以便对 JAX-WS MyServiceImpl 端点启用 MTOM,并且 MTOM 指定阈值(2048 个字节):
      @MTOM(enabled=true, threshold=2048)
      @WebService
      public class MyServiceImpl {
      ...
      }
      此外,还可以在端点实现类上使用 @BindingType (javax.xml.ws.BindingType) 注释来指定端点支持其中一种 MTOM 绑定类型,以便响应消息是启用了 MTOM 的消息。javax.xml.ws.SOAPBinding 类定义了两个可用于 @BindingType 注释值的不同常量(SOAP11HTTP_MTOM_BINDINGSOAP12HTTP_MTOM_BINDING);例如:
      // This example is for SOAP version 1.1.
      @BindingType(value = SOAPBinding.SOAP11HTTP_MTOM_BINDING)
      @WebService
      public class MyServiceImpl {
      ...
      }
      // This example is for SOAP version 1.2.
      @BindingType(value = SOAPBinding.SOAP12HTTP_MTOM_BINDING)
      @WebService
      public class MyServiceImpl {
      ...
      }

      @MTOM 注释的存在和值将覆盖 @BindingType 注释的值。例如,如果 @BindingType 指示 MTOM 已启用,但存在的 @MTOM 注释具有的 enabled 值为 false,那么 MTOM 未启用。

    • 使用 <enable-mtom><mtom-threshold> 部署描述符元素。
      可以在 webservices.xml 部署描述符的 <port-component> 元素中使用 <enable-mtom><mtom-threshold> 元素,作为在服务端点实现类上使用 @MTOM 注释的替代选择;例如:
      <port-component>
      			<port-component-name>MyPort1</port-component-name>
      			<enable-mtom>true</enable-mtom>
      						<mtom-threshold>2048</mtom-threshold>
      			<service-impl-bean>
      				<servlet-link>MyPort1ImplBean</servlet-link>
      			</service-impl-bean>
      </port-component>
      避免故障 避免故障: 部署描述符元素优先于 MTOM 注释中的相应属性。例如,如果在注释中将 enabled 属性设置为 true,但在 webservices.xml 文件中将 <enable-mtom> 元素设置为 false,那么未对相应的端点启用 MTOM。gotcha
  3. 对客户机启用 MTOM 以优化从客户机发送到服务器的二进制消息。 使用下列其中一种方法来对客户机启用 MTOM:
    • 对 Dispatch client 启用 MTOM。
      注: 对于 Dispatch client,客户机应用程序需要以优化格式构造 SOAP 消息。

      以下示例使用 SOAP V1.1。

      第一种方法使用 SOAPBinding.setMTOMEnabled();例如:
      SOAPBinding binding = (SOAPBinding)dispatch.getBinding();
          binding.setMTOMEnabled(true);
      第二种方法使用 Service.addPort;例如:
          Service svc = Service.create(serviceName);
          svc.addPort(portName,SOAPBinding.SOAP11HTTP_MTOM_BINDING,endpointUrl); 
      第三种方法使用 MTOMFeature;例如:
         MTOMFeature mtom = new MTOMFeature(true, 2048);
          Service svc = Service.create(serviceName);
          svc.addPort(portName, SOAPBinding.SOAP11_HTTP_BINDING, endpointUrl);
          Dispatch<Source> dsp = svc.createDispatch(portName, Source.class, Service.Mode.PAYLOAD, mtom);
    • 对动态代理客户机启用 MTOM。
      // Create a BindingProvider bp from a proxy port.
        Service svc = Service.create(serviceName);
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        
        //Enable MTOM using the SOAPBinding.
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        SOAPBinding binding = (SOAPBinding) bp.getBinding();
        binding.setMTOMEnabled(true);
      
        //Or, you can enable MTOM with the MTOMFeature.
        MTOMFeature mtom = new MTOMFeature();
        MtomSample proxy = svc.getPort(portName, MtomSample.class, mtom);
    • 使用 @MTOM 注释来对客户机启用 MTOM;例如:
      public class MyClientApplication {
      
          // Enable MTOM for a port-comonent-ref resource injection.
      	    	    @MTOM(enabled=true, threshold=1024)
      	    @WebServiceRef(MyService.class)
      	    private MyPortType myPort;
          ...
      }
    • 在 port-component-ref 元素中使用部署描述符元素来对客户机启用 MTOM;例如:
      <service-ref>
          <service-ref-name>service/MyPortComponentRef</service-ref-name>
          <service-interface>com.example.MyService</service-ref-interface>
          <port-component-ref>
              <service-endpoint-interface>com.example.MyPortType</service-endpoint-interface>
              <enable-mtom>true</enable-mtom>
              <mtom-threshold>1024</mtom-threshold>
          </port-component-ref>
      </service-ref>
      避免故障 避免故障: 部署描述符元素优先于 MTOM 注释中的相应属性。例如,如果在注释中将 enabled 属性设置为 true,但在客户机的 service-ref 的部署描述符条目中,将 <enable-mtom> 元素设置为 false,那么未对该服务引用启用 MTOM。gotcha

结果

您已开发 JAX-WS Web Service 服务器和客户机应用程序,对使用 MTOM 发送和接收二进制数据的操作进行了优化。

示例

以下示例说明了从 WSDL 文件开始时对 Web Service 客户机和服务器端点启用 MTOM 支持的过程。

  1. 找到包含 xsd:base64Binary 元素的 WSDL 文件。以下示例是包含 xsd:base64Binary 元素的 WSDL 文件的一部分。
      <types>
        ........
        <xs:complexType name="ImageDepot">
            <xs:sequence>
                <xs:element name="imageData" 
                            type="xs:base64Binary"                        
                            xmime:expectedContentTypes="image/jpeg"/>
    
            </xs:sequence>
        </xs:complexType>
        ........
    </types>
  2. app_server_root\bin\ 目录对 WSDL 文件运行 wsimport 命令以生成一组 JAX-WS 可移植工件。
    [Windows]
    app_server_root\bin\wsimport.bat <wsdl_url>
    [AIX][HP-UX][Linux][Solaris]
    app_server_root/bin/wsimport.sh <wsdl_url>
    根据在 WSDL 文件中包含的 expectedContentTypes 值,生成的 JAXB 工件将使用 Java 类型,如下表中所述:
    表 1. MIME 类型和 Java 类型的映射. 描述 MIME 类型和 Java 类型之间的映射。
    MIME 类型 Java 类型
    image/gif java.awt.Image
    image/jpeg java.awt.Image
    text/plain java.lang.String
    text/xml javax.xml.transform.Source
    application/xml javax.xml.transform.Source
    */* javax.activation.DataHandler
  3. 按照与在任何其他 JAX-WS 应用程序中相同的方式使用 JAXB 工件。使用这些 Bean 从 Dispatch 和 Dynamic proxy client API 发送二进制数据。
  4. 对 Dispatch client 启用 MTOM。
    //Create the Dispatch instance.
            JAXBContext jbc = JAXBContext.newInstance("org.apache.axis2.jaxws.sample.mtom");
            Dispatch<Object> dispatch = svc.createDispatch(portName, jbc, Service.Mode.PAYLOAD);
    
    //Enable MTOM.
            SOAPBinding binding = (SOAPBinding) dispatch.getBinding();
            binding.setMTOMEnabled(true);
  5. 对动态代理客户机启用 MTOM。
    //Create the Dynamic Proxy instance.
            Service svc = Service.create(serviceName);
            MtomSample proxy = svc.getPort(portName, MtomSample.class);
    
    //Enable MTOM.
            BindingProvider bp = (BindingProvider) proxy;
            SOAPBinding binding = (SOAPBinding) bp.getBinding();
            binding.setMTOMEnabled(true);
    在启用 JAX-WS 客户机使用 MTOM 后,发送至服务器的消息启用了 MTOM。但是,要使服务器通过使用 MTOM 对客户机作出响应,必须对端点启用 MTOM。
  6. 对端点实现类启用 MTOM。
    @MTOM(enabled, threshold=4096)
    @WebService (endpointInterface="org.apache.axis2.jaxws.sample.mtom.MtomSample")
    
    public class MtomSampleService implements MtomSample {
       ....
    }
    jaxax.xml.ws.SOAPBinding 类为各个受支持的绑定类型提供了一个静态成员。将 SOAP11HTTP_MTOM_BINDINGSOAP12HTTP_MTOM_BINDING 包括为 @BindingType 注释的值。此值使所有服务器响应都能够启用 MTOM。

对服务器和客户机启用 MTOM 时,表示附件的二进制数据作为 SOAP 消息的多用途因特网邮件扩展 (MIME) 附件来包括。如果不使用 MTOM,那么将使用描述 XML 模式的格式(基本 64 位或十六进制编码)对同一数据进行编码并且通过内联的方式将其包括在 XML 文档中。

此示例说明了已启用 MTOM 且含有附件的 SOAP V1.1 消息。typecontent-type 属性都具有值 application/xop+xml,指示在 MTOM 处于启用状态时成功使用 XML 二进制优化打包 (XOP)对消息进行了优化。本示例演示了在启用 MTOM 的情况下,优化消息在连线上的外观。
... other transport headers ... 
Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812; 
type="application/xop+xml"; start="
<0.urn:uuid:0FE43E4D025F0BF3DC11582467646813@apache.org>"; start-info="text/xml"; charset=UTF-8

--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812
content-type: application/xop+xml; charset=UTF-8; type="text/xml";
content-transfer-encoding: binary
content-id: 
   <0.urn:uuid:0FE43E4D025F0BF3DC11582467646813@apache.org>

<?xml version="1.0" encoding="UTF-8"?>
         <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
            <soapenv:Header/>
            <soapenv:Body>
               <sendImage xmlns="http://org/apache/axis2/jaxws/sample/mtom">
                  <input>
                     <imageData>
                        <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" 
href="cid:1.urn:uuid:0FE43E4D025F0BF3DC11582467646811@apache.org"/>
                     </imageData>
                  </input>
               </sendImage>
            </soapenv:Body>
         </soapenv:Envelope>
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812
content-type: text/plain
content-transfer-encoding: binary
content-id: 
         <1.urn:uuid:0FE43E4D025F0BF3DC11582467646811@apache.org>

… binary data goes here …
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812--
相反,本示例演示了未启用 MTOM 时连线上的 SOAP V1.1 消息。二进制数据包含在 SOAP 消息的主体中,而且 SOAP 消息并未优化。
... other transport headers ... 
Content-Type: text/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
      <soapenv:Header/>
      <soapenv:Body>
         <sendImage xmlns="http://org/apache/axis2/jaxws/sample/mtom">
            <input>
               <imageData>R0lGADl ... more base64 encoded data ... KTJk8giAAA7</imageData>
            </input>
         </sendImage>
      </soapenv:Body>
   </soapenv:Envelope>

有关更多信息,请参阅信息中心的“样本”部分,此部分包含一个演示如何将 MTOM 与 JAX-WS Web Service 一起使用的样本。


指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_enablemtom
文件名:twbs_enablemtom.html