Quarkus - Extension for Spring Data API

While users are encouraged to use Hibernate ORM with Panache for Relational Database access, Quarkus provides a compatibility layer forSpring Data JPA repositories in the form of the spring-data-jpa extension.

Prerequisites

To complete this guide, you need:

  • less than 15 minutes

  • an IDE

  • JDK 1.8+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.5.3+

Solution

We recommend that you follow the instructions in the next sections and create the application step by step.However, you can go right to the completed example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the spring-data-jpa-quickstart directory.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

  1. mvn io.quarkus:quarkus-maven-plugin:1.0.0.CR1:create \
  2.     -DprojectGroupId=org.acme \
  3.     -DprojectArtifactId=spring-data-jpa-quickstart \
  4.     -DclassName="org.acme.spring.data.jpa.FruitResource" \
  5.     -Dpath="/greeting" \
  6.     -Dextensions="spring-data-jpa,resteasy-jsonb,quarkus-jdbc-postgresql"
  7. cd spring-data-jpa-quickstart

This command generates a Maven project with a REST endpoint and imports the spring-data-jpa extension.

Define the Entity

Throughout the course of this guide, the following JPA Entity will be used:

  1. package org.acme.spring.data.jpa;
  3. import javax.persistence.Entity;
  4. import javax.persistence.GeneratedValue;
  5. import javax.persistence.Id;
  7. @Entity
  8. public class Fruit {
  10.     @Id
  11.     @GeneratedValue
  12.     private Long id;
  14.     private String name;
  16.     private String color;
  19.     public Fruit() {
  20.     }
  22.     public Fruit(String name, String color) {
  23.         this.name = name;
  24.         this.color = color;
  25.     }
  27.     public Long getId() {
  28.         return id;
  29.     }
  31.     public void setId(Long id) {
  32.         this.id = id;
  33.     }
  35.     public String getName() {
  36.         return name;
  37.     }
  39.     public void setName(String name) {
  40.         this.name = name;
  41.     }
  43.     public String getColor() {
  44.         return color;
  45.     }
  47.     public void setColor(String color) {
  48.         this.color = color;
  49.     }
  50. }

Configure database access properties

Add the following properties to application.properties to configure access to a local PostgreSQL instance.

  1. quarkus.datasource.url=jdbc:postgresql:quarkus_test
  2. quarkus.datasource.driver=org.postgresql.Driver
  3. quarkus.datasource.username=quarkus_test
  4. quarkus.datasource.password=quarkus_test
  5. quarkus.datasource.max-size=8
  6. quarkus.datasource.min-size=2
  7. quarkus.hibernate-orm.database.generation=drop-and-create

This configuration assumes that PostgreSQL will be running locally.

A very easy way to accomplish that is by using the following Docker command:

  1. docker run --ulimit memlock=-1:-1 -it --rm=true --memory-swappiness=0 --name quarkus_test -e POSTGRES_USER=quarkus_test -e POSTGRES_PASSWORD=quarkus_test -e POSTGRES_DB=quarkus_test -p 5432:5432 postgres:11.5

If you plan on using a different setup, please change your application.properties accordingly.

Prepare the data

To make it easier to showcase some capabilities of Spring Data JPA on Quarkus, some test data should be inserted into the databaseby adding the following content to a new file named src/main/resources/import.sql:

  1. INSERT INTO fruit(id, name, color) VALUES (1, 'Cherry', 'Red');
  2. INSERT INTO fruit(id, name, color) VALUES (2, 'Apple', 'Red');
  3. INSERT INTO fruit(id, name, color) VALUES (3, 'Banana', 'Yellow');
  4. INSERT INTO fruit(id, name, color) VALUES (4, 'Avocado', 'Green');

Hibernate ORM will execute these queries on application startup.

Define the repository

It is now time to define the repository that will be used to access Fruit.In a typical Spring Data fashion create a repository like so:

  1. package org.acme.spring.data.jpa;
  3. import org.springframework.data.repository.CrudRepository;
  5. import java.util.List;
  7. public interface FruitRepository extends CrudRepository<Fruit, Long> {
  9.     List<Fruit> findByColor(String color);
  10. }

The FruitRepository above extends Spring Data’s org.springframework.data.repository.CrudRepository which means that all of the latter’s methods areavailable to FruitRepository.Additionally findByColor is defined whose purpose is to return all Fruit entities that match the specified color.

Update the JAX-RS resource

With the repository in place, the next order of business is to update the JAX-RS resource that will use the FruitRepository. Open FruitResource and change its contents to:

  1. package org.acme.spring.data.jpa;
  3. import javax.ws.rs.DELETE;
  4. import javax.ws.rs.GET;
  5. import javax.ws.rs.POST;
  6. import javax.ws.rs.PUT;
  7. import javax.ws.rs.Path;
  8. import javax.ws.rs.Produces;
  10. import org.jboss.resteasy.annotations.jaxrs.PathParam;
  12. import java.util.List;
  13. import java.util.Optional;
  15. @Path("/fruits")
  16. public class FruitResource {
  18.     private final FruitRepository fruitRepository;
  20.     public FruitResource(FruitRepository fruitRepository) {
  21.         this.fruitRepository = fruitRepository;
  22.     }
  24.     @GET
  25.     @Produces("application/json")
  26.     public Iterable<Fruit> findAll() {
  27.         return fruitRepository.findAll();
  28.     }
  31.     @DELETE
  32.     @Path("{id}")
  33.     public void delete(@PathParam long id) {
  34.         fruitRepository.deleteById(id);
  35.     }
  37.     @POST
  38.     @Path("/name/{name}/color/{color}")
  39.     @Produces("application/json")
  40.     public Fruit create(@PathParam String name, @PathParam String color) {
  41.         return fruitRepository.save(new Fruit(name, color));
  42.     }
  44.     @PUT
  45.     @Path("/id/{id}/color/{color}")
  46.     @Produces("application/json")
  47.     public Fruit changeColor(@PathParam Long id, @PathParam String color) {
  48.         Optional<Fruit> optional = fruitRepository.findById(id);
  49.         if (optional.isPresent()) {
  50.             Fruit fruit = optional.get();
  51.             fruit.setColor(color);
  52.             return fruitRepository.save(fruit);
  53.         }
  55.         throw new IllegalArgumentException("No Fruit with id " + id + " exists");
  56.     }
  58.     @GET
  59.     @Path("/color/{color}")
  60.     @Produces("application/json")
  61.     public List<Fruit> findByColor(@PathParam String color) {
  62.         return fruitRepository.findByColor(color);
  63.     }
  64. }

FruitResource now provides a few REST endpoints that can be used to perform CRUD operation on Fruit.

Note on Spring Web

The JAX-RS resource can also be substituted with a Spring Web controller as Quarkus supports REST endpoint definition using Spring controllers.See the Spring Web guide for more details.

Update the test

To test the capabilities of FruitRepository proceed to update the content of FruitResourceTest to:

  1. package org.acme.spring.data.jpa;
  3. import io.quarkus.test.junit.QuarkusTest;
  4. import org.junit.jupiter.api.Test;
  6. import static io.restassured.RestAssured.given;
  7. import static org.hamcrest.CoreMatchers.containsString;
  8. import static org.hamcrest.CoreMatchers.is;
  9. import static org.hamcrest.CoreMatchers.notNullValue;
  10. import static org.hamcrest.core.IsNot.not;
  12. @QuarkusTest
  13. class FruitResourceTest {
  15.     @Test
  16.     void testListAllFruits() {
  17.         //List all, should have all 3 fruits the database has initially:
  18.         given()
  19.                 .when().get("/fruits")
  20.                 .then()
  21.                 .statusCode(200)
  22.                 .body(
  23.                         containsString("Cherry"),
  24.                         containsString("Apple"),
  25.                         containsString("Banana")
  26.                 );
  28.         //Delete the Cherry:
  29.         given()
  30.                 .when().delete("/fruits/1")
  31.                 .then()
  32.                 .statusCode(204)
  33.         ;
  35.         //List all, cherry should be missing now:
  36.         given()
  37.                 .when().get("/fruits")
  38.                 .then()
  39.                 .statusCode(200)
  40.                 .body(
  41.                         not(containsString("Cherry")),
  42.                         containsString("Apple"),
  43.                         containsString("Banana")
  44.                 );
  46.         //Create a new Fruit
  47.         String idOfNewFruit = given()
  48.                 .when().post("/fruits/name/Orange/color/Orange")
  49.                 .then()
  50.                 .statusCode(200)
  51.                 .body(containsString("Orange"))
  52.                 .body("id", notNullValue())
  53.                 .extract().body().jsonPath().getString("id");
  55.         //List all, Orange should be present now:
  56.         given()
  57.                 .when().get("/fruits")
  58.                 .then()
  59.                 .statusCode(200)
  60.                 .body(
  61.                         not(containsString("Cherry")),
  62.                         containsString("Apple"),
  63.                         containsString("Orange")
  64.                 );
  65.     }
  67.     @Test
  68.     void testFindByColor() {
  69.         //Find by color that no fruit has
  70.         given()
  71.                 .when().get("/fruits/color/Black")
  72.                 .then()
  73.                 .statusCode(200)
  74.                 .body("size()", is(0));
  76.         //Find by color that multiple fruits have
  77.         given()
  78.                 .when().get("/fruits/color/Red")
  79.                 .then()
  80.                 .statusCode(200)
  81.                 .body(
  82.                         containsString("Apple"),
  83.                         containsString("Strawberry")
  84.                 );
  86.         //Find by color that matches
  87.         given()
  88.                 .when().get("/fruits/color/Green")
  89.                 .then()
  90.                 .statusCode(200)
  91.                 .body("size()", is(1))
  92.                 .body(containsString("Avocado"));
  94.         //Update color of Avocado
  95.         given()
  96.                 .when().put("/fruits/id/4/color/Black")
  97.                 .then()
  98.                 .statusCode(200)
  99.                 .body(containsString("Black"));
  101.         //Find by color that Avocado now has
  102.         given()
  103.                 .when().get("/fruits/color/Black")
  104.                 .then()
  105.                 .statusCode(200)
  106.                 .body("size()", is(1))
  107.                 .body(
  108.                         containsString("Black"),
  109.                         containsString("Avocado")
  110.                 );
  111.     }
  113. }

The test can be easily run by issuing: ./mvnw test

Package and run the application

Quarkus dev mode works with the defined repositories just like with any other Quarkus extension, greatly enhancing your productivity during the dev cycle.The application can be started in dev mode as usual using:

  1. ./mvnw compile quarkus:dev

Run the application as a native binary

You can of course create a native executable following the instructions of the this guide.

Supported Spring Data JPA functionalities

Quarkus currently supports a subset of Spring Data JPA’s features, namely the most useful and most commonly used features.

An important part of this support is that all repository generation is done at build time thus ensuring that all supported features work correctly in native mode.Moreover, developers know at build time whether or not their repository method names can be converted to proper JPQL queries.This also means that if a method name indicates that a field should be used that is not part of the Entity, developers will getthe relevant error at build time.

What is supported

The following sections described the most important supported features of Spring Data JPA.

Automatic repository implementation generation

Interfaces that extend any of the following Spring Data repositories are automatically implemented:

  • org.springframework.data.repository.Repository

  • org.springframework.data.repository.CrudRepository

  • org.springframework.data.repository.PagingAndSortingRepository

  • org.springframework.data.jpa.repository.JpaRepository

The generated repositories are also registered as beans so they can be injected into any other bean.Furthermore the methods that update the database are automatically annotated with @Transactional.

Fine tuning of repository definition

This allows user defined repository interfaces to cherry-pick methods from any of the supported Spring Data repository interfaces without having to extend those interfaces.This is particularly useful when for example a repository needs to use some methods from CrudRepository but it’s undesirable to expose the full list of methods of said interface.

Assume for example that a PersonRepository that shouldn’t extend CrudRepository but would like to use save and findById methods which are defined in said interface.In such a case, PersonRepository would look like so:

  1. package org.acme.spring.data.jpa;
  3. import org.springframework.data.repository.Repository;
  5. public class PersonRepository extends Repository<Person, Long> {
  7.     Person save(Person entity);
  9.     Optional<Person> findById(Person entity);
  10. }

Customizing individual repositories using repository fragments

Repositories can be enriched with additional functionality or override the default implementation of methods of the supported Spring Data repositories.This is best shown with an example.

A repository fragment is defined as so:

  1. public interface PersonFragment {
  3.     // custom findAll
  4.     List<Person> findAll();
  6.     void makeNameUpperCase(Person person);
  7. }

The implementation of that fragment looks like this:

  1. import java.util.List;
  3. import io.quarkus.hibernate.orm.panache.runtime.JpaOperations;
  5. public class PersonFragmentImpl implements PersonFragment {
  7.     @Override
  8.     public List<Person> findAll() {
  9.         // do something here
  10.         return (List<Person>) JpaOperations.findAll(Person.class).list();
  11.     }
  13.     @Override
  14.     public void makeNameUpperCase(Person person) {
  15.         person.setName(person.getName().toUpperCase());
  16.     }
  17. }

Then the actual PersonRepository interface to be used would look like:

  1. public interface PersonRepository extends JpaRepository<Person, Long>, PersonFragment {
  3. }

Derived query methods

Methods of repository interfaces that follow the Spring Data conventions can be automatically implemented (unless they fall into one of the unsupported cases listed later on).This means that methods like the following will all work:

  1. public interface PersonRepository extends CrudRepository<Person, Long> {
  3.     List<Person> findByName(String name);
  5.     Person findByNameBySsn(String ssn);
  7.     Optional<Person> findByNameBySsnIgnoreCase(String ssn);
  9.     boolean existsBookByYearOfBirthBetween(Integer start, Integer end);
  11.     List<Person> findByName(String name, Sort sort);
  13.     Page<Person> findByNameOrderByJoined(String name, Pageable pageable);
  15.     List<Person> findByNameOrderByAge(String name);
  17.     List<Person> findByNameOrderByAgeDesc(String name, Pageable pageable);
  19.     List<Person> findByAgeBetweenAndNameIsNotNull(int lowerAgeBound, int upperAgeBound);
  21.     List<Person> findByAgeGreaterThanEqualOrderByAgeAsc(int age);
  23.     List<Person> queryByJoinedIsAfter(Date date);
  25.     Collection<Person> readByActiveTrueOrderByAgeDesc();
  27.     Long countByActiveNot(boolean active);
  29.     List<Person> findTop3ByActive(boolean active, Sort sort);
  31.     Stream<Person> findPersonByNameAndSurnameAllIgnoreCase(String name, String surname);
  32. }

User defined queries

User supplied queries contained in the @Query annotation. For example things like the following all work:

  1. public interface MovieRepository extends CrudRepository<Movie, Long> {
  3.     Movie findFirstByOrderByDurationDesc();
  5.     @Query("select m from Movie m where m.rating = ?1")
  6.     Iterator<Movie> findByRating(String rating);
  8.     @Query("from Movie where title = ?1")
  9.     Movie findByTitle(String title);
  11.     @Query("select m from Movie m where m.duration > :duration and m.rating = :rating")
  12.     List<Movie> withRatingAndDurationLargerThan(@Param("duration") int duration, @Param("rating") String rating);
  14.     @Query("from Movie where title like concat('%', ?1, '%')")
  15.     List<Object[]> someFieldsWithTitleLike(String title, Sort sort);
  17.     @Modifying
  18.     @Query("delete from Movie where rating = :rating")
  19.     void deleteByRating(@Param("rating") String rating);
  21.     @Modifying
  22.     @Query("delete from Movie where title like concat('%', ?1, '%')")
  23.     Long deleteByTitleLike(String title);
  25.     @Modifying
  26.     @Query("update Movie m set m.rating = :newName where m.rating = :oldName")
  27.     int changeRatingToNewName(@Param("newName") String newName, @Param("oldName") String oldName);
  29.     @Modifying
  30.     @Query("update Movie set rating = null where title =?1")
  31.     void setRatingToNullForTitle(String title);
  33.     @Query("from Movie order by length(title)")
  34.     Slice<Movie> orderByTitleLength(Pageable pageable);
  35. }

All methods that are annotated with @Modifying will automatically be annotated with @Transactional.

More examples

An extensive list of examples can be seen in the integration tests directory which is located inside the Quarkus source code.

What is currently unsupported

  • Methods of the org.springframework.data.repository.query.QueryByExampleExecutor interface - if any of these are invoked, a Runtime exception will be thrown.

  • QueryDSL support. No attempt will be made to generate implementations of any of the QueryDSL related repositories.

  • Customizing the base repository for all repository interfaces in the code base.

In Spring Data JPA this is done by registering a class that extends org.springframework.data.jpa.repository.support.SimpleJpaRepository however in Quarkus this classis not used at all (since all the necessary plumbing is done at build time). Similar support might be added to Quarkus in the future.

  • Using java.util.concurrent.Future and classes that extend it as return types of repository methods.

  • Native and named queries when using @Query

The Quarkus team is exploring various alternatives to bridging the gap between the JPA and Reactive worlds.

Important Technical Note

Please note that the Spring support in Quarkus does not start a Spring Application Context nor are any Spring infrastructure classes run.Spring classes and annotations are only used for reading metadata and / or are used as user code method return types or parameter types.

More Spring guides

Quarkus support has more Spring compatibility features. See the following guides for more details: