Úloha 5 - Implementujeme servisný komponent cez JPA

Krok 1

Na tomto cvičení začneme využívať technológiu Spring. Najjednoduchšou cestou je nastaviť projekt tak, aby sa spúšťal ako Spring Boot projekt. To urobíte v konfiguračnom súbore pom.xml pridaním nového elementu parent (na miesto, kde je identifikátor a verzia projektu) so záznamom pre spring-boot-starter-parent:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.4.4</version>
    <relativePath/>
</parent>

Do sekcie dependencies pridajte závislosti potrebné pre ďalší postup na cvičení a odstráňte verzie závislostí (do tohto momentu už ich bude spravovať Spring parent). Výsledok by mal vyzerať nasledovne:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>
    
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
    </dependency>
</dependencies>

Projekt je teda nakonfigurovaný ako Spring Boot [2] projekt využívajúci knižnicu JPA [3].

Nová štruktúra adresárov projektu by mala byť nasledovná:

gamestudio  //hlavný adresár projektu gamestudio
├── src
│  ├── main  //zdrojové súbory kódu projektu
│  │  ├── java
│  │  │  └── sk
│  │  │     └── tuke
│  │  │        └── gamestudio  // hlavný balík projektu GameStudio
│  │  │           ├── entity   // balík pre entity servisných komponentov
│  │  │           ├── game     // balík s hrami
│  │  │           ├── server   // balík serverovej časti projektu
│  │  │           ├── service  // rozhrania a implementácie servisných komponentov
│  │  │           └── SpringClient.java  //nová hlavná trieda pre spustenie klientskej časti riešenia
│  │  └── resources  //zdroje projektu (obrázky, konfiguračné súbory atď.)
│  │     └── application.properties  //nastavenia projektu
│  └──  test  // adresár pre zdrojové súbory testov
├── .gitignore
├── pom.xml  //konfiguračný súbor Maven projektu

Skontrolujte a aktualizujte si najmä nastavenie URL, prihlasovacie meno a heslo pre vašu databázu:

#https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html
spring.datasource.url=jdbc:postgresql://localhost/gamestudio
spring.datasource.username=postgres
spring.datasource.password=postgres
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.hikari.maximumPoolSize=2
#spring.jpa.hibernate.ddl-auto=create-drop #premaže databázu pri každom spustení a vytvorí ju nanovo
spring.jpa.hibernate.ddl-auto=update #aktualizuje databázu bez jej zmazania
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.jdbc.lob.non_contextual_creation=true

Krok 2

V tomto kroku pridáte do entitných tried anotácie, ktoré umožnia použitie technológie Java Persistence API - skrátene JPA.

Príklad na entite Score:

package sk.tuke.gamestudio.entity;

import javax.persistence.GeneratedValue;
import javax.persistence.Id;
...

public class Score implements Serializable {
    @Id
    @GeneratedValue
    private int ident; //identifikator
    ...
    
    //doplneny bezparametricky verejny konstruktor
    public Score() {}

    //povodny konstruktor
    public Score(String player, String game, int points, Date playedOn) {...}

    public int getIdent() { return ident; }
    public void setIdent(int ident) { this.ident = ident; }

    ...
    
}

Vytvoreným entitným triedam chýba už len anotácia označujúca entitnú triedu a pomenovaný dopyt, ktorý sa využije v servisnom komponente JPA.

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.NamedQuery;
...

@Entity
@NamedQuery( name = "Score.getTopScores",
             query = "SELECT s FROM Score s WHERE s.game=:game ORDER BY s.points DESC")
@NamedQuery( name = "Score.resetScores",
             query = "DELETE FROM Score")
public class Score implements Serializable {
    ...
}

Krok 3

Príklad implementácie služby Score v JPA :

package sk.tuke.gamestudio.service;

import sk.tuke.gamestudio.entity.Score;

import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.transaction.Transactional;
. . .

@Transactional
public class ScoreServiceJPA implements ScoreService {
    
   @PersistenceContext
   private EntityManager entityManager;

   @Override
   public void addScore(Score score) throws ScoreException {
      entityManager.persist(score);
   }

   @Override
   public List<Score> getTopScores(String game) throws ScoreException {
       return entityManager.createNamedQuery("Score.getTopScores")
           .setParameter("game", game).setMaxResults(10).getResultList();
   }

    @Override
    public void reset() {
        entityManager.createNamedQuery("Score.resetScores").executeUpdate();
        // alebo:
        // entityManager.createNativeQuery("delete from score").executeUpdate();
    }
}

Vysvetlenie :

• Anotácia @Transactional je anotácia definujúca novú transakčnú službu.
• PersistenceContext - predstavuje niečo ako vyrovnávaciu pamäť. Má svoje vlastné, nezdieľané pripojenie na databázu (viac o JPA konceptoch).
• EntityManager entityManager - je injektovaná inštancia správcu entít, reprezentuje PersistenceContext; do tejto premennej bude automaticky vložená jeho inštancia.
• entityManager.persist(score) - uloží danú entitu do databázy pomocou správcu entít.
• entityManager.createNamedQuery("Score.getTopScores") - využíva pomenovaný dopyt definovaný v anotácii @NamedQuery v triede Score na vytvorenie dopytu. Následne setParameter("game", game) nastaví parameter do tohto dopytu, getMaxResults(10) nastaví maximálny počet vrátených inštancií a getResultList() vráti výsledok dopytu vo forme zoznamu inštancií triedy Score.

Krok 4

V tomto kroku využijeme v našej hre vytvorené služby.

public class ConsoleUI {
    private Field field;

    @Autowired
    private ScoreService scoreService;

    ...
}

Krok 5

V tomto kroku hru pomocou novej hlavnej triedy spustíme spolu s vytvorenými službami ako SpringBoot aplikáciu.

Príklad definovania hlavnej triedy pre hru Minesweeper je nasledovný:

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import sk.tuke.gamestudio.game.mines.consoleui.ConsoleUI;
import sk.tuke.gamestudio.game.mines.core.Field;
import sk.tuke.gamestudio.service.ScoreService;
import sk.tuke.gamestudio.service.ScoreServiceJPA;

@SpringBootApplication
@Configuration
public class SpringClient {

    public static void main(String[] args) {
        SpringApplication.run(SpringClient.class, args);
    }

    @Bean
    public CommandLineRunner runner(ConsoleUI ui) {
        return args -> ui.play();
    }

    @Bean
    public ConsoleUI consoleUI(Field field) {
        return new ConsoleUI(field);
    }

    @Bean
    public Field field() {
        return new Field(9, 9, 1);
    }

    @Bean
    public ScoreService scoreService() {
        return new ScoreServiceJPA();
    }
}

Vysvetlenie:

• Anotácie @Configuration a @SpringBootApplication označujú hlavnú triedu Spring Boot aplikácie.
• Metóda main spúšťa projekt ako Spring Boot aplikáciu a definuje jej hlavnú triedu ako parameter metódy SpringApplication.run(...).
• Všetky metódy označené anotáciou @Bean sú komponenty, ktorých inštancie sú automaticky vytvárané počas behu projektu. Spôsob ich inicializácie sa definuje vo vnútri týchto metód.
• Hlavným komponentom aplikácie je komponent typu CommandLineRunner, ktorý predstavuje akýkoľvek komponent bežiaci v konzolovom rozhraní. V našom prípade definujeme, že týmto komponentom bude naše ConsoleUI a bude spúšťané metódou play().
• Ďalšími definovanými komponentmi sú ConsoleUI a Field, kde v oboch metódach špecifikujeme ich inicializáciu.

Pred prvým spustením odporúčame zmazať a nanovo vytvoriť databázu gamestudio (create-drop v application.properties). Tabuľky nevytvárajte, budú vytvorené automaticky na základe anotovaných entít. Aj to je jedna z užitočných vlastností JPA.

Po dokončení potrebných úprav spustite vašu hru a overte jej funkčnosť aj funkčnosť komponentov služieb. Hra by sa už mala spúšťať prostredníctvom Spring Boot.

Krok 6