MTOM für JAX-WS-Web-Services aktivieren

Mit Java™ API for XML-Based Web Services (JAX-WS) können Sie binäre Anhänge, wie z. B. Bilder oder Dateien, zusammen mit Web-Service-Anforderungen senden. JAX-WS bietet Unterstützung für eine optimierte Übertragung binärer Daten gemäß der Spezifikation "SOAP Message Transmission Optimization Mechanism (MTOM)".

Informationen zu diesem Vorgang

JAX-WS unterstützt die Verwendung von SOAP Message Transmission Optimized Mechanism (MTOM) für das Senden binärer Anhangsdaten. Wenn Sie MTOM aktivieren, können Sie binäre Daten optimal senden und empfangen. Es entstehen keine Kosten für die Datencodierung, die sonst anfallen, wenn die binären Daten in ein XML-Dokument eingebettet werden müssen.

Der Anwendungsserver unterstützt das Senden von Anhängen über MTOM nur für JAX-WS-Anwendungen. Über die neuen MTOM- und XOP-Standards bietet dieses Produkt bietet außerdem die Möglichkeit, Anhänge mit SOAP-Nachrichten bereitzustellen, die der Spezifikation "Web Services Security" entsprechen.

JAX-WS-Anwendungen können Binärdaten im base64- oder hexBinary-Format im XML-Dokument senden. Wenn Sie jedoch die Optimierungen nutzen möchten, die MTOM bietet, müssen Sie MTOM so aktivieren, dass binäre Daten im base64-Format als Anhänge außerhalb des XML-Dokuments gesendet werden. Die MTOM-Optimierung ist standardmäßig nicht aktiviert. JAX-WS-Anwendungen setzen für die Aktivierung der MTOM-Unterstützung eine separate Konfiguration der Client- und Serverartefakte voraus.

Vorgehensweise

  1. Entwickeln Sie Java-Artefakte für Ihre JAX-WS-Anwendung. Dazu gehört ein XML-Schema oder eine WSDL-Datei (Web Services Description Language), das bzw. die die Daten Ihrer Web-Service-Anwendung darstellt, die einen binären Anhang enthalten.
    1. Wenn Sie eine WSDL-Datei als Ausgangspunkt verwenden, entwickeln Sie die Java-Artefakte aus einer WSDL-Datei, indem Sie mit dem Befehl "wsimport" die erforderlichen portierbaren JAX-WS-Artefakte generieren.
    2. Wenn Sie JavaBeans-Komponenten als Ausgangspunkt verwenden, entwickeln Sie Java-Artefakte für JAX-WS-Anwendungen, und generieren Sie optional eine WSDL-Datei mit dem Befehl "wsgen". Das XML-Schema bzw. die WSDL-Datei enthält eine Elementdefinition xsd:base64Binary oder xsd:hexBinary für die Binärdaten.
    3. Sie können auch das Attribut xmime:expectedContentTypes im Element importieren, um die Zuordnung durch JAXB zu beeinflussen.
  2. Aktivieren Sie MTOM in Ihrer Endpunktimplementierungsklasse. Verwenden Sie dazu eine der folgenden Methoden:
    • Verwenden Sie die @MTOM-Annotation am Endpunkt.

      Zum Aktivieren von MTOM an einem Endpunkt verwenden Sie die Annotation "@MTOM" (javax.xml.ws.soap.MTOM) am Endpunkt. Die Annotation "@MTOM" hat zwei Parameter, enabled und threshold. Der Parameter enabled hat einen booleschen Wert und gibt an, ob MTOM für den JAX-WS-Endpunkt aktiviert ist. Der Parameter threshold hat einen ganzzahligen Wert größer-gleich 0. Wenn MTOM aktiviert ist, werden alle Binärdaten, deren Umfang den in Byte angegebenen Schwellenwert mit XOP (XML-binary Optimized Packaging) encoded codiert oder als Anhang gesendet. Wenn die Nachrichtengröße unter der angegebenen Ganzzahl liegt, wird die Nachricht im XML-Dokument in Form von base64- oder hexBinary-Daten übertragen.

      Der folgende Beispielausschnitt veranschaulicht, wie die @MTOM-Annotation hinzugefügt wird, damit MTOM für den JAX-WS-Endpunkt MyServiceImpl aktiviert wird und den Schwellenwert von 2048 Byte angibt:
      @MTOM(enabled=true, threshold=2048)
      @WebService
      public class MyServiceImpl {
      ...
      }
      Außerdem können Sie die Annotation "@BindingType" (javax.xml.ws.BindingType) in einer Endpunktimplementierungsklasse verwenden, um anzugeben, dass der Endpunkt einen der MTOM-Bindungstypen unterstützt, sodass die Antwortnachrichten MTOM-fähig sind. Die Klasse "javax.xml.ws.SOAPBinding" definiert zwei verschiedene Konstanten, SOAP11HTTP_MTOM_BINDING und SOAP12HTTP_MTOM_BINDING, die Sie als Wert für die Annotation "@BindingType" verwenden können. Beispiel:
      // Dieses Beispiel bezieht sich auf SOAP Version 1.1.
      @BindingType(value = SOAPBinding.SOAP11HTTP_MTOM_BINDING)
      @WebService
      public class MyServiceImpl {
      ...
      }
      // Dieses Beispiel bezieht sich auf SOAP Version 1.2.
      @BindingType(value = SOAPBinding.SOAP12HTTP_MTOM_BINDING)
      @WebService
      public class MyServiceImpl {
      ...
      }

      Das Vorhandensein und der Wert einer Annotation "@MTOM" überschreiben den Wert der Annotation "@BindingType". Wenn die Annotation "@BindingType" beispielsweise angibt, dass MTOM aktiviert ist, aber eine @MTOM-Annotation mit dem enabled-Wert "false" vorhanden ist, ist MTOM nicht aktiviert.

    • Verwenden Sie die Implementierungsdeskriptorelemente <enable-mtom> und <mtom-threshold>.
      Sie können die Elemente <enable-mtom> und <mtom-threshold> im Element <port-component> im Implementierungsdeskriptor "webservices.xml" alternativ zur @MTOM-Annotation in der Serviceendpunktimplementierungsklasse verwenden. Beispiel:
      <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>
      Fehler vermeiden Fehler vermeiden: Die Implementierungsdeskriptorelemente haben Vorrang vor den entsprechenden Attributen in der MTOM-Annotation. Wenn beispielsweise das Attribut enabled in der Annotation auf true gesetzt ist, das Element <enable-mtom> in der Datei webservices.xml jedoch auf false gesetzt ist, ist MTOM für den entsprechenden Endpunkt nicht aktiviert. gotcha
  3. Die Aktivierung von MTOM auf Clientseite optimiert die binären Nachrichten, die vom Client an den Server gesendet werden. Verwenden Sie eine der folgenden Methoden, um MTOM auf dem Client zu aktivieren:
    • Aktivieren Sie MTOM in einem Dispatch-Client.
      Anmerkung: Die Clientanwendung muss für einen Dispatch-Client eine SOAP-Nachricht in einem optimierten Format erstellen.

      Die folgenden Beispiele verwenden SOAP Version 1.1.

      Die erste Methode verwendet SOAPBinding.setMTOMEnabled();. Beispiel:
      SOAPBinding binding = (SOAPBinding)dispatch.getBinding();
          binding.setMTOMEnabled(true);
      Die zweite Methode verwendet Service.addPort;. Beispiel:
          Service svc = Service.create(serviceName);
          svc.addPort(portName,SOAPBinding.SOAP11HTTP_MTOM_BINDING,endpointUrl); 
      Die dritte Methode verwendet MTOMFeature;. Beispiel:
         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);
    • Aktivieren Sie MTOM in einem Dynamic-Proxy-Client.
      // BindingProvider bp über einen Proxy-Port erstellen
        Service svc = Service.create(serviceName);
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        
        // MTOM mit SOAPBinding aktivieren
        MtomSample proxy = svc.getPort(portName, MtomSample.class);
        BindingProvider bp = (BindingProvider) proxy;
        SOAPBinding binding = (SOAPBinding) bp.getBinding();
        binding.setMTOMEnabled(true);
      
        // Oder MTOM mit MTOMFeature aktivieren
        MTOMFeature mtom = new MTOMFeature();
        MtomSample proxy = svc.getPort(portName, MtomSample.class, mtom);
    • Sie können MTOM auf Ihrem Client mit der @MTOM-Annotation aktivieren. Beispiel:
      public class MyClientApplication {
      
          // MTOM für eine Ressourceninjektion vom Typ "port-component-ref" aktivieren.
      	    		   @MTOM(enabled=true, threshold=1024)
      	    @WebServiceRef(MyService.class)
      	    private MyPortType myPort;
          ...
      }
    • Sie können MTOM auf Ihrem Client mit Implementierungsdeskriptorkomponenten in einem port-component-ref-Element aktivieren. Beispiel:
      <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>
      Fehler vermeiden Fehler vermeiden: Die Implementierungsdeskriptorelemente haben Vorrang vor den entsprechenden Attributen in der MTOM-Annotation. Wenn beispielsweise das Attribut enabled in der Annotation auf true gesetzt ist, das Element <enable-mtom> im Implementierungsdeskriptoreintrag für die Servicereferenz des Clients jedoch auf false gesetzt ist, ist MTOM für diese Servicereferenz nicht aktiviert. gotcha

Ergebnisse

Sie haben eine Client/Server-Anwendung vom Typ JAX-WS-Web-Services entwickelt, die Binärdaten optimal über MTOM sendet und empfängt.

Beispiel

Das folgende Beispiel veranschaulicht, wie die MTOM-Unterstützung im Web-Service-Client und -Server-Endpunkt aktiviert wird, wenn eine WSDL-Datei als Ausgangspunkt verwendet wird.

  1. Suchen Sie die WSDL-Datei, die das Element xsd:base64Binary enthält. Das folgende Beispiel stammt aus einer WSDL-Datei, die ein Element xsd:base64Binary enthält.
      <types>
        ........
        <xs:complexType name="ImageDepot">
            <xs:sequence>
                <xs:element name="imageData" 
                            type="xs:base64Binary"                        
                            xmime:expectedContentTypes="image/jpeg"/>
    
            </xs:sequence>
        </xs:complexType>
        ........
    </types>
  2. Führen Sie den Befehl wsimport im Verzeichnis app_server_root\bin\ für die WSDL-Datei aus, um einen Satz portierbarer JAX-WS-Artefakte zu generieren.
    [Windows]
    Stammverzeichnis_des_Anwendungsservers\bin\wsimport.bat <WSDL-URL>
    [AIX][HP-UX][Linux][Solaris]
    Stammverzeichnis_des_Anwendungsservers/bin/wsimport.sh <WSDL-URL>
    Je nach expectedContentTypes-Wert, der in der WSDL-Datei enthalten ist, haben die generierten JAXB-Artefakte den Java-Typ, der in der folgenden Tabelle beschrieben ist:
    Tabelle 1. Zuordnung von MIME-Typ und Java-Typ. Beschreibt die Zuordnung von MIME-Typen und Java-Typen.
    MIME-Typ Java-Typ
    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. Verwenden Sie die JAXB-Artefakte wie in jeder anderen JAX-WS-Anwendung. Verwenden Sie diese Beans, um Binärdaten über die Client-APIs "Dispatch" und "Dynamic Proxy" zu senden.
  4. Aktivieren Sie MTOM in einem Dispatch-Client.
    // Dispatch-Instanz erstellen.
            JAXBContext jbc = JAXBContext.newInstance("org.apache.axis2.jaxws.sample.mtom");
            Dispatch<Object> dispatch = svc.createDispatch(portName, jbc, Service.Mode.PAYLOAD);
    
    // MTOM aktivieren
            SOAPBinding binding = (SOAPBinding) dispatch.getBinding();
            binding.setMTOMEnabled(true);
  5. Aktivieren Sie MTOM in einem Dynamic-Proxy-Client.
    // Dynamic-Proxy-Instanz erstellen.
            Service svc = Service.create(serviceName);
            MtomSample proxy = svc.getPort(portName, MtomSample.class);
    
    // MTOM aktivieren
            BindingProvider bp = (BindingProvider) proxy;
            SOAPBinding binding = (SOAPBinding) bp.getBinding();
            binding.setMTOMEnabled(true);
    Da Sie den JAX-WS-Client nun für MTOM aktiviert haben, sind die Nachrichten, die an den Server gesendet werden, MTOM-fähig. Damit der Server dem Client auch über MTOM antwortet, müssen Sie jedoch MTOM im Endpunkt aktivieren.
  6. Aktivieren Sie MTOM in Ihrer Endpunktimplementierungsklasse.
    @MTOM(enabled, threshold=4096)
    @WebService (endpointInterface="org.apache.axis2.jaxws.sample.mtom.MtomSample")
    
    public class MtomSampleService implements MtomSample {
       ....
    }
    Die Klasse jaxax.xml.ws.SOAPBinding hat ein statisches Element für jeden der unterstützten Bindungstypen. Fügen Sie SOAP11HTTP_MTOM_BINDING oder SOAP12HTTP_MTOM_BINDING als Wert für die Annotation @BindingType ein. Dieser Wert aktiviert alle Serverantworten für MTOM.

Wenn Sie MTOM im Server und im Client aktivieren, werden die Binärdaten, die den Anhang darstellen, als MIME-Anhang (Multipurpose Internet Mail Extensions) in die SOAP-Nachricht eingefügt. Ohne MTOM werden diese Daten in dem Format codiert, das das XML-Schema beschreibt (base64 oder hexadecimal), und in das XML-Dokument eingefügt.

Das folgende Beispiel zeigt eine MTOM-fähige SOAP-Nachricht der Version 1.1 mit Anhangsdaten. Die Attribute type und content-type haben beide den Wert application/xop+xml, d. h., die Nachricht wurde erfolgreich mit XML-binary Optimized Packaging (XOP) aktiviert, als MTOM aktiviert wurde. Dieses Beispiel veranschaulicht, wie die optimierte Nachricht in der Verbindung aussieht, wenn MTOM aktiviert ist.
... weitere Transportheader ...
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>

… hier sind die Binärdaten enthalten …
--MIMEBoundaryurn_uuid_0FE43E4D025F0BF3DC11582467646812--
Das folgende Beispiel veranschaulicht, wie eine SOAP-Nachricht der Version 1.1 in der Verbindung aussieht, wenn MTOM nicht aktiviert ist. Die Binärdaten sind im Hauptteil der SOAP-Nachricht enthalten, und die SOAP-Nachricht ist nicht optimiert.
... weitere Transportheader ...
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>

Weitere Informationen finden Sie im Abschnitt "Beispiele" des Information Center. Eines der dort aufgeführten Beispiele veranschaulicht die Verwendung von MTOM mit JAX-WS-Web-Services.


Symbol, das den Typ des Artikels anzeigt. Taskartikel



Symbol für Zeitmarke Letzte Aktualisierung: 25.05.2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_enablemtom
Dateiname:twbs_enablemtom.html