Version:

Quarkus extension for Spring Transaction API

While users are encouraged to use Jakarta @Transactional annotations directly, Quarkus provides a compatibility layer for Spring @Transactional in the form of the spring-tx extension.

This guide explains how a Quarkus application can leverage the Spring @Transactional annotation to manage transactions.

Pré-requisitos

Para concluir este guia, você precisa:

Cerca de 15 minutos
Um IDE
JDK 17+ instalado com JAVA_HOME configurado corretamente
Apache Maven 3.9.16
Opcionalmente, o Quarkus CLI se você quiser usá-lo
Opcionalmente, Mandrel ou GraalVM instalado e configurado apropriadamente se você quiser criar um executável nativo (ou Docker se você usar uma compilação de contêiner nativo)
Alguma familiaridade com a extensão Spring DI

Criar o projeto Maven

Primeiro, precisamos de um novo projeto. Crie um novo projeto com o seguinte comando:

CLI

quarkus create app org.acme:spring-tx-quickstart \
    --extension='spring-web,spring-di,spring-tx,spring-data-jpa,jdbc-postgresql' \
    --no-code
cd spring-tx-quickstart

Para criar um projeto Gradle, adicione a opção --gradle ou --gradle-kotlin-dsl.

Para obter mais informações sobre como instalar e usar a CLI do Quarkus, consulte o guia Quarkus CLI.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.39.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=spring-tx-quickstart \
    -Dextensions='spring-web,spring-di,spring-tx,spring-data-jpa,jdbc-postgresql' \
    -DnoCode
cd spring-tx-quickstart

Para criar um projeto Gradle, adicione a opção '-DbuildTool=gradle' ou '-DbuildTool=gradle-kotlin-dsl'.

Para usuários do Windows:

Se estiver usando cmd, (não use barra invertida '\' e coloque tudo na mesma linha)
Se estiver usando o Powershell, envolva os parâmetros '-D' entre aspas duplas, por exemplo, '"-DprojectArtifactId=spring-tx-quickstart"'

This command generates a project which imports the spring-tx, spring-di, spring-web, and spring-data-jpa extensions.

If you already have your Quarkus project configured, you can add the spring-tx extension to your project by running the following command in your project base directory:

CLI

quarkus extension add spring-tx

Maven

./mvnw quarkus:add-extension -Dextensions='spring-tx'

Gradle

./gradlew addExtension --extensions='spring-tx'

Isto irá adicionar o seguinte trecho no seu arquivo de build:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-spring-tx</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-spring-tx")

Define the entity

Ao longo deste guia, a seguinte Entidade JPA será utilizada:

package org.acme.spring.tx;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;

@Entity
public class Fruit {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    public Fruit() {
    }

    public Fruit(String name) {
        this.name = name;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

Definir o repositório

In a typical Spring Data fashion, create a repository for Fruit:

package org.acme.spring.tx;

import java.util.List;

import org.springframework.data.repository.CrudRepository;

public interface FruitRepository extends CrudRepository<Fruit, Long> {

    List<Fruit> findByName(String name);
}

Creating a transactional service

Now let’s create a service that uses Spring’s @Transactional annotation to manage transactions. Create src/main/java/org/acme/spring/tx/FruitService.java with the following content:

package org.acme.spring.tx;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class FruitService {

    @Autowired
    FruitRepository fruitRepository;

    @Transactional (1)
    public Fruit addFruit(String name) {
        return fruitRepository.save(new Fruit(name));
    }

    @Transactional(propagation = org.springframework.transaction.annotation.Propagation.REQUIRED) (2)
    public void addMultipleFruits(List<String> names) {
        for (String name : names) {
            fruitRepository.save(new Fruit(name));
        }
    }
}

1	The Spring `@Transactional` annotation is automatically transformed into a Jakarta `@Transactional` annotation at build time.
2	You can specify propagation attributes just like in Spring. `REQUIRED` is the default.

You can also place @Transactional at the class level to make all public methods transactional:

package org.acme.spring.tx;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@Transactional (1)
public class TransactionalService {

    public void doSomething() {
        // this method is transactional
    }

    public void doSomethingElse() {
        // this method is also transactional
    }
}

1	All public methods of this class are transactional.

Controlling rollback behavior

Spring’s rollbackFor and noRollbackFor attributes are supported:

package org.acme.spring.tx;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class RollbackService {

    @Transactional(rollbackFor = BusinessException.class) (1)
    public void performBusinessOperation() throws BusinessException {
        // if BusinessException is thrown, the transaction rolls back
    }

    @Transactional(noRollbackFor = NonCriticalException.class) (2)
    public void performTolerantOperation() throws NonCriticalException {
        // if NonCriticalException is thrown, the transaction still commits
    }
}

1	The transaction will roll back if `BusinessException` (or a subclass) is thrown.
2	The transaction will NOT roll back if `NonCriticalException` is thrown.

Update the Jakarta REST resource

With the repository and service in place, create the Jakarta REST resource that will use the FruitService. Create src/main/java/org/acme/spring/tx/FruitResource.java with the following content:

package org.acme.spring.tx;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class FruitResource {

    @Autowired
    FruitService fruitService;

    @Autowired
    FruitRepository fruitRepository;

    @GetMapping("/fruits")
    public List<Fruit> list() {
        return (List<Fruit>) fruitRepository.findAll();
    }

    @PostMapping("/fruits")
    public Fruit add(@RequestBody Fruit fruit) {
        return fruitService.addFruit(fruit.getName());
    }
}

Empacote e execute a aplicação

Quarkus Dev Services will automatically start a PostgreSQL container in dev and test modes, so no manual database configuration is needed.

Execute a aplicação com:

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

In another terminal, add a fruit:

curl -X POST -H "Content-Type: application/json" -d '{"name": "Apple"}' http://localhost:8080/fruits

Then list all fruits:

curl http://localhost:8080/fruits

Como de costume, a aplicação pode ser empacotada utilizando:

CLI

quarkus build

Maven

./mvnw install

Gradle

./gradlew build

E executada com java -jar target/quarkus-app/quarkus-run.jar.

Também é possível gerar o executável nativo com:

CLI

quarkus build --native

Maven

./mvnw install -Dnative

Gradle

./gradlew build -Dquarkus.native.enabled=true

Supported Spring @Transactional features

The table below summarizes the supported attributes:

Table 1. Supported Spring @Transactional attributes
Atributo	Status	Comments
`propagation`	Supported	All values except `NESTED`: `REQUIRED` (default), `REQUIRES_NEW`, `SUPPORTS`, `MANDATORY`, `NOT_SUPPORTED`, `NEVER`. `NESTED` causes a build-time error.
`rollbackFor`	Supported
`rollbackForClassName`	Supported
`noRollbackFor`	Supported
`noRollbackForClassName`	Supported
`readOnly`	Unsupported	Ignored with a warning
`timeout` / `timeoutString`	Unsupported	Ignored with a warning
`isolation`	Unsupported	Only `DEFAULT` is accepted; other values are ignored with a warning
`value` / `transactionManager`	Unsupported	Quarkus manages the transaction manager
`label`	Unsupported	Ignored with a warning

Nota técnica importante

Observe que o suporte ao Spring no Quarkus não inicia um Application Context do Spring, nem executa nenhuma classe de infraestrutura do Spring. As classes e anotações do Spring são usadas apenas para leitura de metadados e/ou como tipos de retorno de métodos ou tipos de parâmetros no código do usuário. Isso significa que, para os usuários finais, adicionar bibliotecas arbitrárias do Spring não terá nenhum efeito. Além disso, classes de infraestrutura do Spring (como org.springframework.beans.factory.config.BeanPostProcessor , por exemplo) não serão executadas.

Mais guias de Spring

O Quarkus possui mais funcionalidades compatíveis com o Spring. Para mais informações, consulte os seguintes guias: