Actualització Canigó 3.6 a Canigó 3.8

A qui va dirigit

Aquesta guia va dirigida a tots aquells usuaris que vulguin actualitzar a Canigó 3.8 la seva aplicació Canigó 3.6.

Versió de Canigó

Els passos descrits en aquest document apliquen a la versió 3.8 del Framework Canigó.

Introducció

Al mes de gener del 2024 s’ha publicat la versió 3.8 del Framework Canigó. Aquesta versió és una versió LTS i es recomana actualitzar les aplicacions Canigó a aquesta versió per tal de tenir un suport continuat, així com la màxima estabilitat que proporciona una versió LTS.

L’objectiu d’aquesta guia és mostrar els procediments necessaris per a actualitzar una aplicació realitzada amb Canigó 3.8 i el punt de partida d’aquesta guia és una aplicació creada amb l’arquetipus maven de Canigó.

Configuració prèvia

A la Matriu de Compatibilitats podeu consultar les versions dels mòduls i components de Canigó de les versions 3.6.x i 3.8.x.

Per tant, caldrà fer:

1. Actualitzar els intervals de versions dels mòduls utilitzats per l’aplicació per a migrar a Canigó 3.8.0

2. Per a actualitzar de la versió 3.6 a la 3.8, es necessari realitzar l’actualització de les dependències del nostre projecte.

Les dependències específiques que han d’actualitzar-se la seva les següents:

2.1 Spring Boot 3.1.4

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

2.2 Spring Framework 6.1.1

   <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-context</artifactId>
      <version>6.1.1</version>
   </dependency>

2.3 OpenJDK 17

   <maven.compiler.source>17</maven.compiler.source>
   <maven.compiler.target>17</maven.compiler.target>

2.4 Spring Security 6.1.3

   <dependency>
      <groupId>org.springframework.security</groupId>
      <artifactId>spring-security-core</artifactId>
      <version>6.1.3</version>
   </dependency>

2.5 Junit 4 a Junit 5 (Jupiter) 5.10.1.

   <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <version>5.10.1</version>
      <scope>test</scope>
   </dependency>
   <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-engine</artifactId>
      <version>5.10.1</version>
      <scope>test</scope>
   </dependency>
   <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-params</artifactId>
      <version>5.10.1</version>
      <scope>test</scope>
   </dependency>

NOTA: Si tens dependències de Javax, és necessari actualitzar-les a la versió més recent de Jakarta, ja que OpenJDK 17 no és compatible amb Javax.

Passes a realitzar

Un cop actualitzades les versions dels mòduls, segons s’ indica a la secció anterior, serà necessari realitzar els següents passos:

1. Reemplaça les dependències de Javax per Jakarta en l’arxiu pom.xml.

Pom.xml

<dependency>
   <groupId>javax.annotation</groupId>
   <artifactId>javax.annotation-api</artifactId>
   <version>1.3.2</version>
</dependency>

per

<dependency>
   <groupId>jakarta.annotation</groupId>
   <artifactId>jakarta.annotation-api</artifactId>
   <version>1.3.5</version>
</dependency>

2. Reemplaçar l’ imports de javax per jakarta en totes les classes Java que utilitzin el import de javax.

import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
import javax.persistence.Query;

per

import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import jakarta.persistence.Query;

3. És necessari modificar els JUnit per a utilitzar JUnit 5 (Jupiter).

Per a realitzar les modificacions correctament, hem de tenir en compte els següents punts:

• 1.: Comptar amb les dependències de JUnit 4 canviades a JUnit 5 (Jupiter).

   <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <version>5.10.1</version>
      <scope>test</scope>
   </dependency>
   <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-engine</artifactId>
      <version>5.10.1</version>
      <scope>test</scope>
   </dependency>
   <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-params</artifactId>
      <version>5.10.1</version>
      <scope>test</scope>
   </dependency>

• 2.: Actualitzar les següents anotacions en el nostre codi perquè siguin compatibles amb JUnit 5.

  • @org.junit.Test per @org.junit.jupiter.api.Test (import org.junit.jupiter.api.Test;).

  • @Before ara és @BeforeEach (import org.junit.jupiter.api.BeforeEach;).

  • @After ara és @AfterEach (import org.junit.jupiter.api.AfterEach;).

  • @BeforeClass ara és @BeforeAll (import org.junit.jupiter.api.BeforeAll;).

  • @AfterClass ara és @AfterAll (import org.junit.jupiter.api.AfterAll;).

  • @Ignore ara és @Disabled (import org.junit.jupiter.api.Disabled;).

  • @RunWith ara és @ExtendWith (import org.junit.jupiter.api.extension.ExtendWith;)

  • @Category ara és @Tag (import org.junit.jupiter.api.Tag;)

  • @Test (expected = Exception.class) ara és Assertions.assertThrows

    • Exemple

    @Test(expected = IndexOutOfBoundsException.class)
    public void testIndexOutOfBoundsException() {
       ArrayList emptyList = new ArrayList();
       Object o = emptyList.get(0);
    }
    

    per

    @Test
    public void testIndexOutOfBoundsException() {
       ArrayList emptyList = new ArrayList();
       Assertions.assertThrows(IndexOutOfBoundsException.class, () -> {
          Object o = emptyList.get(0);
       });
    }
    

4. És recomanable utilitzar l’última versió de l’schema del XSD de Spring Security. Per exemple de: http://www.springframework.org/schema/security/spring-security-5.4.xsd a: http://www.springframework.org/schema/security/spring-security.xsd

5. S’ha modificat la URL d’accés a swagger passant de: http://localhost:8080/swagger-ui/index.html a: http://localhost:8080/api/swagger-ui/index.html

Informació sobre mòduls migrats

S’indica el llistat de mòduls que han estat migrats de la versió 3.6 a la 3.8. Per cada mòdul cal modificar els intervals de les versions. A més, per a alguns mòduls cal realitzar altres modificacions per a poder usar-los de manera correcta.

• canigo.root
• canigo.core
• canigo.persistence.core
• canigo.persistence.jpa
• canigo.persistence.mongodb
• canigo.security
• canigo.web.core
• canigo.web.rs
• canigo.support.mailing
• canigo.operation.logging
• canigo.test
• canigo.support.sftp

canigo.root

No aplica realitzar accions relacionades amb la migració de 3.6 a 3.8.

canigo.core

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

canigo.persistence.core

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

canigo.persistence.jpa

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• A més, pel fet que s’ha eliminat javax , a causa de la incompatibilitat amb JDK 17, s’ha de reemplaçar totes les dependències associades a aquesta libreria,javax, per les corresponents de jakarta. Per tant, haurem d’afegir la dependència jakarta.annotation-api versió 1.3.5 que substitueix la dependència de javax.annotation-api versió 1.3.2.

• S’ha d’afegir la dependènciamockito-core a la versió 5.7.0.

• Finalment s’ha d’actualitzarjackson-databind de la 2.13.2.2 a la versió 2.15.3.

• La configuració ja no s’ha de realitzar en el fitxer <PROJECT_ROOT>/src/main/resources/config/props/jpa.properties, ja que les diferents propietats que es vulguin usar, s’han de definir en el fitxer application.yml. Un exemple de configuració d’aquest fitxer seria el següent:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/*databaseName*
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: *username*
    password: *password*
  jpa:
    show-sql: true
    generate-ddl: true
    hibernate:
      ddl-auto: update
      generate_statistics: false
      use_scrollable_resultset: true
    connection:
      release_mode: auto
      autocommit: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect

• Configuració si l’aplicació va per jdbc. La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer <PROJECT_ROOT>/src/main/resources/config/props/jdbc.properties. Un exemple del contingut del fitxer application.yml podria ser el següent:

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/*databaseName*
    username: *username*
    password: *password*

• Configuració si l’aplicació va per jndi. La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer <PROJECT_ROOT>/src/main/resources/config/props/jndi.properties. Un exemple del contingut del fitxer application.yml podria ser el següent:

spring:
  datasource:
    jndi-name: java:jboss/datasources/nomjndi
    jndi-lookupOnStartup: false
    jndi-cache: java: false

canigo.persistence.mongodb

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• A més, pel fet que s’ha eliminat javax , a causa de la incompatibilitat amb JDK 17, s’ha de reemplaçar totes les dependències associades a aquesta libreria,javax, per les corresponents de jakarta. Per tant, haurem d’afegir la dependència jakarta.annotation-api versió 1.3.5 que substitueix la dependència de javax.annotation-api versió 1.3.2. També s’ha de canviar la dependència javax.annotation-api versió 1.3.2 per la dependència jakarta.annotation-api versiò 1.3.5.

• No reactiu. La configuració ja no s’ha de realitzar en el fitxer <PROJECT_ROOT>/src/main/resources/config/props/mongodb.properties, ja que les diferents propietats que es vulguin usar, s’han de definir en el fitxer application.yml. Un exemple de configuració d’aquest fitxer seria el següent:

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/*database*
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

Indiquem taula amb explicació de les propietats:

• Reactiu. La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer mongodb.properties. Un exemple del contingut del fitxer application.yml podria ser el següent:

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/*database*

Indiquem taula amb explicació de les propietats:

canigo.security

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer <PROJECT_ROOT>/src/main/resources/config/props/security.properties. Un exemple del contingut del fitxer application.yml podria ser el següent:

jwt:
  header:
    startToken: Bearer
  secret: canigo
  expiration: 3600

Indiquem taula amb explicació de les propietats:

• Configuració per base de dades. La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer <PROJECT_ROOT>/src/main/resources/config/props/security.properties.

Un exemple del contingut del fitxer application.yml podria ser el següent:

security:
  database:
    jndiName: nomJNDI
    url: urlJNDI
    username: USERNAME
    password: PASSWORD

Indiquem taula amb explicació de les propietats:

• Configuració per LDAP. La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer <PROJECT_ROOT>/src/main/resources/config/props/security.properties. Un exemple del contingut del fitxer application.yml podria ser el següent:

security:
  ldap:
    url: urlLDAP
    manager:
      dn: managerDN
      password: PASSWORD

Indiquem taula amb explicació de les propietats:

• Configuració de la font d’autenticació per GICAR. La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer <PROJECT_ROOT>/src/main/resources/config/props/security.properties.

Un exemple del contingut del fitxer application.yml podria ser el següent:

security:
  gicar:
    httpGicarHeaderUsernameKey: NIF

• Configuració de la font d’autenticació i autorització per GICAR. La configuració ha passat a realitzar-se amb fitxer yml en lloc d’amb el fitxer <PROJECT_ROOT>/src/main/resources/config/props/security.properties. Un exemple del contingut del fitxer application.yml podria ser el següent:

security:
  gicar:
    httpGicarHeaderUsernameKey: NIF

Indiquem taula amb explicació de les propietats:

canigo.web.core

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• A més, pel fet que s’ha eliminat javax , a causa de la incompatibilitat amb JDK 17, s’ha de reemplaçar totes les dependències associades a aquesta libreria,javax, per les corresponents de Jakarta. Per tant, haurem d’afegir la dependència jakarta servelet api versió 6.0.0 que substitueix la dependència de javax.servelet api.

canigo.web.rs

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• A més, pel fet que s’ha eliminat javax , a causa de la incompatibilitat amb JDK 17, s’ha de reemplaçar totes les dependències associades a aquesta libreria,javax, per les corresponents de jakarta. Per tant, haurem d’afegir la dependència jakarta.servlet-api versió 5.0.0 que substitueix la dependència de javax.servlet-api versió 4.0.1.

canigo.support.mailing

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• Així mateix , a causa de la incompatibilitat i obsolescència amb el JDK 17 , s’esborren les dependències associades a la llibreria JAVAX ,sent reemplaçades per les dependències de JAKARTA. Les dependències reemplaçades són:jakarta.activation versió 2.1.2 que substitueix la dependència de javax.activation versió 1.1.1 i la dependència jakarta.mail versió**2.0.1** que substitueixla dependència dejavax.mail versió 1.6.2
• S’actualitzacommons.io de la 2.11.0 a la versió 2.15.0.

La configuració ja no s’ha de realitzar en el fitxer <PROJECT_ROOT>/src/main/resources/config/props/mail.properties, ja que les diferents propietats que es vulguin usar, s’han de definir en el fitxer application.yml. Un exemple de configuració d’aquest fitxer seria el següent:

spring:
  mail:
    host: smtp.host.com
    port: 25
    protocol: smtp
    username: <username>
    password: <password>
    default-encoding: UTF-8
    debug: false
    timeout: 8500

Indiquem taula amb explicació de les propietats:

canigo.operation.logging

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• S’ha d’afegir la dependència Canigó-web-core de la versió 3.1.0.
• És necessari, canviar la versió 3.0.4 del propi mòdul canigó per la versió del mòdul canigó a 3.1.0. És a dir , canigó operation logging 3.0.4 a versió 3.1.0.
• A més, pel fet que s’ha eliminat javax , a causa de la incompatibilitat amb JDK 17, s’ha de reemplaçar totes les dependències associades a aquesta libreria,javax, per les corresponents de jakarta. Per tant, haurem d’afegir la dependència jakarta.websocket-api versió 2.1.1 que substitueix la dependència de javax.websocket-api versió 1.1 ,jakarta.servlet-api versió 6.0.0 que substitueix la dependència de javax.servlet-api versió 3.0.0.
• S’ha d’actualitzartomcat-embed-websocket de la 10.0.18 a la versió 10.1.16,jackson-core versió 2.13.2 a la versió 2.15.3 i mockito-core de la 4.3.1 a la versió 5.7.0
• Actualització de tots els mòduls de Canigó per a actualitzar org.springframework de 5.3.18 a 6.1.1, spring-core de 5.3.18 a 6.1.1,spring-websocket de 5.3.18 a 6.1.1, spring-context-support de 5.3.18 a 6.1.1, spring-webmvcde 5.3.18 a 6.1.1 i spring-messaging de 5.3.18 a 6.1.1.
• Finalment s’ha d’actualitzarjackson-databind de la 2.13.2.2 a la versió 2.15.3.

canigo.test

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

• A més, pel fet que s’ha eliminat javax , a causa de la incompatibilitat amb JDK 17, s’ha de reemplaçar totes les dependències associades a aquesta libreria,javax, per les corresponents de jakarta. Per tant, haurem d’afegir la dependència jakarta.servlet-api versió 6.0.0 que substitueix la dependència de javax.servlet-api versió 3.0.0.

• Una altra de les actualitzacions de dependències que s’ha de realitzar és afegir la dependència de mockito-core a la versió 5.7.0, spring-test 6.1.1 i testng a la versió 7.8.0 . Així mateix modificar la dependència de junit de la version 4.13.2 a junit-jupiter 5.10.1 i finalment jackson-databind de la 2.13.2.2 a la versió 2.15.3.

canigo.support.sftp

• Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:

La configuració ja no s’ha de realitzar en el fitxer <PROJECT_ROOT>/src/main/resources/config/props/sftp.properties, ja que les diferents propietats que es vulguin usar, s’han de definir en el fitxer application.yml. Un exemple de configuració d’aquest fitxer seria el següent:

sftp:
  url: URL_DEL_SERVIDOR_FTP
  port: 22
  username: USUARI_FTP
  password: PASSWORD_FTP

Indiquem taula amb explicació de les propietats: