Développement des WSDL

Un Document WSDL est constitué par deux parties le tout à l’intérieur d’une racine représentée par la balise <definitions>:

Partie abstraite : qui décrit les messages et les opérations disponibles. Elle comporte les éléments suivants :

- Type : représenté par la balise <types>, contient la définition des types des données

exprimée sous forme de XML Schema. Un seul est autorisé.

- Message : représenté par la balise <message>, décrit les messages à transmettre

(paramètre d’une opération, valeur de retour, exception, …). Plusieurs sont autorisés.

- Type de port : représenté par la balise <PortType>, décrit l’ensemble d’opérations (~ Interface au sens Java), où chacune possède 0 ou plusieurs messages en entrée et 0 ou plusieurs messages de sortie ou de fautes. Plusieurs sont autorisés.

Partie concrète : décrit le protocole à utiliser et le type d’encodage à utiliser pour les messages. Plusieurs parties concrètes peuvent être proposées pour la partie abstraite afin de pouvoir réutiliser cette dernière. La partie concrète comporte les éléments suivants :

- Binding : représenté par la balise <binding>, spécifie une liaison entre un portType et un

protocole (SOAP, http). Plusieurs sont autorisés.

3

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

- Port : représenté par la balise <port>, définit où est localisé le service web et le binding

à utiliser grâce à des URLs. Plusieurs sont autorisés.

- Service : représenté par la balise <service>, regroupe l’ensemble des ports. Plusieurs sont

autorisés.

2. WSDL par l’exemple : Carnet d’adresse

Le service Notebook fournit trois opérations :

- une opération addPerson qui prend en paramètre un objet Person et retourne un booléen

pour indiquer l’état de création

- une opération addPerson qui prend en paramètre trois chaines de caractères (name,

address et birthyear) sans retour

- une opération getPersonByName qui prend en paramètre une chaîne de caractère et

retourne un objet Person

- une opération getPersons sans paramètre en entrée et qui retourne un tableau d’objets

Person

L’accès au service est réalisé par l’intermédiaire de messages SOAP (étudié en détail dans le prochain cours). Le protocole utilisé pour l’échange des messages SOAP est HTTP et le style utilisé est du RPC.

4

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

Elément Types

L’élément <types> contient la définition des types utilisés pour décrire la structure des messages échangés par le Web Service. Le système de typage est généralement un Schema XSD mais d’autres systèmes sont autorisés (RELAX NG par exemple). Cet élément peut être facultatif si les types utilisés par les messages sont des types de bases (Integer, Boolean, … ). Dans le cas de structures complexes (Person par exemple) un Schema XML est alors employé

Exemple : Définition des types pour Netbook service

<definitions name="Notebook" targetNamespace=http://notebookwebservice.lisi.ensma.fr/ xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns=http://notebookwebservice.lisi.ensma.fr/ xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"> <types> <xsd:schema targetNamespace="http://notebookwebservice.lisi.ensma.fr/"> <xsd:complexType name="person"> <xsd:sequence> <xsd:element name="address" type="xs:string" minOccurs="0"/> <xsd:element name="birthyear" type="xs:string"minOccurs="0"/> <xsd:element name="name" type="xs:string" minOccurs="0"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="personArray" final="#all"> <xsd:sequence> <xsd:element name="item" type="tns:person" minOccurs="0" maxOccurs="unbounded" nullable="true"/> </xsd:sequence> </xsd:complexType> </xsd:schema> </types> ... </definitions> Une personne est définie par une adresse, une année de naissance et un nom. Le type personarray représente un tableau de personnes.

La définition des types peut également être importée à partir d’un fichier Schema XML, qui doit être accessible au même titre que le document WSDL. Cependant, l’adresse de l’hôte du Schema XML n’est pas forcément la même que celle du document WSDL, cette séparation permet de réutiliser des types dans plusieurs WSDL différents et d’éviter d’alourdir le document WSDL. Par la suite nous privilégions la séparation des types du document WSDL.

Exemple : importation du fichier XSD définissant les types de Notebook service.

5

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

<definitions targetNamespace="http://notebookwebservice.lisi.ensma.fr/" name="Notebook" xmlns:xsd="http://www.w3.org/2001/XMLSchema" ...> <types> <xsd:schema> <xsd:import namespace="http://notebookwebservice.lisi.ensma.fr/" schemaLocation="Notebook_schema1.xsd"/> </xsd:schema> </types> ... </definitions> Elément messages

L’élément <message> permet de décrire les messages échangés par les services en précisant les paramètres d’entrées des opérations, les paramètres de sorties et les exceptions. Chaque

<message> est identifié par un nom (attribut name) et est constitué d’un ensemble d’éléments <part>. En quelque sorte un élément <part> correspond à un paramètre d’une opération. Si une opération est décrit par plusieurs paramètres, plusieurs éléments <part> seront à définir. L’élément <part> est défini par un nom (attribut name) et un type (attribut type).

Exemple : Définition des messages pour Netbook service

<definitions targetNamespace="http://notebookwebservice.lisi.ensma.fr/" name="Notebook" ...> <types> ... </types> <message name="addPersonWithComplexType"> <part name="newPerson" type="tns:person"/> </message> <message name="addPersonWithComplexTypeResponse"> <part name="addPersonWithComplexTypeResult" type="xsd:boolean"/> </message> <message name="addPersonWithSimpleType"> <part name="name" type="xsd:string"/> <part name="address" type="xsd:string"/> <part name="birthyear" type="xsd:string"/> </message> <message name="getPerson"> <part name="personName" type="xsd:string"/> </message> <message name="getPersonResponse"> <part name="getPersonResult" type="tns:person"/> </message> <message name="getPersons"/>

6

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

<message name="getPersonsResponse"> <part name="getPersonsResult" type="tns:personArray"/> </message> </definitions> Le message addPersonWithComplexType est utilisé pour l’appel d’une opération avec une seule partie. Cette dernière pointe sur un type person qui est défini par l’élément <types>. De même pour le message addPersonWithComplexTypeResponse qui est utilisé pour le résultat d’une opération avec une seule partie. Tandis que le message addPersonWithSimpleType est utilisé pour l’appel d’une opération avec trois parties.

Elément portType et sous élément Operation

Un élément <portType> est un regroupement d’opérations et peut être comparé à une interface Java. L’élément <portType> est identifiable par un nom (attribut name) et est composé de sous élément <operation>. Une opération est comparable une méthode Java, qui est identifiable par un nom (attribut name). La description des paramètres est obtenue par une liste de messages.

Une opération exploite les messages via les sous éléments suivants :

- -

-

<input> : message transmis au service <output> : message produit par le service

<fault> : message d’erreur (très proche des exceptions) Chaque sous élément

possède les attributs suivants :

- -

name : nom explicite donné au message (optionnel)

message : référence à un message (défini précédemment)

La surcharge d’opération est autorisée sous condition que les Messages <input> et/ou <ouput> soient différents.

Exemple : Définition des Ports pour Netbook service

<definitions targetNamespace="http://notebookwebservice.lisi.ensma.fr/" name="Notebook" ...> <types> ... </types> <message> ... </message> <portType name="Notebook"> <operation name="addPerson"> <input message="tns:addPersonWithComplexType"/> <output message="tns:addPersonWithComplexTypeResponse"/> </operation>

7

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

<operation name="addPerson" parameterOrder="name address birthyear"> <input message="tns:addPersonWithSimpleType"/> </operation> <operation name="getPerson"> <input message="tns:getPerson"/> <output message="tns:getPersonResponse"/> </operation> <operation name="getPersons"> <input message="tns:getPersons"/> <output message="tns:getPersonsResponse"/> </operation> </portType> </definitions> L’opération addPerson est surchargée. Il est possible aussi de fixer l’ordre des paramètres définis par cette opération.

Il est possibilité de définir une opération suivant quatre modèles

1. One-way : envoi de messages

Le client du service envoie un message à l’opération et n’attend pas de réponse. Un seul message <input> est uniquement utilisé.

<operation name="addPerson" parameterOrder="name address birthyear"> <input message="tns:addPersonWithSimpleType"/> </operation> 2. Request/Response : question – réponse

Le client du service envoie un message à l’opération et un message est retourné au client. Un message <input>, un message <output> et un message <fault>

<operation name="addPerson" parameterOrder="name address birthyear"> <input message="tns:addPersonWithSimpleType"/> </operation> <operation name="addPerson"> <input message="tns:addPersonWithComplexType"/> <output message="tns:addPersonWithComplexTypeResponse"/> </operation>

3. Notification : notification

Le service envoie un message au client. Un seul message <output> est uniquement utilisé.

<operation name="personStatus"> <output message="trackingInformation"/> </operation>

4. Solicit - response : sollicitation - réponse

8

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

Le client reçoit un message du service et répond au service. Un message <ouput>, un message <input> et un message <fault>

<operation name="personStatus"> <output message="trackingInformation"/> </operation> <operation name="clientQuery"> <output message="bandWithRequest"/> <input message="bandwidthInfo" /> <fault message="faultMessasge" /> </operation>

Elément Binding

Un élément <binding> permet de réaliser la partie concrète d’un élément <portType>. Il décrit précisément le protocole à utiliser pour manipuler un élément <portType> : SOAP 1.1 et 1.2,

HTTP GET & Post (pour le transfert d’images par exemple), MIME. Plusieurs éléments <binding> peuvent être définis de sorte qu’un élément portType peut être appelé de différentes manières. La structure de l’élément <binding> dépend du protocole utilisé.

Structure générale de l’élément <binding> sans précision sur le protocole employé.

<definitions> ... <binding name="NamePortBinding" type="tns:portType"> <!-- Décrit le protocole à utiliser --> <operation name="operation1"> <!-- Action du protocole sur l’opération --> <input> <!-- Action du protocole sur les messages d’entrés (input) - -> </input> <output> <!-- Action du protocole sur les messages de sorties (ouput) - -> </output> <fault> <!-- Action du protocole sur les messages d’erreurs (fault) - -> </fault>

</operation>

</binding>

</Definitions>

9

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

Le schema XML de WSDL ne décrit pas les sous éléments de binding, operation, input, ouput et fault. Ces éléments sont spécifiques aux protocoles utilisés.

est

défini

SOAP

binding

l’espace

: par Le http://schemas.xmlsoap.org/wsdl/soap/. Le préfixe utilisé est généralement soap (de la forme <soap:binding>). Différentes versions peuvent être utilisées : 1.1 et 1.2 (dans la suite nous utiliserons la version 1.1). Les principales balises à exploiter dans le binding sont <soap:binding>, <soap:operation>, <soap:body>, <soap:header>, <soap:headerfault> et <soap:fault>. A noter que nous détaillerons certains aspects dans le cours consacré au protocole SOAP.

suivant

noms

de

Exemple : Définition d’un binding SOAP 1.2

<definitions ...> <!-- Définition de la partie Abstraite du WSDL --> <binding name="NoteBookPortBinding" type="tns:Notebook"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/> <operation name="addPersonWithComplexType"> <soap12:operation soapAction=

"http://notebookwebservice.fr/addPersonWithComplexType"/>

<input> <soap:body use="literal" namespace="http://notebookwebservice.fr/"/> </input> <output> <soap12:body use="literal" namespace="http://notebookwebservice.fr/"/> </output> </operation> <operation name="addPersonWithSimpleType"> <soap12:operation soapAction=""/> <input> <soap12:body use="literal" namespace="http://notebookwebservice.fr/"/> </input> </operation> <operation name="getPerson"> <soap12:operation soapAction=""/> <input> <soap12:body use="literal" namespace="http://notebookwebservice.fr/"/> </input> <output> <soap12:body use="literal" namespace="http://notebookwebservice.fr/"/> </output>

10

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

</operation>

</binding>

</definitions>

L’élément <soap:binding> doit être présent lors de la définition d’un binding à base de messages SOAP.

<definitions ...> <!-- Définition de la partie Abstraite du WSDL --> <binding ...> <soap:binding transport="uri"? style="rpc|document"/> </binding> </definitions>

L’attribut style permet d’indiquer la façon dont sont créés les messages SOAP pour l’ensemble des opérations : rpc (encodage défini par SOAP RPC) et document (encodage sous forme d’élément XML). L’attribut transport permet de préciser le protocole à utiliser pour le transport des messages SOAP : HTTP : http://schemas.xmlsoap.org/soap/http, SMTP, FTP, …

L’élément <soap:operation> doit être présent pour chaque opération définie dans la partie abstraite du document.

<definitions ...> <!-- Définition de la partie Abstraite du WSDL --> <binding ...> <operation ...> <soap:operation soapAction="uri"? style="rpc|document"?>? </operation> </binding> </definitions>

L’attribut soapAction permet de préciser la valeur de l’en-tête HTTP (qui est généralement une combinaison du namespace et du nom de l’opération). L’attribut style permet de préciser la façon dont sont créés les messages SOAP de l’opération en question (RPC ou document). L’élément <soap:body> précise le format des messages échangés par une opération. Il y a autant d’élément <soap:body> qu’il y a de messages définis par une opération (<input>, <ouput> et <fault>).

<definitions ...> <!-- Définition de la partie Abstraite du WSDL --> <binding ...> <operation ...> <input> <soap:body parts="nmtokens"? use="literal|encoded"? encodingStyle="uri-list"? namespace="uri"?>

11

Université Virtuelle de Tunis Développement Orienté Services Développement des WSDL

</input> <output> <soap:body parts="nmtokens"? use="literal|encoded"? encodingStyle="uri-list"? namespace="uri"?> </output> </operation> </binding> < /definitions >

L’attribut use caractérise la forme des parties des messages : encoded pour une transformation suivant un mécanisme défini par l’attribut encodingStyle et litteral sans transformation des parties des messages, elles apparaissent directement.

Elément Service et Port

L’élément service définit l’ensemble des points d’entrée du Service Web, en regroupant des éléments <port>. Ce dernier permet de spécifier une adresse pour un binding donné. Un port est défini par deux attributs : name (nom du port) et binding (nom du binding). Le corps de l’élément <port> est spécifique au protocole utilisé pour définir le binding. Dans le cas d’un binding de type SOAP, un élément <soap:address> précise l’URI du port. Il est par conséquent possible d’appeler un service à des endroits différents (plusieurs éléments port).

Exemple : Définition d’un service

<definitions ...> <!-- Définition de la partie Abstraite du WSDL --> <binding ...> </binding> <service name="Notebook"> <port name="NoteBookPort" binding="tns:NoteBookPortBinding"> <soap:address location="http://localhost:8080/NotebookWebService/notebook"/> </port> </service> </definitions>

3. Outils pour la construction de WSDL

Il existe plusieurs outils pour construire un document WSDL, on peut citer les plus connus tels que : Notepad++ (éditeur de texte puisqu’il s’agit d’XML), Eclipse JavaEE, Netbeans, Visual Studio et tous les environnements de développement qui manipulent les Services Web.

Il existe aussi des outils pour valider un document WDSL, tel que www.validwsdl.com et des outils pour manipuler un WSDL, tels que SOAPUI.

12