Quarkus Roq Data

Quarkus Roq Data is a Quarkus extension that uses JSON/YAML file content to use in a type-safe way in your project.

Installation

If you want to use this extension, you need to add the io.quarkiverse.roq:quarkus-roq-data extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.roq</groupId>
    <artifactId>quarkus-roq-data</artifactId>
    <version>{project-version}</version>
</dependency>

Getting started

Once you have the extension installed, you can add a JSON or YAML file to your project’s src/main/site/data directory.

The data file can use .json, .yml, or .yaml extensions.

car.json

{
    "make": "Gol",
    "year": 1994
}

To use the data in your Java code, you need to create a Java class that matches the structure of the JSON or YAML file.

Car.java

import io.quarkiverse.roq.data.runtime.annotations.DataMapping;

@DataMapping("car") (1)
public record Car(String make, Integer year) {}

Inject the Car record into a resource class.

Resource.java

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/site")
public class Resource {

    @Inject
    Car car;

    @GET
    public String getCar() {
        return car.toString();
    }
}

1	The filename of the data file without the extension.

Access the resource using the following URL: http://localhost:8080/site. The output should be Quarkus Site - Quarkus Site generated by Roq.

Mapping data file as a array

If your data file root element is an array, you can map it using the parentArray attribute as shown below:

list.json

[
    {
        "name": "Quarkus OpenAPI Generator",
        "description": "Quarkus extension to generate Java code from OpenAPI specifications"
    },
    {
        "name": "Quarkus Dapr",
        "description": "Quarkus extension to integrate with Dapr"
    }
]

Extensions.java

import java.util.List;
import io.quarkiverse.roq.data.runtime.annotations.DataMapping;

@DataMapping(value = "list", parentArray = true) (1)
public record Extensions(List<Extension> list) { (2)

    public record Extension(String name, String description) {
    }
}

1	The `parentArray` attribute is set to `true` to indicate that the root element of the data file is an array.
2	The class aimed to map the data file must have a constructor that accepts a single parameter of type `List<T>`, where `T` is the type of the elements in the array.

The class annotated with @DataMapping must have a constructor that accepts a single parameter of type List<T>, where T is the type of the elements in the array.

With the above configuration, the Extensions record will be have a list of Extension records and can be injected via CDI.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.roq.data.dir` The location of the Roq data files relative to the quarkus.roq.site-dir. Environment variable: `QUARKUS_ROQ_DATA_DIR`	string	`_data`
`quarkus.roq.data.enforce-bean` Whether to enforce the use of a bean for each data file. With this option enabled, when a record is annotated with `DataMapping`, a bean will be created and populated with the data from the file. Environment variable: `QUARKUS_ROQ_DATA_ENFORCE_BEAN`	boolean	`false`

Configuration property

Type

Default

quarkus.roq.data.dir

The location of the Roq data files relative to the quarkus.roq.site-dir.

Environment variable: QUARKUS_ROQ_DATA_DIR

string

_data

quarkus.roq.data.enforce-bean

Whether to enforce the use of a bean for each data file.
With this option enabled, when a record is annotated with DataMapping, a bean will be created and populated with the data from the file.

Environment variable: QUARKUS_ROQ_DATA_ENFORCE_BEAN

boolean

false