R6.05 - Prog. Frameworks : Spring boot

package com.td1.example.demo1.control;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/")
    public String home() {
        return "<h2>Welcome home</h2>";
    }

    @GetMapping(value= {"/hello","/hello/{name}"})
    public String hello(@PathVariable(required = false) String name) {
        if (name != null) {
            return "Hello " + name;
        }
        return "Go to hell, impolite one !";
    }
}

Explications :

• L'annotation @RestController permet de spécifier que cette classe représente un contrôleur pour une API REST, ce qui implique notamment que les méthodes qu'elle contient peuvent se contenter de retourner une valeur afin que celle-ci soit automatiquement empaquetée dans la réponse au client, soit sous forme de simple chaîne de caractère comme dans cette démonstration, soit en JSON (cf. démo suivante). 
• NB : pour les applications web non API, qui veulent retourner du contenu HTML, il est préférable d'utiliser l'annotation @Controller, comme abordé dans un futur article.
• L'annotation @GetMapping permet d'associer une route pour une requête GET à la méthode contrôleur qui vient juste après. Le contenu entre parenthèse peut être simplement la route, ou bien plusieurs champs afin de paramétrer la requête. Dans le code ci-dessus, on voit que le champ value permet de spécifier les différentes route possibles pour appeler le contrôleur qui suit. Il est également possible de définir des entêtes, des paramètres, etc.

Démonstration :

• Le projet généré contient déjà une configuration d'exécution. Il suffit donc de cliquer sur la flèche verte pour lancer la compilation puis l'exécution.
• On remarque qu'un répertoire target s'est créé à la racine du projet. C'est lui qui contient le résultat de la compilation.
• On constate dans la console qu'il y a bien un serveur tomcat lancé sur le port 8080 (cf. Figure 3)

Figure 3 : affichage console au lancement de la démonstration 1

• Dans un navigateur, taper localhost:8080. On obtient l'affichage du titre "Welcome home". On constate que la chaîne renvoyée par l'API contient du HTML qui a été interprété par le navigateur. Si on va dans l'inspecteur, onglet "Réseau" et que l'on clique sur la requête, on voit que dans les entêtes de réponse on a : Content-Type : text/html. C'est pour cela que le navigateur interprète le contenu de la réponse comme du HTML.
• si on tape l'URL localhost:8080/hello/toto, on obtient l'affichage "Hello toto"
• si on tape l'URL localhost:8080/hello, on obtient l'affichage "Go to hell .."
• si on tape l'URL localhost:8080/hello/, on obtient un message d'erreur. En effet, toute route non conforme affiche ce message par défaut. On verra comment le modifier dans les futurs articles.
• si on tape ni'importe quelle autre route, par ex. localhost:8080/salut, on obtient également ce message d'erreur par défaut.

2.2°/ API avec base de données type SQL en mémoire/fichier

L'objectif de ce deuxième exemple est d'illustrer comment utiliser la base de données H2 ainsi que JPA/Hibernate afin de gérer de façon transparente les accès à la BdD, c'est-à-dire sans écrire de requête SQL mais en manipulant simplement des objets. Les opérations de manipulation de la BdD se font au travers d'une API. Cet exemple sert également à montrer comment initialiser la BdD à partir d'un fichier SQL, et/ou d'instructions Java.

ATTENTION : cet exemple n'utilise qu'une seule table et n'aborde donc pas comment prendre en compte des références entre des tables (avec clé étrangère), ou comment gérer les interactions one-to-many, many-to-one, ... Ce sera l'objet du cours suivant.

Voici les grandes lignes afin de créer ce type d'application :

• Chaque table va être décrite par une classe de type POJO (Plain Old Java Object) avec des annotations. Ces classes doivent généralement contenir :
  • un attribut représentant la clé primaire,
  • des attributs représentant les colonnes, potentiellement annotées, si par exemple le nom de l'attribut doit être un peu différent du nom de colonne, si la valeur est non nulle, ...
  • si besoin des annotations pour décrire des relations (one-to-many, many-to-one, ...) avec d'autres tables, donc d'autres POJO.
  • un ou plusieurs constructeurs,
  • des getters/setters pour chacun des attributs, sauf généralement la clé primaire
• Grâce à ces classes, nommées "entités", Spring Boot va être capable de créer la BdD et les tables correspondantes, si besoin, mais surtout de générer tout le code permettant de faire le lien entre des instances de ces entités et la BdD. Pour cela, Spring utilise un ensemble de fonctionnalités décrites par JPA sous la forme d'interfaces, et par défaut Hibernate qui implémente ces fonctionnalités. Hibernate est donc l'ORM qui va s'occuper de faire les requêtes SQL, sans que l'on ait normalement besoin d'écrire du SQL.
• Pour gérer très facilement l'accès aux tables et donc obtenir des instances d'entités, Spring Boot définit la notion de repository.
• Un repository est simplement une classe interface déclarant les méthodes d'accès à la BdD pour en obtenir des entités. Le côté "magique" est qu'il n'est pas nécessaire d'implémenter les méthodes car Spring Boot va le faire automatiquement. En effet, il est capable de déterminer quelle requête exécuter en fonction du nom des méthodes.

2.2.1°/ configuration générale de l'application

Pour créer le squelette de base du projet dans Spring Initializr, il faut ajouter comme dépendances : "Spring Web", "Spring Data JPA", "H2 database". Une fois le projet ouvert sous IDEA, la première chose à faire est de modifier la fichier de configuration principale de l'application, à savoir src/main/resources/applications.properties. Il faut ajouter à ce fichier tous les paramètres de configuration liés à l'accès à la BdD. Par exemple, pour cette démonstration, cela donne :

# 1 - app name
spring.application.name=demo2

# 2 - create the tables inferring from entities. NB : use update to just update the table structures, without dropping table contents
spring.jpa.hibernate.ddl-auto=create
# 3 - delay the execution of data.sql until database+tables are created
spring.jpa.defer-datasource-initialization=true

# 4.1 - setup db type I: H2 in memory with db name = herocorp
spring.datasource.url=jdbc:h2:mem:herocorp

# 4.2 - setup db type II: H2 in a "file" ~/herocorpdb. NB : must set init.mode to always to execute data.sql
#spring.sql.init.mode=always
#spring.datasource.url=jdbc:h2:file:~/herocorpdb

# 5 - enable the db console to have an access with url like localhost:8080/h2-console
spring.h2.console.enabled=true

# 6 - uncomment to show SQL requests on console
#spring.jpa.show-sql=true

Remarques :

• La 2ème ligne de configuration permet d'indiquer à Hibernate ce qu'il doit faire au sujet de la BdD lors du lancement de l'application. Dans le cas présent, il recrée les tables à chaque lancement, ce qui serait stupide en mode production, avec une vraie base de donnée, par exemple postgres. Il est donc possible de spécifier comme valeur none pour qu'il ne fasse rien. Dans ce cas, il est cependant possible d'utiliser un script SQL pour créer les tables, en le mettant dans /src/main/resources/script.sql
• Si Hibernate doit créer lui-même les tables, il va utiliser les entités pour inférer la structure des tables à créer.
• Pour initialiser des tables, il faut créer un fichier src/main/resources/data.sql contenant les instructions SQL pour remplir les tables. Malheureusement, il faut que ces tables existent au préalable et c'est pourquoi il faut attendre que hibernate ait fini d'analyser les entités pour créer la BdD et les tables. C'est le rôle de la 3ème linge de configuration.
• Il faut également indiquer quel type de BdD on utilise. Dans le cas présent, c'est une BdD "embarqué", qui peut soit être placée en mémoire, soit dans un fichier, comme on le voit avec les lignes de configuration 4.1 et 4.2. L'avantage du deuxième cas est que la BdD ne disparaît pas après l'arrêt de l'application.
• Les deux dernières lignes sont plus en vue du déboguage.

2.2.2°/ Structuration en packages

Pour structurer correctement le code, il est souhaitable de créer différents packages :

• model : contient les classes représentant les entités,
• repository : contient les classes représentant les repository
• service : contient les classes qui vont utiliser les repository pour récupérer des données
• control : contient les classes qui vont créer les routes et accéder aux classes de service pour récupérer les données.

A noter que dans les cas très simples, on peut également créer des contrôleurs qui utilisent directement les repository. Cependant, le fait de créer des services permet de conserver les contrôleurs tels quels même si on change de type de repository, par exemple quand on change de type de BdD.

2.2.3°/ Les entités

Dans cette démonstration, on suppose que l'on manipule une table représentant un héro. C'est pourquoi on crée un fichier model/Hero.java, comme suivant :

package com.td1.example.demo2.model;
import jakarta.persistence.*;

@Entity
@Table(name = "heroes")
public class Hero {

    @Id
    @GeneratedValue(strategy= GenerationType.IDENTITY)
    private Long id;

    private String publicName;
    private String realName;
    private String power;
    private int powerLevel;

    public Hero() {}
   ... // other constructors, getters/setters
}

package com.td1.example.demo2.repository;

import com.td1.example.demo2.model.Hero;
import org.springframework.data.jpa.repository.JpaRepository;

import java.util.List;

public interface HeroesRepository extends JpaRepository<Hero, Long> {

    // NB : no need to implement methods below : spring will do it automatically inferring it from their names !!
    Hero findByPublicName(String publicName);
    List<Hero> findAllByPower(String power);
}

package com.td1.example.demo2.service;

import com.td1.example.demo2.model.Hero;
import com.td1.example.demo2.repository.HeroesRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class HeroesService {
    private HeroesRepository heroesRepository;

    @Autowired
    public HeroesService(HeroesRepository heroesRepository) {
        this.heroesRepository = heroesRepository;
    }

    public List<Hero> findAll() {
        System.out.println("Getting all heroes");
        List<Hero> list = heroesRepository.findAll();
        return list;
    }
   ...
}

package com.td1.example.demo2.control;

import com.td1.example.demo2.model.Hero;
import com.td1.example.demo2.service.HeroesService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
public class HeroesController {

    private final HeroesService heroesService;

    HeroesController(HeroesService heroesService) {
        this.heroesService = heroesService;
    }

    @GetMapping("/heroes")
    public List<Hero> getAllHeroes() {
        System.out.println("Getting all heroes");
        List<Hero> list = heroesService.findAll();
        return list;
    }
   ...
   @GetMapping("/heroes/getbypower")
    public List<Hero> getHeroesByPower(@RequestParam String power, @RequestParam(required = false) Boolean pattern) {
        List<Hero> list = null;
        if ((pattern == null) || (pattern == false)) {
            System.out.println("Getting heroes with power " + power);
            list = heroesService.findAllByPower(power);
        }
        else {
            list = heroesService.findAllByPowerContaining(power);
        }
        return list;
    }  
   ...
}

package com.td1.example.demo2;

import com.td1.example.demo2.model.Hero;
import com.td1.example.demo2.repository.HeroesRepository;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

import java.util.List;

@Component
public class MyRunner implements CommandLineRunner {
    private static final Logger logger = LoggerFactory.getLogger(MyRunner.class);

    private final HeroesRepository heroesRepository;

    @Autowired
    public MyRunner(HeroesRepository heroesRepository) {
        this.heroesRepository = heroesRepository;
    }

    @Override
    public void run(String... args) throws Exception {

        // add a new hero, using a entity instance
        Hero phil = new Hero("stickman", "phil deferre", "superthin", 99);
        heroesRepository.save(phil);

        logger.info("getting all heroes");
        List<Hero> list = heroesRepository.findAll();
        for(Hero h : list) {
            System.out.println(h);
        }
    }
}