R6.05 - Prog. Frameworks : Spring boot

    // create a hero
    @PostMapping("/heroes")
    public Hero createHero(@RequestBody HeroDTO hero)  {
        return heroesService.createHero( hero.getPublicName(), hero.getRealName(), hero.getPower(), hero.getPowerLevel());
    }

    // update hero by id
    @PutMapping("/heroes")
    public Hero updateHero(@RequestBody HeroDTO hero) throws ResourceNotFoundException {
        return heroesService.updateHero(hero.getId(), hero.getPublicName(), hero.getRealName(), hero.getPower(), hero.getPowerLevel());
    }

    public Hero createHero(String publicName, String realName, String power, Integer powerLevel) {
        Hero hero = new Hero(publicName, realName, power, powerLevel);
        heroesRepository.save(hero);
        return hero;
    }

    public Hero updateHero(Long id, String publicName, String realName, String power, Integer poweLevel) throws ResourceNotFoundException {
        Optional<Hero> heroOpt = heroesRepository.findById(id);
        if (heroOpt.isEmpty()) throw new HeroNotFoundException("updating hero with id = "+id);
        Hero hero = heroOpt.get();
        if (publicName != null) hero.setPublicName(publicName);
        if (realName != null) hero.setRealName(realName);
        if (power != null) hero.setPower(power);
        if (poweLevel != null) hero.setPowerLevel(poweLevel);
        heroesRepository.save(hero);
        return hero;
    }

    // example with response manipulation
    @GetMapping("/heroes/getbypower")
    public ResponseEntity<List<Hero>> getHeroesByPower(@RequestParam String power, @RequestParam(required = false) Boolean pattern) {
        List<Hero> list = null;
        if (pattern == null) pattern = false;
        list = heroesService.findAllByPower(power,pattern);

        // if list is empty, do not send the empty list but instead a NO_CONTENT status code
        if (list.isEmpty()) return ResponseEntity.status(HttpStatus.NO_CONTENT).body(null);
        // if list is not empty, send it, together with 2 customs response headers
        return ResponseEntity
                .ok()
                .header("myheader","toto")
                .header("otherheader","hello")
                .body(list);
    }

Démonstration :

• tester l'URL : http://localhost:8080/heroes/getbypower?power=qqqq. Dans l'inspecteur chrome, on remarque que la réponse est bien vide et que le status est 204 (pas de contenu)
• tester l'URL : http://localhost:8080/heroes/getbypower?power=pain. Dans l'inspecteur chrome, on remarque que le status de la réponse est 200 (ok), et qu'il y a bien 2 entêtes de réponse myheader et otherheader.

4°/ paginer des résultats de requête 

Même si les capacités des réseaux vont s'accroissant, il est toujours bien de faire attention de ne pas échanger des volumes de données trop importants. C'est pourquoi il est fréquent de recourir à la pagination pour récupérer des données potentiellement volumineuses.

La pagination consiste simplement à demander des données par morceaux en indiquant la taille d'un morceau et le numéro du morceau. Mais au lieu de parler de morceau, on utilise plutôt le terme historique de page car les données étaient généralement ensuite affichées comme sur une page. De plus, il est souvent possible de récupérer les données en les triant selon certains champs, par ordre croissant ou décroissant.

Cette fonctionnalité étant centrale et importante pour la performance d'une grosse applicaiton, spring propose un mécanisme qui automatise quasiment tout. Pour cela, il faut :

• utiliser un repository de type PagingAndSortingRepository, ce qui est le cas du JpaRepository utilisé dans la démonstration. Cela permet d'avoir accès à un méthode Page<T> findAll(Pageable p) qui permet de récupérer toutes les données de façon paginée.
• si besoin déclarer dans ce repository des méthodes plus précises, en leur ajoutant un paramètre Pageable. Ces méthodes doivent retourner un objet de type Page<T> ou T est le type d'objet géré par le repository. Par exemple Page<Hero>indAllByRealName(String realName, Pageable p)
• créer des méthodes de service qui prend en paramètre un objet Pageable et qui font appel à celles du repository.
• créer des méthodes contrôleurs qui prennent en paramètre un objet Pageable et qui font appel à celles du service.

Quand spring voit un contrôleur avec un paramètre Pageable, il récupère automatiquement dans les paramètre de requêtes les valeurs des champs page, size et sort pour créer un objet Pageable. Le problème est que la requête ne contient pas forcément tous ces champs. Il est donc possible de spécifier à spring des valeurs par défaut, grâce aux annotation @PageableDefault et @SortDefault.

Voici un exemple de pagination pour récupérer des héros. Dans le classe HeroesService, on ajoute :

    public Page<Hero> findAllWithPagination(Pageable pageable) {
        return heroesRepository.findAll(pageable);
    }

Remarque : pas besoin de déclarer findAll() dans HeroesRepository puisqu'elle fait partie des méthodes héritées.

Dans HeroesController, on ajoute :

@GetMapping("/heroes/paging")
    public Page<Hero> getAllHeroesWithPagination(@PageableDefault(page = 0, size = 5)
                                                     @SortDefault.SortDefaults({
                                                             @SortDefault(sort = "id", direction = Sort.Direction.ASC)
                                                     })Pageable pageable) {
        return heroesService.findAllWithPagination(pageable);
    }

Et c'est tout !

Démonstration :

• tester l'URL : http://localhost:8080/heroes/paging?page=0&size=3. On obtient un objet complexe, avec notamment le champ content qui est une liste de 3 héro triés par id croissant. Il y a aussi des champs très utiles tels que totalPages (= nombre total de pages), last (si dernière page ou non), offset (= page*size)
• tester l'URL : http://localhost:8080/heroes/paging?page=1&size=3&sort=powerLevel,desc. On obtient cette fois une liste de héros triés par niveau de pouvoir décroissant. 
• tester l'URL : http://localhost:8080/heroes/paging?page=5. On obtient normalement une liste vide, puisqu'il n'y a pas suffisamment de héro pour avoir une page 5.

5°/ Utiliser des fichiers CSV

Le TD n°1 a présenté comment remplir les tables de la BdD à la fin de l'initialisation de l'application, de deux façons : via un fichier ressource data.sql ou bien via des instructions dans un Runner. Il y a bien entendu d'autres solutions, dont la plus courante consiste à utiliser des fichiers csv.

Selon l'application, ce type de fichier peut être "intégré" aux ressources de l'application ou bien peut être uploadé via une route. Dans les deux cas, l'objectif est de lire le contenu de ce fichier via un service pour créer des instances d'entités, que l'on sauve ensuite dans le BdD via un repository.

La première étape consiste donc à écrire un service capable dune telle chose. Pour cela, le plus simple consiste à utiliser le package Apache de manipulation de csv. Pour les inclure au projet, il suffit d'éditer le pom.xml en ajoutant dans les dépendances :

<dependency>
	<groupId>org.apache.commons</groupId>
	<artifactId>commons-csv</artifactId>
	<version>1.8</version>
</dependency>

Ce package permet notamment d'utiliser les classes CSVParser et CSVRecord pour lire un csv et en extraire des enregistrements.

La classe représentant le service n'est pas très compliquée à écrire et l'on peut la réutiliser dans différents projets. Sa structuration est assez simple, avec :

• une méthode "générale" permettant de lire un flux d'octet (InputStream) venant d'un fichier csv, et d'obtenir une liste de données de la forme Iterable<CSVRecord>.
• des méthodes pour convertir des CSVRecord en une liste d'entité d'un certain type,
• des méthodes qui vont ouvrir un fichier csv pour obtenir un flux d'octet, appeler les méthodes précédentes pour obtenir des liste d'entités, pour enfin sauver celles-ci en BdD.

Les dernières méthodes peuvent au choix prendre en entrée un fichier csv sous la forme :

• d'une instance de la classe Resource, lorsque le fichier csv se trouve dans le répertoire resources du projet,
• d'une instance de MultipartFile, lorsque le fichier est reçu via une requête à l'application.

La deuxième étape consiste à créer utiliser ce service :

• soit dans un contrôleur avec une route pour uploader un fichier, en écrivant quelque chose du genre :

@RestController
public class HeroesController {
    private final CSVService csvService;
   ... // other attributes

    @Autowired
    HeroesController(CSVService csvService, ...) {
        this.csvService = csvService;
        ...
    }
    @PostMapping("/heroes/upload")
    public void uploadCSVForHeroes(@RequestParam("file") MultipartFile file) throws CSVConversionException {
        csvService.saveCSVToHeroes(file);
    }
}

•  soit dans un runner, qui utilise un fichier ressource, avec par exemple :

@Component
public class MyRunner implements CommandLineRunner {
    private final CSVService csvService;
    @Value("classpath:heroes.csv")
    Resource resourceFile;

    @Autowired
    public MyRunner(CSVService csvService) {
        this.csvService = csvService;
    }
    @Override
    @Transactional
    public void run(String... args) throws Exception {
        csvService.saveCSVToHeroes(resourceFile);
    }
}