A l'aide de JAX-WS (Java™ API for XML-Based Web Services), vous pouvez envoyer des pièces jointes binaires, telles des images ou des fichiers avec des demandes de services Web. JAX-WS ajoute un support pour la transmission optimisée de données binaires, comme défini dans la spécification MTOM (Message Transmission Optimization Mechanism) SOAP.
Pourquoi et quand exécuter cette tâche
JAX-WS prend en charge l'utilisation du mécanisme SOAP MTOM
pour l'envoi de pièces jointes binaires. En activant MTOM, vous pouvez
envoyer et recevoir des données binaires de manière optimale sans conséquence sur
le coût du codage requis pour imbriquer les données binaires dans le document XML.
Le serveur d'applications ne prend en charge l'envoi de pièces jointes à l'aide de MTOM que pour des applications JAX-WS. Ce produit permet de fournir des pièces jointes aux messages SOAP de Web Services
Security SOAP, à l'aide des nouvelles normes MTOM et XOP.
Les applications JAX-WS
peuvent envoyer des données binaires, telles les données codées base64 ou hexBinary se trouvant
dans le document XML. Toutefois, pour tirer le meilleur parti des optimisations
fournies par MTOM, activez MTOM pour envoyer des données base64 binaires en tant que
pièces jointes se trouvant hors du document XML. Par défaut, l'optimisation MTOM n'est pas activée. Les applications JAX-WS requièrent une configuration distincte des artefacts serveur et client pour activer le support MTOM.
Procédure
- Développez des artefacts Java pour votre application JAX-WS qui comprend un schéma XML ou un fichier WSDL (Web Services Description Language) représentant les données d'application de vos services Web qui incluent une pièce jointe binaire.
- Si vous commencez avec un fichier WSDL, développez des artefacts Java à partir d'un fichier WSDL en utilisant la commande wsimport pour générer les artefacts portables JAX-WS requis.
- Si vous commencez avec des composants JavaBeans, développez des artefacts Java pour des applications JAX-WS et générez, facultativement, un fichier WSDL en utilisant la commande wsgen. Le schéma XML ou le fichier WSDL inclut une définition d'élément xsd:base64Binary
ou xsd:hexBinary pour les données binaires.
- Vous pouvez également inclure l'élément xmime:expectedContentTypes sur l'élément
afin de modifier le mappage par JAXB.
- Activez MTOM sur la classe d'implémentation de noeud final à l'aide de l'une des méthodes suivantes :
- Utilisez l'annotation @MTOM sur le noeud final.
Pour activer MTOM sur un noeud final, utilisez l'annotation @MTOM (javax.xml.ws.soap.MTOM) sur le noeud final. L'annotation @MTOM possède deux paramètres, enabled et threshold. La valeur du paramètre enabled est booléenne. Elle indique si MTOM est activé pour le noeud final JAX-WS. La valeur du paramètre threshold est un entier supérieur ou égal à zéro. Lorsque MTOM est activé, toute donnée binaire dont la taille, en octets, dépasse la valeur seuil, et codée avec XOP (XML-binary Optimized Packaging) ou envoyée sous forme de pièce jointe. Si la taille du message est inférieure à la valeur seuil, le message est intégré dans le document XML en tant que données base64 ou hexBinary.
Le fragment de code ci-dessous illustre l'ajout de l'annotation @MTOM, de sorte que MTOM soit activé pour le noeud final JAX-WS
MyServiceImpl, et spécifie une valeur seuil de 2048 octets :
@MTOM(enabled=true, threshold=2048)
@WebService
public class MyServiceImpl {
...
}
En outre, vous pouvez utiliser l'annotation, @BindingType (javax.xml.ws.BindingType) sur une classe d'implémentation de noeud pour spécifier que le noeud final prend en charge l'un des types de liaison MTOM pour que MTOM soit activé pour les messages de réponse. La classe javax.xml.ws.SOAPBinding définit deux différentes constantes,
SOAP11HTTP_MTOM_BINDING et
SOAP12HTTP_MTOM_BINDING que vous pouvez utiliser pour la valeur de l'annotation @BindingType, par exemple :
// Cet exemple est pour SOAP version 1.1
@BindingType(value = SOAPBinding.SOAP11HTTP_MTOM_BINDING)
@WebService
public class MyServiceImpl {
...
}
// Cet exemple est pour SOAP version 1.2
@BindingType(value = SOAPBinding.SOAP12HTTP_MTOM_BINDING)
@WebService
public class MyServiceImpl {
...
}
La présence et la valeur d'une annotation @MTOM remplacent la valeur de l'annotation @BindingType. Par exemple, si @BindingType indique que MTOM est activé, mais qu'une annotation @MTOM est présente avec la valeur false pour enabled, MTOM n'est pas activé.
- Utilisez les éléments du descripteur de déploiement <enable-mtom> et <mtom-threshold>.
Les éléments
<enable-mtom> et
<mtom-threshold> peuvent être utilisés à l'intérieur de l'élément
<port-component> dans le descripteur de déploiement webservices.xml, et constituer une alternative à l'utilisation de l'annotation @MTOM
dans la classe d'implémentation du noeud final de service, par exemple :
<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>
Eviter les incidents: Les éléments du descripteur de déploiement ont la priorité sur les attributs correspondants de l'annotation MTOM. Par exemple, si l'attribut
enabled a la valeur
true dans l'annotation, alors que l'élément
<enable-mtom> à la valeur
false dans le fichier
webservices.xml, MTOM n'est pas activé pour le noeud final concerné.
gotcha
- Activez MTOM sur le client pour optimiser les messages binaires qui sont envoyés par le client au serveur. Utilisez l'une des méthodes suivantes pour activer MTOM sur le client :
- Activez MTOM sur un client Dispatch.
Remarque : Pour un client de répartition, l'application client doit construire un message SOAP dans un format optimisé.
Les exemples suivant utilisent SOAP version 1.1.
La première méthode utilise SOAPBinding.setMTOMEnabled(), par exemple :
SOAPBinding binding = (SOAPBinding)dispatch.getBinding();
binding.setMTOMEnabled(true);
La deuxième méthode utilise Service.addPort(), par exemple :
Service svc = Service.create(serviceName);
svc.addPort(portName,SOAPBinding.SOAP11HTTP_MTOM_BINDING,endpointUrl);
La troisième méthode utilise MTOMFeature, par exemple :
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);
- Activez MTOM sur un client Dynamic Proxy.
// Créer un élément BindingProvider à partir d'un port de proxy.
Service svc = Service.create(serviceName);
MtomSample proxy = svc.getPort(portName, MtomSample.class);
BindingProvider bp = (BindingProvider) proxy;
// Activez MTOM à l'aide de SOAPBinding
MtomSample proxy = svc.getPort(portName, MtomSample.class);
BindingProvider bp = (BindingProvider) proxy;
SOAPBinding binding = (SOAPBinding) bp.getBinding();
binding.setMTOMEnabled(true);
// Ou, vous pouvez activer MTOM avec MTOMFeature
MTOMFeature mtom = new MTOMFeature();
MtomSample proxy = svc.getPort(portName, MtomSample.class, mtom);
- Activez MTOM dans votre client à l'aide de l'annotation @MTOM, par exemple :
public class MyClientApplication {
// Activez MTOM pour une injection de ressource port-component-ref.
@MTOM(enabled=true, threshold=1024)
@WebServiceRef(MyService.class)
private MyPortType myPort;
...
}
- Activez MTOM dans votre client à l'aide d'éléments de descripteur de déploiement à l'intérieur d'un élément port-component-ref, par exemple :
<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>
Eviter les incidents: Les éléments du descripteur de déploiement ont la priorité sur les attributs correspondants de l'annotation MTOM. Par exemple, si l'attribut
enabled a la valeur
true dans l'annotation, alors que l'élément
<enable-mtom> à la valeur
false dans l'entrée du descripteur de déploiement de la référence de service du client, MTOM n'est pas activé pour la référence de service concernée.
gotcha
Résultats
Vous avez développé un serveur de services Web JAX-WS et une application client
qui peut envoyer et recevoir des données binaires à l'aide de MTOM.
Exemple
L'exemple suivant illustre l'activation du support MTOM sur le client de services Web
et le noeud final de serveur lors du démarrage avec un fichier WSDL.
- Définissez l'emplacement du fichier WSDL contenant un élément xsd:base64Binary. L'exemple suivant est extrait du fichier WSDL qui contient un élément xsd:base64Binary.
<types>
........
<xs:complexType name="ImageDepot">
<xs:sequence>
<xs:element name="imageData"
type="xs:base64Binary"
xmime:expectedContentTypes="image/jpeg"/>
</xs:sequence>
</xs:complexType>
........
</types>
- Exécutez la commande wsimport à partir du répertoire racine_serveur_app\bin\
pour le fichier WSDL afin de générer un ensemble d'artefacts portables JAX-WS.
Selon les valeurs
expectedContentTypes contenues dans le fichier WSDL, les artefacts JAXB générés sont de type Java comme décrit dans le tableau suivant :
Tableau 1. Mappage du type MIME et du type Java. Ce tableau décrit le mappage entre les types MIME et Java. Type MIME |
Type 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 |
- Utilisez les artefacts JAXB de la même manière qu'avec toute autre application JAX-WS. Utilisez
ces beans pour envoyer des données binaires à partir des API client Dispatch et Dynamic Proxy.
- Activez MTOM sur un client Dispatch.
//Créer l'instance Dispatch.
JAXBContext jbc = JAXBContext.newInstance("org.apache.axis2.jaxws.sample.mtom");
Dispatch<Object> dispatch = svc.createDispatch(portName, jbc, Service.Mode.PAYLOAD);
//Activer MTOM.
SOAPBinding binding = (SOAPBinding) dispatch.getBinding();
binding.setMTOMEnabled(true);
- Activez MTOM sur un client Dynamic Proxy.
//Créer l'instance Dynamic Proxy.
Service svc = Service.create(serviceName);
MtomSample proxy = svc.getPort(portName, MtomSample.class);
//Activer MTOM.
BindingProvider bp = (BindingProvider) proxy;
SOAPBinding binding = (SOAPBinding) bp.getBinding();
binding.setMTOMEnabled(true);
Maintenant que vous avez activé
le client JAX-WS pour MTOM, les messages envoyés au serveur sont activés MTOM.
Cependant, pour que le serveur renvoie une réponse au client en utilisant MTOM, vous devez activer MTOM sur le noeud final.
- Activez MTOM sur la classe d'implémentation de noeud final.
@MTOM(enabled, threshold=4096)
@WebService (endpointInterface="org.apache.axis2.jaxws.sample.mtom.MtomSample")
public class MtomSampleService implements MtomSample {
....
}
La classe jaxax.xml.ws.SOAPBinding a un membre statique pour
chaque type de liaison pris en charge. Incluez l'élément SOAP11HTTP_MTOM_BINDING ou
SOAP12HTTP_MTOM_BINDING en tant que valeur pour l'annotation @BindingType. Cette valeur active toutes les réponses de serveur pour l'activation MTOM.
Lorsque vous activez MTOM sur le serveur
et le client, les données binaires qui représentent la pièce jointe sont incluses en tant que
pièce jointe MIME au message SOAP.
Sans MTOM, les mêmes données sont codées au format
qui décrit le schéma XML, base64 ou hexadecimal, et incluses en ligne dans le document XML.
Cet exemple illustre
un message SOAP version 1.1 activé pour MTOM avec une pièce jointe. Les attributs
type
et
content-type ont la valeur
application/xop+xml, ce qui indique que le message
a été optimisé à l'aide de XOP (XML-binary Optimized packaging) lorsque MTOM est activé. Cet exemple décrit l'aspect
du message optimisé sur ce réseau avec MTOM activé.
... 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--
Cet exemple, quant à lui, présente
un message SOAP version 1.1 sur le réseau sans MTOM activé. Les données binaires sont incluses
dans le corps du message SOAP et le message SOAP n'est pas optimisé.
... 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>
Pour plus d'informations, reportez-vous à la galerie d'exemples du centre de documentation qui inclut un exemple montrant l'utilisation de MTOM avec des services Web JAX-WS.