SOA Cours 5 - Exercices : Web Services WS-* et RESTful



Les exercices de cette page ont pour objectif de vous faire découvrir les Web Services de manière concrète en utilisant les technologies Java et Java Enterprise Edition.

  1. Prise en main de l'environnement de développement
  2. Développement d'un service WS-*
  3. Client pour un service WS-*
  4. Client pour un service RESTful
  5. Développement d'un service RESTful

Prise en main de l'environnement de développement

L'environnement de développement utilisé dans ces exercices est composé de :

  • NetBeans : un environnement de développement (IDE - Integrated Development Environment), qui permet notamment d'éditer et compiler du code ;
  • GlassFish : un serveur d'application Java Enterprise Edition qui permet de déployer les applications développées.

Le but de ce premier exercice est de vous familiariser avec l'IDE NetBeans et avec le serveur d'applications GlassFish afin de vous permettre ensuite de développer et déployer des web services.

Prise en main du serveur d'applications GlassFish

NetBeans dispose nativement d'une interface d'interaction avec le serveur d'application GlassFish. C'est cette interface que nous allons utiliser le plus souvent.

Lancer NetBeans.

Dans l'onglet Services, aller à Servers > GlassFish Server 3.1.2 puis choisir Start dans le menu contextuel (clic droit avec la souris).

Regarder l'onglet GlassFish Server qui est apparu en bas de la fenêtre de Netbeans. A quoi sert-il ?

Toujours sur Servers > GlassFish Server 3.1.2, choisir View Admin Console dans le menu contextuel.

Dans le navigateur web qui est lancé automatiquement, vous pouvez alors accéder à l'interface web d'administration du serveur GlassFish. Le chargement de la page peut prendre un peu de temps mais vous devez obtenir quelque-chose qui ressemble à la figure ci-dessous.

Si un login et un mot de passe vous sont demandés, utilisez admin pour le login et adminadmin pour le mot de passe.

Quelles applications sont déjà déployées sur le serveur ?

Création d'un projet Web Application avec NetBeans

NetBeans est basé sur la notion de projet. Un projet correspond à tout ou partie d'une application que l'on souhaite développer.

Aller dans le menu File > New Project. Choisir Web Application dans la catégorie Java Web.

Dans l'écran Name and Location, nommer le projet "FactorialWebService" et l'enregistrer dans C:\Utilisateurs\[votre login]\Documents\NetBeansProjects. ATTENTION, cette étape est très importante sans quoi vous ne pourrez pas déployer votre module sur le serveur !

Si le répertoire "NetBeansProjects" n'existe pas dans "C:\Utilisateurs\[votre login]\Documents\", créez le.

Dans l'écran Server and settings, laisser les valeurs par défaut.

Dans l'écran Frameworks, laisser les valeurs par défaut. Puis, cliquer sur Terminer.

Le projet que vous venez de créer contient tous les éléments de base d'une application web. L'étape suivante consiste à déployer cette application sur le serveur et à tester son fonctionnement.

Déploiement de l'application web créée

Par défaut, lors de la création d'un projet de type Web Application, NetBeans créée une page web appelée index.jsp dans le répertoire Web Pages. Cette page sert de page d'accueil par défaut de l'application web ainsi créée.

Ouvrir le fichier index.jsp.

Cette page d'accueil générée par défaut par NetBeans contient le code suivant :

<%@page contentType="text/html" pageEncoding="UTF-8"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
        <title>JSP Page</title>
    </head>
    <body>
        <h1>Hello World!</h1>
    </body>
</html>

Sans rentrer dans les détails, cette page web contient du code HTML et également du code JSP (Java Server Pages) entre <% et %>. JSP est le langage permettant d'inclure du code Java dans des pages web afin de créer une interface web pour une application Java. Nous n'allons pas nous servir de la technologie JSP par la suite, mais cette page va simplement nous permettre de tester le bon déploiement de notre application : une fois déployée, lors de son exécution cette application doit afficher le texte "Hello World!" dans un navigateur web.

Sélectionner le projet de votre Web Application puis choisir Clean and Build dans le menu contextuel (clic droit).

Cette action déclenche la compilation du code de l'ensemble du projet et la génération d'une archive .war qui peut être déployée sur le serveur d'applications.

Sélectionner le projet de votre Web Application puis choisir Deploy dans le menu contextuel (clic droit).

Cette action déclenche le déploiement de l'application sur le serveur.

Avec un navigateur web, aller à l'URL http://localhost:8080/FactorialWebService/. Vous devez obtenir une page telle que celle-ci :

Vérifier dans la console d'administration de GlassFish que l'application aparait bien dans la liste des applications déployées (éventuellement rafraichir la page). Tester le lancement de l'application depuis la console en utilisant le lien Launch.

Vous êtes maintenant prêt à utiliser votre serveur d'applications pour déployer des Web Services !

Développement d'un service WS-*

L'objectif de cet exercice est de développer un service WS-* qui reçoit en paramètre un entier n, calcule n! (factorielle) et retourne le résultat.

Le code de cet exercice est à placer dans le projet "FactorialWebService" créé lors de l'exercice précédent.

Dans le dossier "Source Packages", créer un package Java. Dans ce package, créer une classe Java avec une méthode qui pour tout entier n retourne n!.

Annoter la classe de manière à l'exposer en tant que Web Service.

Déployer votre application sur le serveur (clic droit puis Deploy).

Regarder l'onglet GlassFish Server. A quelle URL votre service peut-il être interrogé ? Ou peut-on télécharger le contrat WSDL du service ? Et le XML Schema des données échangées par votre service ?

Dans un navigateur web, taper l'URL de votre service, suivie de ?Tester. Qu'avez-vous sous les yeux ?

Dans cet exercice, vous avez vu comment développer un Web Service à partir d'une classe Java. Dans l'exercice suivant, vous allez créer un client pour un Web Service.

NetBeans est capable générer un Web Service de façon partiellement automatique. Vous pouvez essayer cette fonctionnalité en créant un nouveau projet de type "Web Application" puis un créant un nouveau fichier de type "Web Service" (ou "Web Service from WSDL" si vous avez commencé par écrire le contrat WSDL comme c'est préconisé dans l'approche "contract first") en utilisant le menu File > New File > Web Services.

Développement d'un client pour un service WS-*

Sur la base de l'API JAX-WS, NetBeans propose un outil de génération automatique permettant d'obtenir un stub et une couche de traitement XML pour un service WS-* à partir de son contrat WSDL. C'est cet outil que vous allez utiliser maintenant pour créer un client pour le Web Service "CountryInfoService" permettant d'obtenir diverses informations sur des pays.

Découverte du service et configuration

Consulter la documentation du service "CountryInfoService". Où peut-on consulter son contrat WSDL ?

Quelles opérations sont mises à dispositions par le service ?

Vous allez utiliser ce Web Service "CountryInfoService" dans une application Java très simple.

Création du stub JAX-WS

Créer un nouveau projet de type Java Application appelé "CountryWebServiceClient" et l'enregistrer dans C:\Users\[votre login]\Documents\NetBeansProjects. ATTENTION, cette étape est très importante sans quoi vous pourriez rencontrer des problèmes à l'exécution !

Utiliser le menu File > New File > Web Services > Web Service Client pour lancer l'assistant de création automatique de client de Web Service de NetBeans.

Dans l'écran WSDL and Client location :

  1. Sélectionner WSDL URL et saisir l'URL du contrat WSDL du service ;
  2. Indiquer un nom de package Java pour les classes qui vont être générées automatiquement par NetBeans, comme par exemple countryinfo, puis cliquer sur "Finish".

Quelles sont les ressources qui sont automatiquement créées dans le projet NetBeans ? Ou peut-on retrouver la liste des opérations mises à disposition par le service ?

Utilisation du service depuis une application

Créer une classe Java avec une méthode main.

Au niveau du projet, faire apparaître le contenu du dossier "Web Service Reference" de manière à voir tous les éléments imbriqués jusqu'aux "feuilles" de la hiérarchie qui correspondent aux opérations disponibles sur le service référencé.

Sélectionner l'opération CapitalCity et la glisser avec la souris sur la classe Java juste en dessous de la méthode main.

Cette opération créée une méthode statique permettant d'appeler l'opération CapitalCity du service via le proxy.

Appeler cette méthode depuis la méthode main en lui donnant le code ISO d'un pays de votre choix et afficher le résultat.

Faire "Clean and Build" puis "Run" sur votre projet et vérifier le résultat dans l'onglet "CountryWebServiceClient (run)" qui s'affiche en bas de la fenêtre de NetBeans.

Utilisation avec des types de données complexes

Essayer maintenant d'utiliser l'opération CountriesUsingCurrency pour afficher la liste des pays qui utilisent la monnaie "EUR" (euro). De quel type est le résultat de cette opération ?

Regarder le contenu du répertoire "Generated Sources (jax-ws)", et ouvrir la classe "ArrayOfCountryCodeAndName". Que remarquez-vous ? Comment pouvez-vous utiliser cette classe pour afficher la liste des pays qui utilisent la monnaie euro ?

Vous savez maintenant comment créer automatiquement un stub JAX-WS pour un Web Service et l'utiliser dans une application Java.

A l'issue des exercices réalisés jusqu'à présent, vous êtes en mesure de créer un Web Service WS-* et un client standalone pour ce Web Service.

Il est possible de complexifier à loisir les services et les clients pour créer des applications plus riches. Il est possible d'exposer le contenu d'une base de donnée via un web service, par exemple. De plus, d'autres types de clients que les clients standalone peuvent être utilisés pour appeler des Web Services, comme par exemple des applications web (comme les clients web de test générés automatiquement par NetBeans).

Client d'un service RESTful

L'objectif de cet exercice est de créer un client permettant d'interroger un service RESTful de recherche géographique mis à disposition gratuitement par MapQuest.

Découverte du service

Le service s'appelle Nominatim, il réalise des opérations de géocodage et de géocodage inverse (reverse geocoding) et sa documentation est disponible en ligne.

Nominatim répond à des requêtes GET sur l'URL http://open.mapquestapi.com/nominatim/v1/search avec les paramètres suivants :

  • Un paramètre format qui permet de spécifier le format souhaité pour la réponse. Le service offre deux possibilités : xml ou json. Par exemple : format=xml.
  • Un paramètre q qui contient les mots clés de la requête. Par exemple : q=supelec (pour plusieurs mots-clés, utiliser le séparateur +, par exemple : q=supelec+rennes).
  • Un paramètre limit qui permet de limiter le nombre de résultats de la recherche. Par exemple : limit=3.

Exemple de requête HTTP complète : GET http://open.mapquestapi.com/nominatim/v1/search?format=xml&q=supelec&limit=3

Avec un client REST (comme celui-ci par exemple), faire une requête de recherche sur Nominatim et afficher les résultats.

Développement d'un client Java

L'objectif est maintenant d'interroger le service avec un client que vous aurez vous même développé en Java.

Créer un projet de type Java Application contenant une classe avec une méthode main.

Comme vu en cours avec l'API java.net, établir une connexion HTTP avec le service, puis passer une requête GET et afficher la réponse obtenue. Vous pouvez vous inspirer du code suivant :

// Préparation de la connexion
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.supelec.fr", 8080));
URL url = new URL("http://serveur:port/uri/du/service");
HttpURLConnection connexion = (HttpURLConnection) url.openConnection(proxy);

// Envoi de la requête
connexion.setRequestMethod("GET");
connexion.connect(); // send GET request

// Récupération du contenu de la réponse
System.out.println("Réponse :");
InputStream stream = connexion.getInputStream();

BufferedReader r = new BufferedReader(new InputStreamReader(stream));
String line;
while((line = r.readLine()) != null){
    System.out.println(line);
}

// Déconnexion
connexion.disconnect();

Exécuter le projet et vérifier les affichages réalisés. Faire varier les paramètres de la requête.

Vous savez maintenant comment interroger un service RESTful et l'utiliser dans une application Java.

Développement d'un service RESTful

La création d'un service RESTful ressemble à la création d'un service WS-* puisqu'il faut créer une classe Java et l'annoter (ici l'API Java utilisée est JAX-RS).

Cependant, la philosophie REST implique des différences fondamentales dans la façon de concevoir les services. En effet, pour être conforme à la vue "ressources" de REST lorsqu'on développe un service, il ne s'agit pas de concevoir une classe qui met à disposition des méthodes, mais de concevoir un ensemble de ressources (on utilise généralement une classe pour le conteneur et des classes pour les ressources contenues) que l'utilisateur peut consulter et modifier.

Pour cet exercice, vous implémenterez un service RESTful qui représente une ressource de type message de bienvenue.

Créer un projet de type Web Application.

Créer une classe Java qui représente la ressource "message de bienvenue".

Annoter la classe pour l'exposer sous la forme d'un service RESTful répondant aux requêtes GET, la réponse étant alors le contenu du message de bienvenue.

Si NetBeans demande de quelle façon vous souhaitez enregistrer votre service, comme indiqué sur la figure ci-dessous, choisir la première option comme indiqué ci-dessous pour que NetBeans "enregistre" automatiquement votre service :

L'enregistrement signifie que le serveur d'applications génère une application chargée de traiter les requêtes HTTP entrantes et les redirige vers le service, et inversement pour les réponses fournies par le service. Le nom de cette application générée par NetBeans (par défaut : "resources") apparaitra dans l'URL du service juste après le nom du projet.

Tester le service avec un client HTTP avec l'une des deux méthodes vues dans l'exercice précédent.

Dans ce dernier exercice, vous avez découvert comment créer un Web Service RESTful basique.

Des outils de génération automatique de code permettent de créer des services et des clients plus complets que ceux vus dans cet exercice. Jersey est une implémentation de JAX-RS fournie par Sun (Oracle) et permet de faire de genre d'opérations. Vous pouvez tester Jersey en utilisant les assistants de NetBeans suivants :

  • File > New File > Web Services > RESTful Web Service from patterns (choisir "Simple Root Resource" pour le plus simple des services) pour créer un service ;
  • File > New File > Web Services > RESTful Java Client pour créer un client.