Create Spring Data Repository

The Spring Data repository abstraction simplifies dealing with data models by reducing the amount of boilerplate code required to implement data access layers for various persistence stores (such as JPA). @Repository and its sub-interfaces like @CrudRepository are the central concept in Spring Data which is a marker interface to provide data manipulation functionality for the entity class that is being managed. When the application starts, Quarkus configures the required persistence technologies and provides an implementation for the interfaces used.

First, we need a data model.

Create Model

Click here to create and open a new file for our Remodelpository: fruit-taster/src/main/java/org/acme/quickstart/Fruit.java.

Click Copy to Editor to add the code:

package org.acme.quickstart;

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

@Entity
public class Fruit {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    private String color;


    public Fruit() {
    }

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

    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;
    }

    public String getColor() {
        return color;
    }

    public void setColor(String color) {
        this.color = color;
    }
}

This is a simple POJO representing a Fruit, with a name and color.

Create Spring Data Repository

Next, click here to create and open a new file for our Repository: fruit-taster/src/main/java/org/acme/quickstart/FruitRepository.java.

Click Copy to Editor to create the code for the repository:

package org.acme.quickstart;

import org.springframework.data.repository.CrudRepository;

import java.util.List;

public interface FruitRepository extends CrudRepository<Fruit, Long> {

    List<Fruit> findByColor(String color);

}

Note that by extending Spring's CrudRepository interface you'll automatically get a complete set of methods to manipulate the entity (e.g. count(), findAll(), delete() and others).

Create sample data

Finally, we need some sample data to work with. Click here to create and open a new file to hold our sample data: fruit-taster/src/main/resources/import.sql.

Click Copy to Editor to create add the sample data which will be used to populate our database when the app runs:

INSERT INTO fruit(id, name, color) VALUES (nextval('hibernate_sequence'), 'cherry', 'red');
INSERT INTO fruit(id, name, color) VALUES (nextval('hibernate_sequence'), 'orange', 'orange');
INSERT INTO fruit(id, name, color) VALUES (nextval('hibernate_sequence'), 'banana', 'yellow');
INSERT INTO fruit(id, name, color) VALUES (nextval('hibernate_sequence'), 'avocado', 'green');
INSERT INTO fruit(id, name, color) VALUES (nextval('hibernate_sequence'), 'strawberry', 'red');

Configure Quarkus

We need to configure our app to define database connection settings. Click: fruit-taster/src/main/resources/application.properties to open this file. This file contains Quarkus configuration.

Click Copy to Editor to add the following values to the application.properties file:

quarkus.datasource.url=jdbc:h2:mem:rest-crud
quarkus.datasource.driver=org.h2.Driver
quarkus.datasource.max-size=8
quarkus.datasource.min-size=2
quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.hibernate-orm.log.sql=true

That’s it! Now you have a database, domain model (Fruit) and a repository (FruitRepository) to retrieve the domain model, and some sample data.

NOTE Although we are using import.sql to initialize our database in our app, you shouldn't use this in production. Instead, review suggested uses of Hibernate ORM in production.

Next, we'll create some injectable Spring Beans that will give us access to the data using the Spring DI annotations.

Spring DI in Quarkus

While you are encouraged to use CDI annotations for injection, Quarkus provides a compatibility layer for Spring dependency injection in the form of the spring-di extension.

This step explains how your Quarkus application can leverage the well known Dependency Injection annotations included in the Spring Framework.

Let’s proceed to create some beans using various Spring annotations.

Create Functional Interface

First we will create a StringFunction interface that some our beans will implement and which will be injected into another bean later on. This Functional Interface provide target types for lambda expressions and method references we'll define.

Functional Interfaces are part of the base Java platform, and are not Spring-specific.

Click here to create and open a new file for our interface: fruit-taster/src/main/java/org/acme/quickstart/StringFunction.java.

Click Copy to Editor to create the code for the interface:

package org.acme.quickstart;

import java.util.function.Function;

public interface StringFunction extends Function<String, String> {

}

With the interface in place, we will add an AppConfiguration class which will use the Spring’s Java Config style for defining a bean. It will be used to create a StringFunction bean that will capitalize the text passed as parameter.

Click here to create and open a new file for our configuration: fruit-taster/src/main/java/org/acme/quickstart/AppConfiguration.java.

Click Copy to Editor to create the code for the interface:

package org.acme.quickstart;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AppConfiguration {

    @Bean(name = "capitalizeFunction")
    public StringFunction capitalizer() {
        return String::toUpperCase;
    }
}

Create Functions

Now we define another bean that will implement StringFunction using Spring’s stereotype annotation style. This bean will effectively be a no-op bean that simply returns the input as is.

Click here to create and open a new file for our bean: fruit-taster/src/main/java/org/acme/quickstart/NoOpSingleStringFunction.java.

Click Copy to Editor to create the code for the interface:

package org.acme.quickstart;

import org.springframework.stereotype.Component;

@Component("noopFunction")
public class NoOpSingleStringFunction implements StringFunction {

    @Override
    public String apply(String s) {
        return s;
    }
}

Add injectable configuration

Quarkus also provides support for injecting configuration values using Spring’s @Value annotation. To see that in action, click Copy to Editor to add a new configuration parameter to our application which we'll use to add a little flavor to our app:

taste.message = tastes great

We'll also need a new Spring Bean to use this configuration! Click here to create and open a new file for our configuration: fruit-taster/src/main/java/org/acme/quickstart/MessageProducer.java.

Click Copy to Editor to create the code for the interface:

package org.acme.quickstart;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;

@Service
public class MessageProducer {

    @Value("${taste.message}")
    String message;

    public String getTaste() {
        return message;
    }
}

Tie them all together

The final bean we will create ties together all the previous beans.

Click here to create and open a new file for our configuration: fruit-taster/src/main/java/org/acme/quickstart/TasterBean.java.

Click Copy to Editor to create the code for the bean:

package org.acme.quickstart;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class TasterBean {

    private final MessageProducer messageProducer;

    @Autowired
    @Qualifier("noopFunction")
    StringFunction noopStringFunction;

    @Autowired
    @Qualifier("capitalizeFunction")
    StringFunction capitalizerStringFunction;

    @Value("${taste.suffix:!}")
    String suffix;

    public TasterBean(MessageProducer messageProducer) {
        this.messageProducer = messageProducer;
    }

    public String taste(String fruitName) {
        final String initialValue = fruitName + ": " + messageProducer.getTaste() + " " + suffix;
        return noopStringFunction.andThen(capitalizerStringFunction).apply(initialValue);
    }
}

In the code above, we see that both field injection and constructor injection are being used (note that constructor injection does not need the @Autowired annotation since there is a single constructor). Furthermore, the @Value annotation on suffix has also a default value defined, which in this case will be used since we have not defined taste.suffix in application.properties.

This new TasterBean has a method taste() which will report how each fruit tastes. It also uses our functions noopStringFunction and capitalizerStringFunction that we've injected via @Autowired to both do nothing and also transform the result INTO ALL CAPS.

With our data model, repository, and accessor beans in place, let's move to the final step where we'll expose our fruits to the outside world via Spring Web annotations.

Using Spring Web Annotations in Quarkus

While you are encouraged to use JAX-RS annotation for defining REST endpoints, Quarkus provides a compatibility layer for Spring Web in the form of the spring-web extension.

This step shows how your Quarkus application can leverage the well known Spring Web annotations to define RESTful services.

Create Controllers

Click here to create and open a new file for our basic controller for accessing Fruits: fruit-taster/src/main/java/org/acme/quickstart/FruitController.java.

Click Copy to Editor to create the code for the controller:

package org.acme.quickstart;

import java.util.List;
import java.util.Optional;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;

@RestController
@RequestMapping("/fruits")
public class FruitController {

    private final FruitRepository fruitRepository;

    public FruitController(FruitRepository fruitRepository) {
        this.fruitRepository = fruitRepository;
    }

    @GetMapping(produces = "application/json")
    public Iterable<Fruit> findAll() {
        return fruitRepository.findAll();
    }


    @DeleteMapping("/{id}")
    public void delete(@PathVariable(name = "id") long id) {
        fruitRepository.deleteById(id);
    }

    @PostMapping(path = "/name/{name}/color/{color}", produces = "application/json")
    public Fruit create(@PathVariable(name = "name") String name, @PathVariable(name = "color") String color) {
        return fruitRepository.save(new Fruit(name, color));
    }

    @PutMapping(path = "/id/{id}/color/{color}", produces = "application/json")
    public Fruit changeColor(@PathVariable(name = "id") Long id, @PathVariable(name = "color") String color) {
        Optional<Fruit> optional = fruitRepository.findById(id);
        if (optional.isPresent()) {
            Fruit fruit = optional.get();
            fruit.setColor(color);
            return fruitRepository.save(fruit);
        }

        throw new IllegalArgumentException("No Fruit with id " + id + " exists");
    }

    @GetMapping(path = "/color/{color}", produces = "application/json")
    public List<Fruit> findByColor(@PathVariable(name = "color") String color) {
        return fruitRepository.findByColor(color);
    }
}

Notice the use of familiar Spring annotations like @GetMapping and @PathVariable. This exposes a set of RESTful APIs:

• GET /fruits - Retrieve all Fruits as a JSON array
• DELETE /fruits/{id} - Delete by ID
• POST /fruits/name/{name}/color/{color} - create a new Fruit with a name and color
• PUT /fruits/id/{id}/color/{color} - Update a fruit with a new color
• GET /fruits/color/{color} - Retrieve all fruits of the specified color

Test app

With this in place, we can now test our fruits access. The app is still running, so simply click the following commands to do a few operations:

Get all fruits:

curl -s http://localhost:8080/fruits | jq

Note you may need to click the command again, if it didn't execute in the new Terminal window. If you get a parse error:, it is likely you missed an earlier step, and the Quarkus live reload caught it. Click on the app's landing page to see details and clues about what may be wrong, and re-visit any prior steps to re-add the missing code.

Note that we pass the output to the jq utility which prints nicely-formatted JSON.

You should see:

[
  {
    "color": "red",
    "id": 1,
    "name": "cherry"
  },
  {
    "color": "orange",
    "id": 2,
    "name": "orange"
  },
  {
    "color": "yellow",
    "id": 3,
    "name": "banana"
  },
  {
    "color": "green",
    "id": 4,
    "name": "avocado"
  },
  {
    "color": "red",
    "id": 5,
    "name": "strawberry"
  }
]

Add a fruit:

curl -X POST -s http://localhost:8080/fruits/name/apple/color/red | jq

Get all red fruits:

curl -s http://localhost:8080/fruits/color/red | jq

Notice the presence of apple which we just added earlier.

Change the color of the apple to green:

curl -X PUT -s http://localhost:8080/fruits/id/6/color/green | jq

And retrieve all green fruits:

curl -s curl -s http://localhost:8080/fruits/color/green | jq

You should see:

[
  {
    "color": "green",
    "id": 4,
    "name": "avocado"
  },
  {
    "color": "green",
    "id": 6,
    "name": "apple"
  }
]

Indicating that the color of our apple has changed to green.

Exercise Beans using Spring DI Annotations

As a final test let's create another bean to use our injected beans and configuration using Spring DI annotations.

Click here to create and open a new file for our taster controller for tasting Fruits: fruit-taster/src/main/java/org/acme/quickstart/TasterController.java.

Click Copy to Editor to create the code for the controller:

package org.acme.quickstart;

import java.util.ArrayList;
import java.util.List;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import org.springframework.web.bind.annotation.PathVariable;

@RestController
@RequestMapping("/taster")
public class TasterController {

    private final FruitRepository fruitRepository;

    private final TasterBean tasterBean;

    public TasterController(FruitRepository fruitRepository, TasterBean tasterBean) {
        this.fruitRepository = fruitRepository;
        this.tasterBean = tasterBean;
    }

    @GetMapping(produces = "application/json")
    public List<TasteResult> tasteAll() {
        List<TasteResult> result = new ArrayList<>();

        fruitRepository.findAll().forEach(fruit -> {
            result.add(new TasteResult(fruit, tasterBean.taste(fruit.getName())));
        });
        return result;
    }

    @GetMapping(path = "/{color}", produces = "application/json")
    public List<TasteResult> tasteByColor(@PathVariable(name = "color") String color) {
        List<TasteResult> result = new ArrayList<>();
        fruitRepository.findByColor(color).forEach(fruit -> {
            result.add(new TasteResult(fruit, tasterBean.taste(fruit.getName())));
        });
        return result;
    }

    public class TasteResult {
        public Fruit fruit;
        public String result;

        public TasteResult(Fruit fruit, String result) {
            this.fruit = fruit;
            this.result = result;
        }

    }
}

Again, we're using Spring Rest annotations like @GetMapping but we're also injecting our repository and taster bean in the constructor. This controller exposes 2 RESTful APIs:

• GET /taster - taste all fruits and report result
• GET /taster/{color} - Taste only fruits of the specified color

App still running? Check. Let's test our new API:

Taste all the fruits:

curl -s http://localhost:8080/taster | jq

You should see:

[
  {
    "fruit": {
      "color": "red",
      "id": 1,
      "name": "cherry"
    },
    "result": "CHERRY: TASTES GREAT !"
  },
  {
    "fruit": {
      "color": "orange",
      "id": 2,
      "name": "orange"
    },
    "result": "ORANGE: TASTES GREAT !"
  },
  {
    "fruit": {
      "color": "yellow",
      "id": 3,
      "name": "banana"
    },
    "result": "BANANA: TASTES GREAT !"
  },
  {
    "fruit": {
      "color": "green",
      "id": 4,
      "name": "avocado"
    },
    "result": "AVOCADO: TASTES GREAT !"
  },
  {
    "fruit": {
      "color": "red",
      "id": 5,
      "name": "strawberry"
    },
    "result": "STRAWBERRY: TASTES GREAT !"
  }
]

Taste only the green fruits:

curl -s http://localhost:8080/taster/green | jq

[
  {
    "fruit": {
      "color": "green",
      "id": 4,
      "name": "avocado"
    },
    "result": "AVOCADO: TASTES GREAT !"
  }
]

Add a suffix

Click Copy to Editor to add a new suffix for our taster:

taste.suffix = (if you like fruit!)

And taste yellow fruits:

curl -s http://localhost:8080/taster/yellow | jq

You should see:

[
  {
    "fruit": {
      "color": "yellow",
      "id": 3,
      "name": "banana"
    },
    "result": "BANANA: TASTES GREAT (IF YOU LIKE FRUIT!)"
  }
]

Notice the presence of our new suffix! Quarkus apps make it super easy to code, test, and re-code on the fly.

Cleanup

We're done coding, so let's stop the app. In the first Terminal, press CTRL-C to stop the running Quarkus app (or click the clear command to do it for you).

Build executable JAR

Quarkus applications can be built as executable JARs, or native binary images. Here we'll use an executable JAR to deploy our app. Build the application:

mvn clean package -DuberJar=true -DskipTests

It produces 2 jar files:

• fruit-taster-1.0-SNAPSHOT.jar - containing just the classes and resources of the projects, it’s the regular artifact produced by the Maven build

• fruit-taster-1.0-SNAPSHOT-runner.jar - Since we used -DuberJar=true, this is an executable "Uber" JAR that can be run with java -jar.

Run the app locally

Run the app by clicking on the below command:

java -jar target/*-runner.jar

Note the fast startup time!

When measuring the footprint of a Quarkus application, we measure Resident Set Size (RSS) and not the JVM heap size which is only a small part of the overall problem. The JVM not only allocates native memory for heap (-Xms, -Xmx) but also structures required by the JVM to run your application.

So, to see the RSS, click to run the following command in another terminal:

ps -p $(jps|grep runner|awk '{print $1}') -o command,rss

You should see something like:

COMMAND                       RSS
java -jar target/fruit-tast 167660

This shows that our process is taking around 163 MB of memory (Resident Set Size, or RSS). It gets even smaller when compiled to native (more on this later).

Note that the RSS and memory usage of any app, including Quarkus, will vary depending your specific environment, and will rise as the application experiences load.

Make sure the app is still working as expected (we'll use curl this time to access it directly):

curl -s http://localhost:8080/fruits | jq

Cleanup

In the first Terminal, press CTRL-C to stop the running Quarkus native app (or click the clear command to do it for you).

Congratulations!

You've now built a Java application as an executable JAR. Quarkus also supports building to native images providing even greater startup speed and memory effeciency. Now let's give our app native powers by creating a Quarkus native app.

Now that we have our app built, let's move it into containers and into the cloud.

Install OpenShift extension

Quarkus offers the ability to automatically generate OpenShift resources based on sane default and user supplied configuration. The OpenShift extension is actually a wrapper extension that brings together the kubernetes and container-image-s2i extensions with defaults so that it’s easier for the user to get started with Quarkus on OpenShift.

Run the following command to add it to our project:

mvn quarkus:add-extension -Dextensions="openshift"

Login to OpenShift

We'll deploy our app as the developer user. Run the following command to login with the OpenShift CLI:

oc login -u developer -p developer

You should see

Login successful.

You don't have any projects. You can try to create a new project, by running

    oc new-project <projectname>

Create project

For this scenario, let's create a project that you will use to house your applications. Click:

oc new-project quarkus-spring --display-name="Sample Quarkus App using Spring APIs"

Before we deploy the application we need to deploy the Postgres database.

Deploy Postgres

When running in production, we'll need a Postgres database on OpenShift. Click the next command to deploy Postgres to your new project:

oc new-app \ -e POSTGRESQL_USER=sa \ -e POSTGRESQL_PASSWORD=sa \ -e POSTGRESQL_DATABASE=fruits \ -e POSTGRESQL_MAX_CONNECTIONS=200 \ --name=postgres-database \ openshift/postgresql`

Configure Quarkus

Since we are now deploying this to Openshift our database will no longer be on localhost. And our production is running Postgres. How do we handle these multiple configurations? Quarkus has a neat feature where we can create different profiles. So we will use the %dev profile for our local environment.

Click: fruit-taster/src/main/resources/application.properties to open this file. This file contains Quarkus configuration.

Click Copy to Editor to add the following values to the application.properties file:

%dev.quarkus.datasource.url=jdbc:h2:mem:rest-crud
%dev.quarkus.datasource.driver=org.h2.Driver
%dev.quarkus.datasource.max-size=8
%dev.quarkus.datasource.min-size=2
%dev.quarkus.hibernate-orm.database.generation=drop-and-create
%dev.quarkus.hibernate-orm.log.sql=true

quarkus.datasource.url=jdbc:postgresql://postgres-database:5432/fruits
quarkus.datasource.driver=org.postgresql.Driver
quarkus.datasource.username=sa
quarkus.datasource.password=sa
quarkus.hibernate-orm.database.generation=drop-and-create
quarkus.hibernate-orm.sql-load-script = import.sql

taste.message = tastes great
taste.suffix = (if you like fruit!)

Deploy application to OpenShift

Now let's deploy the application itself. Run the following command which will build and deploy the Quarkus app in Openshift:

mvn clean package \ -Dquarkus.kubernetes-client.trust-certs=true \ -Dquarkus.container-image.build=true \ -Dquarkus.kubernetes.deploy=true \ -Dquarkus.kubernetes.deployment-target=openshift \ -Dquarkus.openshift.expose=true \ -DskipTests \ -Dquarkus.openshift.labels.app.openshift.io/runtime=java`

The output should end with BUILD SUCCESS.

For more details of the above options:

• quarkus.kubernetes-client.trust-certs=true - We are using self-signed certs in this simple example, so this simply says to the extension to trust them.
• quarkus.container-image.build=true - Instructs the extension to build a container image
• quarkus.kubernetes.deploy=true - Instructs the extension to deploy to OpenShift after the container image is built
• quarkus.kubernetes.deployment-target=openshift - Instructs the extension to generate and create the OpenShift resources (like DeploymentConfigs and Services) after building the container
• quarkus.openshift.expose=true - Instructs the extension to generate an OpenShift Route.
• quarkus.openshift.labels.app.openshift.io/runtime=java - Adds a nice-looking icon to the app when viewing the OpenShift Developer Toplogy

Finally, make sure it's actually done rolling out:

oc rollout status -w dc/fruit-taster

Wait (about 30 seconds) for that command to report replication controller "fruit-taster-1" successfully rolled out before continuing.

If the oc rollout command appears to not finish, just CTRL-C it and run it again.

And now we can access using curl once again:

curl -s http://fruit-taster-quarkus-spring.[[HOST_SUBDOMAIN]]-80-[[KATACODA_HOST]].environments.katacoda.com/taster | jq

You should see the same fruits being tasted:

[
  {
    "fruit": {
      "color": "red",
      "id": 1,
      "name": "cherry"
    },
    "result": "CHERRY: TASTES GREAT (IF YOU LIKE FRUIT!)"
  },
  ...

You can also see the app deployed in the OpenShift Developer Toplogy

Scale the app

With that set, let's see how fast our app can scale up to 10 instances:

oc scale --replicas=10 dc/fruit-taster

Back in the OpenShift Developer Toplogy you'll see the app scaling dynamically up to 10 pods:

We now have 10 instances running providing better performance. Make sure it still works:

curl -s http://fruit-taster-quarkus-spring.[[HOST_SUBDOMAIN]]-80-[[KATACODA_HOST]].environments.katacoda.com/taster | jq

10 not enough? Try 100! Click the command to scale this app to 100 instances:

oc scale --replicas=50 dc/fruit-taster

It will take a bit longer to scale that much. In the meantime the app continues to respond:

curl -s http://fruit-taster-quarkus-spring.[[HOST_SUBDOMAIN]]-80-[[KATACODA_HOST]].environments.katacoda.com/taster | jq

You can watch the 50 pods spinning up:

oc get pods -w -l app=fruit-taster

Watch as long as you like, then CTRL-C the pod watcher.

Finally, scale it back down:

oc scale --replicas=1 dc/fruit-taster

Congratulations!

This step covered the deployment of a Quarkus application on OpenShift. To try out the native features, try the Getting Started tutorial. There is much more, and the integration with these environments has been tailored to make Quarkus applications execution very smooth. For instance, the health extension can be used for health check; the configuration support allows mounting the application configuration using config maps, the metric extension produces data scrape-able by Prometheus and so on.