Commander un Arduino avec une tablette Android

- Etude de cas -

IX. Implémentation du service REST du serveur▲

La couche web expose la couche [métier] aux clients web via un service REST.

A lire

paragraphes 4.3.2 et 9.6 du document [ref2] ;

IX-A. Le projet Eclipse▲

en [1], le projet Eclipse est un projet Maven [2] ;
en [3], les dépendances Maven du projet. Celui-ci dépend du projet de la couche [métier]. Les autres dépendances en découlent en cascade ;
en [4], la classe [RestMetier] implémente la couche [métier].

IX-B. Les dépendances Maven▲

Le fichier [pom.xml] du projet Maven est le suivant :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
41.
42.
43.
44.
45.
46.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

    <groupId>istia.st.avat.server</groupId>
  <artifactId>server-rest</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>war</packaging>

  <name>server-rest</name>

  <properties>
    <endorsed.dir>${project.build.directory}/endorsed</endorsed.dir>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <releaseCandidate>1</releaseCandidate>
    <spring.version>3.1.1.RELEASE</spring.version>
    <jackson.mapper.version>1.5.6</jackson.mapper.version>
  </properties>

  <repositories>
    <repository>
      <id>com.springsource.repository.bundles.release</id>
      <name>SpringSource Enterprise Bundle Repository - Release</name>
      <url>http://repository.springsource.com/maven/bundles/release</url>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-beans</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-web</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-webmvc</artifactId>
      <version>${spring.version}</version>
    </dependency>
    <dependency>
      <groupId>org.codehaus.jackson</groupId>
      <artifactId>jackson-mapper-asl</artifactId>
      <version>${jackson.mapper.version}</version>
    </dependency>
    <dependency>
            <groupId>istia.st.domotique.server</groupId>
            <artifactId>server-metier</artifactId>
            <version>1.0-SNAPSHOT</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      ...
    </plugins>
  </build>

</project>

le service REST est implémenté à l'aide du framework SpringMVC. On trouve donc un certain nombre de dépendances sur ce framework (lignes 29-48) ;
lignes 49-53 : le serveur REST va échanger avec ses clients des objets au format JSON (JavaScript Object Notation). C'est une représentation texte des objets. Un objet JAVA peut être sérialisé en un texte JSON. Inversement, ce dernier peut être désérialisé pour créer un objet JAVA. Côté serveur, la bibliothèque Jackson est utilisée pour faire ces opérations ;
lignes 54-58 : le serveur REST a une dépendance sur la couche [métier] que nous avons décrite.

IX-C. La configuration du service REST▲

Un service REST est une application web et à ce titre est configurée par un fichier [web.xml] classique :

est le suivant :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>REST for AVAT</display-name>
  <servlet>
    <servlet-name>restservices</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>/WEB-INF/rest-services-config.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>restservices</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
</web-app>

lignes 4-12 : définition d'une servlet, une classe capable de traiter les requêtes HTTP des clients web ;
ligne 5 : son nom restservices. On peut l'appeler comme on veut ;
ligne 6 : la servlet qui gère les requêtes HTTP des clients web. C'est la classe [DispatcherServlet] de SpringMVC ;
lignes 7-10 : indiquent le fichier de configuration de la servlet, ici [WEB-INF/rest-services-config.xml] ;
ligne 11 : la servlet sera chargée au démarrage du serveur, ici un serveur Tomcat 7 ;
lignes 13-16 : les URL (ligne 15) traitées par la servlet restservices (ligne 14).

Au final, ce fichier indique que toutes les URL (ligne 15) seront gérées par la servlet restservices (ligne 14) définie lignes 4-12.

La classe [DispatcherServlet] est configurée par le fichier [] suivant :

Sélectionnez

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:oxm="http://www.springframework.org/schema/oxm"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
                            http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd
                            http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd
                            http://www.springframework.org/schema/oxm
                            http://www.springframework.org/schema/oxm/spring-oxm-3.0.xsd
                            http://www.springframework.org/schema/util
                              http://www.springframework.org/schema/util/spring-util-3.0.xsd">


  <!-- thread d'enregistrement des arduinos -->
  <bean id="recorder" class="arduino.dao.Recorder" init-method="init">
    <property name="port" value="100"/>
    <property name="ip" value="192.168.2.1"/>
    <property name="nbConnexions" value="5"/>
    <property name="traced" value="true"/>              
  </bean>
  <!-- couche dao -->  
  <bean id="dao" class="arduino.dao.Dao" init-method="init">
    <property name="recorder" ref="recorder"/>
    <property name="timeoutConnection" value="1000"/>
    <property name="timeoutRead" value="1000"/> 
    <property name="traced" value="true"/>                           
  </bean>
  <!-- couche métier -->
  <bean id="metier" class="arduino.metier.Metier">
    <property name="dao" ref="dao"/>
  </bean>
  
      <!-- Recherche des annotations SpringMVC dans les classes du package nommé -->
    <context:component-scan base-package="arduino.rest.metier" />

    <!-- L'unique View utilisée. Elle génère du JSON -->
    <bean
        class="org.springframework.web.servlet.view.json.MappingJacksonJsonView">
        <property name="contentType" value="text/plain" />
    </bean>

    <!-- Le convertisseur JSON -->
    <bean id="jsonMessageConverter"
        class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter" />

        <!-- la liste des convertisseurs de messages. Il n'y en qu'un : le JSON ci-dessus -->
    <bean
        class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
        <property name="messageConverters">
            <util:list id="beanList">
                <ref bean="jsonMessageConverter" />
            </util:list>
        </property>
    </bean>

</beans>

lignes 17-34 : configuration des couches [métier] et [DAO] du serveur ;
lignes 36-37 : il est possible de configurer Spring à l'aide d'annotations dans le code Java. C'est ce qui a été fait ici. La ligne 37 dit à Spring d'exploiter les annotations qu'il trouvera dans le package [arduino.rest.metier] ;

Il y trouvera trois genres d'annotations :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.

@Controller
public class RestMetier {

    // couche métier
    @Autowired
    private IMetier metier;
    @Autowired
    private View view;

    // liste des arduinos
    @RequestMapping(value = "/arduinos/", method = RequestMethod.GET)
    public ModelAndView getArduinos() {
...
    }

ligne 1 : l'annotation @Controller fait de la classe [RestMetier] un contrôleur SpringMVC, c-à-d une classe capable de traiter des requêtes HTTP. Celles-ci sont définies par l'annotation @RequestMapping qu'on voit en ligne 11 ;
lignes 5 et 7 : l'annotation @Autowired tague des champs qui sont des références sur des beans définis dans le fichier de configuration de SpringMVC. Dans notre cas, ce sont les beans des lignes 2 et 10 du fichier [rest-services-config.xml] ci-dessous. Les champs des lignes ainsi taguées sont automatiquement initialisés par Spring.

Revenons au code du fichier [rest-services-config.xml] :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.

<!-- couche métier -->
  <bean id="metier" class="arduino.metier.Metier">
    <property name="dao" ref="dao"/>
  </bean>
  
      <!-- Recherche des annotations SpringMVC dans les classes du package nommé -->
    <context:component-scan base-package="arduino.rest.metier" />

    <!-- L'unique View utilisée. Elle génère du JSON -->
    <bean
        class="org.springframework.web.servlet.view.json.MappingJacksonJsonView">
        <property name="contentType" value="text/plain" />
    </bean>

    <!-- Le convertisseur JSON -->
    <bean id="jsonMessageConverter"
        class="org.springframework.http.converter.json.MappingJacksonHttpMessageConverter" />

        <!-- la liste des convertisseurs de messages. Il n'y en qu'un : le JSON ci-dessus -->
    <bean
        class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter">
        <property name="messageConverters">
            <util:list id="beanList">
                <ref bean="jsonMessageConverter" />
            </util:list>
        </property>
    </bean>

</beans>

lignes 10-13 : les vues générées par l'unique contrôleur seront du type [MappingJacksonJsonView] (ligne 11). Cette vue va transformer son modèle en un unique objet JSON qu'elle va transmettre à son client. La ligne 12 configure un entête HTTP envoyé par le serveur à son client : elle dit que le serveur envoie du texte, ici l'objet JSON ;
lignes 16-17 : un « convertisseur de messages ». Je ne sais pas bien ce que signifie cette expression. Il semble que cela définisse une classe capable de créer un objet à partir d'une requête ou d'une réponse HTTP et inversement. Ici la classe [MappingJacksonHttpMessageConverter] va créer un objet JSON à partir du modèle de la vue. Inversement, elle est capable de produire un objet Java à partir de données JSON postées par le client ;
lignes 20-27 : il peut y avoir plusieurs « convertisseurs de messages » pour différents cas de figure. Entre les lignes 21-23, on met les beans chargés de « convertir des messages ». On y met donc le bean défini ligne 16. C'est le seul.

IX-D. Le code du service REST▲

Le serveur REST est implémenté par la classe [RestMetier] suivante :

Sélectionnez

package arduino.rest.metier;

...

import arduino.metier.IMetier;

@Controller
public class RestMetier {

    // couche métier
    @Autowired
    private IMetier metier;
    @Autowired
    private View view;

    // liste des arduinos
    @RequestMapping(value = "/arduinos/", method = RequestMethod.GET)
    public ModelAndView getArduinos() {
...
    }

    // clignotement
    @RequestMapping(value = "/arduinos/blink/{idCommande}/{idArduino}/{pin}/{duree}/{nombre}", method = RequestMethod.GET)
    public ModelAndView faireClignoterLed(@PathVariable("idCommande") String idCommande,
            @PathVariable("idArduino") String idArduino, @PathVariable("pin") String pin,
            @PathVariable("duree") String duree, @PathVariable("nombre") String nombre) {
...
    }

    // envoi de commandes JSON
    @SuppressWarnings("unchecked")
    @RequestMapping(value = "/arduinos/commands/{idArduino}", method = RequestMethod.POST, consumes = "application/json")
    public ModelAndView sendCommandesJson(@PathVariable("idArduino") String idArduino,
            @RequestBody List<Map<String, String>> commandes) {
...
    }

    // lecture pin
    @RequestMapping(value = "/arduinos/pinRead/{idCommande}/{idArduino}/{pin}/{mode}", method = RequestMethod.GET)
    public ModelAndView pinRead(@PathVariable("idCommande") String idCommande,
            @PathVariable("idArduino") String idArduino, @PathVariable("pin") String pin, @PathVariable("mode") String mode) {
...
    }

    // écriture pin
    @RequestMapping(value = "/arduinos/pinWrite/{idCommande}/{idArduino}/{pin}/{mode}/{valeur}", method = RequestMethod.GET)
    public ModelAndView pinWrite(@PathVariable("idCommande") String idCommande,
            @PathVariable("idArduino") String idArduino, @PathVariable("pin") String pin, @PathVariable("mode") String mode,
            @PathVariable("valeur") String valeur) {
...
    }

    // crée une réponse d'erreur
    private ModelAndView createResponseError(String numero, String message) {
        Map<String, Object> modèle = new HashMap<String, Object>();
        modèle.put("error", numero);
        modèle.put("message", message);
        return new ModelAndView(view, modèle);
    }
}

4 : en suivant l'exemple du paragraphe 4.3.2.5 de [ref2], écrire la classe [RestMetier].

IX-E. Les tests du service REST▲

Travail à faire : en suivant l'exemple du paragraphe 4.3.2.6 de [ref2], déployer et tester le service REST. Toutes les méthodes de ce service doivent être testées.

Voici quelques exemples :

URL	rôle
http://localhost:8080/server-restServer/arduinos/	rend la liste des Arduinos connectés
http://localhost:8080/server-restServer/arduinos/blink/1/192.168.2.3/8/100/20/	fait clignoter la led de la pin n° 8 de l'Arduino identifié par 192.168.2.3
http://localhost:8080/server-restServer/arduinos/pinRead/1/192.168.2.3/0/a/	lecture analogique de la pin n° 8 de l'Arduino identifié par 192.168.2.3
http://localhost:8080/server-restServer/arduinos/pinRead/1/192.168.2.3/5/b/	lecture binaire de la pin n° 5 de l'Arduino identifié par 192.168.2.3
http://localhost:8080/server-restServer/arduinos/pinWrite/1/192.168.2.3/8/b/1/	écriture binaire de la valeur 1 sur la pin n° 8 de l'Arduino identifié par 192.168.2.3
http://localhost:8080/server-restServer/arduinos/pinWrite/1/192.168.2.3/4/a/100/	écriture analogique de la valeur 100 sur la pin n° 4 de l'Arduino identifié par 192.168.2.3

Le test de la méthode [sendCommandesJson] est plus délicat :

Sélectionnez

1.
2.
3.
4.
5.
6.
7.

    // envoi de commandes JSON
    @SuppressWarnings("unchecked")
    @RequestMapping(value = "/arduinos/commands/{idArduino}", method = RequestMethod.POST, consumes = "application/json")
    public ModelAndView sendCommandesJson(@PathVariable("idArduino") String idArduino,
            @RequestBody List<Map<String, String>> commandes) {
...
}

ligne 3 : la méthode attend une requête POST qu'on ne peut pas simuler simplement avec un navigateur. Il faut des outils spéciaux ;
ligne 3 : la requête POST doit demander une URL de la forme [/arduinos/commands/192.168.2.3] pour envoyer à l'Arduino désigné une liste de commandes JSON ;
ligne 5 : cette liste de commandes JSON est le corps du POST (@RequestBody), c-à-d la valeur postée.

Pour tester cette méthode, on pourra utiliser un navigateur Chrome avec l'extension [Advanced REST Client] :

Pour installer cette extension, on pourra procéder de la façon suivante :

lancer le navigateur Chrome ;
en [1], personnaliser le navigateur ;
en [2], sélectionner l'option [Outils / Extensions] ;
en [3], installer l'extension [Advanced REST Client].

Une fois cette extension installée dans Chrome, on peut l'utiliser de la façon suivante :

en [1], en bas du navigateur, on sélectionne la vue [Applications]. Il faut parfois créer un nouvel onglet pour avoir cette barre de sélection ;
en [2], on lance l'extension désirée ;
en [1], l'URL de la méthode REST à tester ;
en [2], la méthode GET ou POST pour envoyer la requête ;

La requête est envoyée en la validant ou via le bouton [Send].

en [3], les entêtes HTTP de la demande ;
en [4], les entêtes HTTP de la réponse ;
en [5], la réponse JSON renvoyée par le serveur REST ;

Toutes les méthodes GET du service REST peuvent être testées ainsi. Pour la méthode POST [sendCommandesJson], on procèdera ainsi :

en [1], l'URL de la méthode [sendCommandsJson] ;
en [2], la requête se fait via la commande HTTP POST ;
en [3], on indique que l'objet envoyé par le POST est du texte JSON ;
en [4], la liste des commandes JSON. On notera bien les crochets qui commencent et terminent la liste. Ici, dans la liste il n'y a qu'une commande JSON qui écrit la valeur binaire 0 sur la pin 8 de l'Arduino ;
en [5], la réponse JSON envoyée par le serveur ;

Le serveur est désormais écrit. Il servira aussi bien aux client natifs Android qu'aux client web mobiles.

Vous avez aimé ce tutoriel ? Alors partagez-le en cliquant sur les boutons suivants :

Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright © 2013 Serge Tahé. Aucune reproduction, même partielle, ne peut être faite de ce site ni de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.