Mappage entre le langage Java, WSDL et XML pour les applications JAX-RPC

Les données des applications JAX-RPC (Java™ API for XML) circulent au format XML (extensible Markup Language). Les applications JAX-RPC utilisent des mappages pour décrire la conversion de données entre le langage Java et les technologies XML (schéma XML, WSDL [Web Services Description Language] et SOAP), qui sont prises en charge par le serveur d'applications.

Pour les applications JAX-RPC, la plupart des mappages entre le langage Java et XML sont définis par la spécification JAX-RPC. Certains mappages facultatifs ou non spécifiés dans JAX-RPC sont également pris en charge. Vous trouverez la liste complète des API dans spécification JAX-RPC. Pour obtenir la liste complète des normes et spécifications prises en charge, voir les spécifications des services Web et la documentation des API.

Conventions de notation

Tableau 1. Conventions applicables aux espaces de nom. Ce tableau répertorie les préfixes d'espace de nom et les espaces de nom correspondants utilisés dans les conventions.
Préfixe d'espace de nom Espace de nom
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 espace de nom défini par l'utilisateur
apache http://xml.apache.org/xml-soap
wasws http://websphere.ibm.com/webservices/

Informations détaillées sur le mappage

Les sections suivantes identifient les mappages pris en charge, y compris :

Mappage Java-vers-WSDL

Cette section résume les règles de mappage Java vers WSDL. Les règles de mappage Java-vers-WSDL sont utilisées par la commande Java2WSDL pour le traitement ascendant. Dans ce type de traitement, une implémentation existante de service Java est utilisée pour créer un fichier WSDL définissant le service web. Le fichier WSDL généré peut nécessiter une édition manuelle supplémentaire pour les raisons suivantes :
  • Les classes et les constructions Java ne possèdent pas toutes des mappages vers des fichiers WSDL. Par exemple, les classes Java qui ne respectent pas les règles des spécifications de beans Java risquent de ne pas pouvoir être mappées vers une construction WSDL.
  • Certaines classes et constructions Java disposent de plusieurs mappages vers un i. Par exemple, une classe java.lang.String peut être mappée vers une construction xsd:string ou soapenc:string. La commande Java2WSDL choisit l'un de ces mappages, mais le fichier WSDL doit être modifié si un mappage différent est souhaité.
  • Des constructions WSDL peuvent être générées de plusieurs façons. Par exemple, vous pouvez générer wsdl:part en wsdl:message avec un attribut de type ou d'élément. La commande Java2WSDL effectue un choix en analysant les valeurs des options -style et -use.
  • Le fichier WSDL décrit les éléments de données de l'instance envoyés dans le message SOAP. Si vous souhaitez modifier les noms ou le format utilisés dans le message, le fichier WSDL doit être modifié. Par exemple, la commande Java2WSDL mappe en élément XML une propriété de bean Java. Dans certains cas, vous voudrez modifier le fichier WSDL pour mapper en attribut XML la propriété de bean Java.
  • Le fichier WSDL requiert une modification si le support d'en-tête ou de pièce jointe est souhaité.
  • Le fichier WSDL doit être édité si un fichier WSDL à plusieurs parties, qui utilise wsdl:import, est souhaité.
Pour des services simples, le fichier WSDL généré est suffisant. Pour des services compliqués, le fichier WSDL généré constitue un bon point de départ. Pour en savoir plus sur cet outil, consultez les informations relatives à l'outil Java2WSDL de ligne de commande des applications JAX-RPC (Java API for XML).
Remarques générales
  • Mappage de package vers un espace de nom :

    La spécification JAX-RPC n'indique pas quel est le mappage par défaut des noms de package Java vers des espaces de noms XML. Elle indique que chaque mappage Java doit mapper vers un seul espace de noms XML. De la même façon, chaque espace de noms XML doit mapper vers un seul package Java. Un algorithme de mappage par défaut est fourni pour construire l'espace de nom en inversant les noms de packages Java et en leur ajoutant un préfixe http://. Par exemple, un package nommé com.ibm.webservice est mappé vers l'espace de nom XML http://webservice.ibm.com.

    Vous pouvez remplacer le mappage par défaut entre les espaces de nom XML et les noms de package Java à l'aide des options -NStoPkg et -PkgtoNS des commandes WSDL2Java et Java2WSDL.

  • Mappage d'identificateur :

    Les identificateurs Java sont directement mappés vers des identificateurs WSDL et XML.

    Les noms de propriétés de beans Java sont mappés vers des identificateurs XML. Par exemple, un bean Java, avec des méthodes getInfo et setInfo, est mappé vers une construction XML du nom d'info.

    Les noms de paramètre de méthode d'interface SEI (service endpoint interface), si disponibles, sont mappés directement vers des identificateurs WSDL et XML. Pour en savoir plus, voir les informations relatives à l'option -implClass de la commande WSDL2Java.

  • Récapitulatif de construction WSDL :
    Tableau 2. Mappage de Java à une construction WSDL ou XML. Décrit le mappage d'une construction Java vers la construction WSDL et XML correspondante.
    Construction Java Construction WSDL et XML
    Interface SEI wsdl:portType
    Méthode wsdl:operation
    Paramètres wsdl:input, wsdl:message, wsdl:part
    Retourne wsdl:output, wsdl:message, wsdl:part
    Emet wsdl:fault, wsdl:message, wsdl:part
    Types primitifs xsd and soapenc simple types
    Beans Java xsd:complexType
    Propriétés de beans Java Nested xsd:elements of xsd:complexType
    Tableaux JAX-RPC a défini xsd:complexType ou xsd:element avec un attribut maxOccurs="unbounded"
    Exceptions définies par l'utilisateur xsd:complexType
  • Construction liaison et service

    Un wsdl:binding conforme au wsdl:portType généré est créé. Un wsdl:service contenant un port faisant référence au wsdl:binding généré est créé. Les noms de la liaison et du service sont contrôlés par les options de la commande Java2WSDL.

  • Style et usage
    Utilisez les options -style et -use pour générer différentes sortes de fichiers WSDL. Les quatre combinaisons prises en charge sont les suivantes :
    • -style DOCUMENT -use LITERAL
    • -style RPC -use LITERAL
    • -style DOCUMENT -use LITERAL -wrapped false
    • -style RPC -use ENCODED
    Ces combinaisons sont décrites brièvement dans ce qui suit.
    • DOCUMENT LITERAL :

      La commande Java2WSDL génère une spécification Web Services - Interoperability (WS-I) conforme au fichier WSDL document-literal. Le wsdl:binding est généré en incorporant les attributs style="document" et use="literal". Un xsd:element est généré pour chaque méthode d'interface SEI pour décrire le message de demande. Un xsd:element similaire est généré pour chaque méthode SEO pour décrire le message de réponse.

    • RPC LITERAL :

      La commande Java2WSDL génère un fichier WSDL de type rpc-literal conforme à WS-I. Le wsdl:binding est généré en incorporant les attributs style="rpc" et use="literal". Les constructions wsdl:message sont générées pour les entrées et les sorties de chaque méthode d'interface SEI. Les paramètres de la méthode sont décrits par les éléments constitutifs des constructions wsdl:message.

    • DOCUMENT LITERAL non encapsulé :

      La commande Java2WSDL génère un fichier WSDL de type document/literal en fonction de la spécification JAX-RPC. Ce fichier WSDL n'est pas conforme à .NET. La différence principale entre DOCUMENT LITERAL et DOCUMENT LITERAL non encapsulé réside dans l'utilisation de constructions wsdl:message pour définir les messages de demande et de réponse.

    • RPC ENCODED :

      La commande Java2WSDL génère un fichier WSDL de type rpc/encodé selon la spécification JAX-RPC. Le fichier WSDL n'est pas conforme à la spécification WS-I. Le wsdl:binding est généré en incorporant les attributs style="rpc" et use="encoded". Certains mappages soapenc permettent de représenter des types et des tableaux.

    De nombreux types type Java sont mappés directement vers des types XML standard. Par exemple, un java.lang.String est mappé vers un xsd:string. Ces mappages sont décrits dans la spécification JAX-RPC.

    Les types Java qui ne peuvent être mappés directement vers des types XML standard sont générés à la section wsdl:types. Une classe Java correspondant au modèle de beans Java est mappée vers un xsd:complexType. Reportez-vous à la spécification JAX-RPC pour une description de toutes les règles de mappage. L'exemple suivant illustre le mappage de classes Java de base et dérivées.
    Java :
    
    
    public abstract class Base {  
         public Base() {}  
         public int a;                         // mappé  
         private int b;                        // mappé via setter/getter  
         private int c;                        // non mappé  
         private int[] d;                      // mappé via un setter/getter indexé  
    
         public int getB() { return b;}        // mappe la propriété b  
         public void setB(int b) {this.b = b;}  
    
         public int[] getD() { return d;}      // mappe la propriété d indexée  
         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() {...}        // non mappé  
      }  
    
      public class Derived extends Base {  
         public int x;                         // mappé  
         private int y;                        // non mappé  
      } 
    
    Mappé vers : 
    
    <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>
        
    
  • Classes non prises en charge :

    Si une classe ne peut pas être mappée vers un type XML, la commande Java2WSDL émet un message et une référence xsd:anyType est générée dans le fichier WSDL. Dans ce cas, modifiez l'implémentation du service Web afin d'utiliser les classes compatibles JAX-RPC.

Mappage WSDL-vers-Java

La commande WSDL2Java génère des classes Java à l'aide des informations décrites dans le fichier WSDL.

Remarques générales :
  • Mappage d'un espace de nom vers un package

    JAX-RPC ne spécifie pas le mappage des espaces de noms XML vers des noms de packages Java. JAX-RPC spécifie que chaque package Java est mappé vers un seul espace de noms XML. De la même façon, chaque espace de noms XML doit mapper vers un seul package Java. Un algorithme de mappage par défaut supprime tout protocole de l'espace de nom XML et inverse les noms. Par exemple, l'espace de nom XML http://websphere.ibm.com devient un package Java portant le nom de com.ibm.websphere.

    Le mappage par défaut d'un espace de noms XML vers un package Java ignore la racine de contexte. Si deux espaces de noms sont identiques jusqu'à la première barre oblique, ils mappent vers le même package Java. Par exemple, les espaces de nom XML http://websphere.ibm.com/foo et http://websphere.ibm.com/bar sont mappés au package Java com.ibm.websphere. Vous pouvez remplacer le mappage par défaut entre les espaces de nom XML et les noms de package Java à l'aide des options -NStoPkg et -PkgtoNS des commandes WSDL2Java et Java2WSDL.

    Les noms XML sont plus riches que les identificateurs Java. Ils peuvent inclure des caractères non autorisés dans les identificateurs Java. Voir dans l'annexe 20 de la spécification JAX-RPC les règles de mappage des noms XML en identificateurs Java.

  • Récapitulatif de construction Java :
    Le tableau suivant récapitule la construction Java vers XML. Reportez-vous à la spécification JAX-RPC pour une description de ces mappages.
    Tableau 3. Mappage d'une construction WSDL ou XML à Java. Ce tableau décrit le mappage entre les constructions XML et Java.
    Construction WSDL et XML ConstructionJava
    xsd:complexType Classe de bean Java, classe d'exception Java ou tableau Java
    nested xsd:element/xsd:attribute Propriété de bean Java
    xsd:simpleType (énumération) Classe d'énumération JAX-RPC
    wsdl:message La signature du paramètre de méthode est généralement déterminée par wsdl:message. Signature de méthode d'interface SEI
    wsdl:portType Interface SEI
    wsdl:operation Méthode d'interface SEI
    wsdl:binding Stub
    wsdl:service Interface de service
    wsdl:port Méthode d'accesseur de port dans l'interface de service
  • Mappage de types XML standard :
    • Mappage de types XML simples JAX-RPC :

      De nombreux types XML sont mappés directement en types Java. Reportez-vous à la spécification JAX-RPC pour une description de ces mappages.

      La commande WSDL2Java génère des types Java pour les constructions de schémas XML définies à la section wsdl:types. Le langage de schéma XML est plus important que le sous-ensemble requis ou facultatif défini par la spécification JAX-RPC. La commande WSDL2Java prend en charge les mappages obligatoires et la plupart des mappages facultatifs, ainsi que certains mappages de schéma XML qui ne sont pas inclus dans la spécification JAX-RPC. La commande WSDL2Java ignore les constructions qu'elle ne prend pas en charge. Par exemple, elle ne prend pas en charge l'attribut default. Si un xsd:element est défini avec l'attribut default, ce dernier est ignoré. Dans certains cas, la commande mappe vers l'interface Java javax.xml.soap.SOAPElement des constructions non prises en charge.

      Le mappage de beans Java standard est défini à la section 4.2.3 de la spécification JAX-RPC. Le type est défini par xsd:complexType. Les éléments xsd:elements imbriqués dans les groupes xsd:sequence ou xsd:all sont mappés vers des propriétés de beans Java. Exemple :
      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() {}  
      
           // Propriété de bean a  
           public String getA()             {...}  
           public void   setA(String value) {...}  
      
           // Propriété de bean indexé b  
           public String[] getB()           {...}  
           public String   getB(int index)  {...}  
           public void     setB(String[] values) {...}  
           public void     setB(int index, String value) {...}  
      
        }
      
    • Mappage de la construction wsdl:portType :

      La construction wsdl:portType est mappée vers l'interface SEI. Le nom de wsdl:portType est mappé vers celui de la classe de l'interface SEI.

    • Mappage de la construction wsdl:operation :
      Une construction wsdl:operation dans un wsdl:portType est mappée vers une méthode de l'interface SEI. Le nom de wsdl:operation est mappé vers celui de la méthode. wsdl:operation contient des éléments wsdl:input et wsdl:output qui font référence aux constructions wsdl:message de demande et de réponse à l'aide de l'attribut message. wsdl:operation peut contenir un élément wsdl:fault qui fait référence à un wsdl:message décrivant l'erreur. Ces erreurs sont mappées vers des classes Java qui étendent l'exception, java.lang.Exception, comme indiqué à la section 4.3.6 de la spécification JAX-RPC.
      • Effet du format de document/literal encapsulé :
        Si le fichier WSDL utilise le format encapsulé de type document/literal, les paramètres de méthode sont mappés à partir de l'encapsuleur xsd:element. Le format encapsulé de type document/literal et literal sont détectés automatiquement par la commande WSDL2Java. Les critères suivants doivent être satisfaits :
        • Le fichier WSDL doit comporter style="document" dans sa construction wsdl:binding.
        • Les constructions input et output des opérations dans wsdl:binding doivent contenir des éléments soap:body comportant use="literal".
        • Le wsdl:message référencé par la construction d'entrée wsdl:operation ne doit comporter qu'une seule partie.
        • La partie doit utiliser l'attribut element pour référencer un xsd:element.
        • L'élément xsd:element référencé ou l'élément encapsuleur doit porter le même nom que wsdl:operation.
        • L'élément encapsuleur ne doit comporter aucun xsd:attribute.
        Dans ce cas, chaque nom de paramètre est mappé à partir d'un xsd:element imbriqué contenu dans un élément encapsuleur. Le type de paramètre est mappé à partir du type de l'xsd:element imbriqué. Exemple :
        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) ... 
      • Mappage de paramètre :

        Si le format encapsulé document/literal n'est pas détecté, le mappage de paramètre suit les règles de mappage JAX-RPC normales définies à la section 4.3.4 de la spécification JAX-RPC.

        Chaque paramètre est défini par une partie wsdl:message référencée à partir des éléments input et output.
        • wsdl:part dans la demande wsdl:message est mappé vers un paramètre input.
        • wsdl:part dans le wsdl:message de réponse est mappé vers la valeur return. Si plusieurs wsdl:parts figurent dans le message de réponse, ces parties sont mappées vers les paramètres output.
          • Une classe Holder est générée pour chaque paramètre output comme indiqué à la section 4.3.5 de la spécification JAX-RPC.
        • Le wsdl:part figurant à la fois dans le wsdl:message de demande et de réponse est mappé vers un paramètre inout.
          • Une classe Holder est générée pour chaque paramètre input comme indiqué à la section 4.3.5 de la spécification JAX-RPC.
          • L'attribut wsdl:operation parameterOrder définit l'ordre des paramètres.
        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) ... 
    • Mappage de wsdl:binding :
      La commande WSDL2Java utilise les informations wsdl:binding pour générer un raccord côté client spécifique de l'implémentation. WebSphere Application Server utilise les informations wsdl:binding du côté serveur pour désérialiser adéquatement la demande, appeler le service Web et sérialiser la réponse. Les informations contenues dans wsdl:binding ne doivent pas affecter la génération de l'interface SEI, mais elles le peuvent si le format encapsulé document/literal est utilisé ou lorsqu'il y a des pièces jointes MIME.
      • Pièces jointes MIME :
        Pour un fichier WSDL compatible WSDL 1.1, une partie d'un message opérationnel, défini dans la liaison comme étant une pièce jointe MIME, devient un paramètre du type de la pièce jointe, quelle que soit la partie déclarée. Exemple :
        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) ... 
        JAX-RPC requiert la prise en charge des types MIME suivants :
        Tableau 4. 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
        multipart/* javax.mail.internet.MimeMultipart
        text/xml javax.xml.transform.Source
        application/xml javax.xml.transform.Source
    • Mappage de wsdl:service :

      L'élément wsdl:service est mappé vers une interface de service généré. Cette interface contient des méthodes permettant d'accéder à chacun des ports dans wsdl:service. L'interface de service généré est présentée dans les sections 4.3.9, 4.3.10 et 4.3.11 de la spécification JAX-RPC.

      En outre, l'élément wsdl:service est mappé vers la classe ServiceLocator spécifique à l'implémentation qui est celle d'une interface de service généré.

Pour plus d'informations sur cet outil, consultez les informations relatives à l'outil WSDL2Java pour les applications JAX-RPC (Java API for XML-based Remote Procedure Call).


Mappage entre messages WSDL et SOAP

Le fichier WSDL définit le format du message SOAP envoyé via des connexions de réseau. La commande WSDL2Java et l'environnement d'exécution WebSphere Application Server utilisent les informations contenues dans le fichier WSDL pour confirmer que le message SOAP est correctement sérialisé et désérialisé.

Si un wsdl:binding indique qu'un message est envoyé au format RPC, le message SOAP contient un élément définissant l'opération. Si un wsdl:binding indique que le message est envoyé à l'aide du format de document, le message SOAP ne contient pas l'élément operation.

Si wsdl:part est défini à l'aide de l'attribut type, le nom et le type de la partie sont utilisés dans le message. Si wsdl:part est défini à l'aide de l'attribut element, le nom et le type de l'élément sont utilisés dans le message. L'attribut element n'est pas pris en charge par la spécification JAX-RPC si use="encoded".

Si wsdl:binding indique qu'un message est codé, les valeurs contenues dans le message sont envoyées avec l'information xsi:type. Si wsdl:binding indique qu'un message est littéral, les valeurs contenues dans le message ne sont pas envoyées avec l'information xsi:type. Exemple :
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>
			<attribut d'élément non admis en mode rpc/encodé> 
		</ns:method>
	</soap:body>
 
DOCUMENT/LITERAL  non encapsulé 
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>

Icône indiquant le type de rubrique Rubrique de référence



Icône d'horodatage Dernière mise à jour: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=rwbs_map
Nom du fichier : rwbs_map.html