Quarkus Roq Data

Quarkus Roq Data is a Quarkus extension that registers JSON/YAML files as CDI beans, accessible from Qute templates and injectable in Java code with type safety.

Roq Data is already included as part of the Roq Static Site Generator extension io.quarkiverse.roq:quarkus-roq. Follow Standalone installation section to use it standalone.

Data files

Add JSON or YAML files to your project’s data directory. Each file becomes a CDI bean named after the file (without extension).

Supported extensions: .json, .yml, .yaml.
data/mountain.json
{
    "name": "Lhotse",
    "elevation": 8516
}

Type-safe mapping

Use @DataMapping on a record to create a typed CDI bean:

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

@DataMapping("mountain") (1)
public record Mountain(String name, Integer elevation) {}
1 The value must match the data filename (without extension).

Then inject it in your code:

@Inject
Mountain mountain;

Dynamic mapping

For untyped access, inject the raw JSON using @Named:

@Inject
@Named("mountain") (1)
JsonObject mountain;
1 The filename of the data file without the extension.

Array data files

For data files where the root element is a JSON/YAML array:

data/mountains.json
[
    {
        "name": "Lhotse",
        "elevation": 8516
    },
    {
        "name": "Everest",
        "elevation": 8849
    }
]

Type-safe mapping

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

@DataMapping(value = "mountains", type = DataMapping.Type.ARRAY_FILE) (1)
public record Mountains(List<Mountain> list) { (2)
}
1 Use Type.ARRAY_FILE to indicate the root element is an array.
2 The record must have a single constructor parameter of type List<T>.

Dynamic mapping

@Inject
@Named("mountains") (1)
JsonArray mountains;
1 The filename of the data file without the extension.

Data directories

A directory inside data/ is automatically grouped into a single JsonObject bean, with each file as a key (filename without extension). Individual files are also available as separate beans.

data/heroes/
  batman.yaml    # { "name": "Batman", "city": "Gotham" }
  superman.yaml  # { "name": "Superman", "city": "Metropolis" }

This produces:

  • @Named("heroes") JsonObject with keys batman and superman

  • @Named("heroes/batman") JsonObject for the individual file

Directory mapping

For type-safe access to data directories, use ARRAY_DIR or OBJECT_DIR:

As a list
@DataMapping(value = "heroes", type = DataMapping.Type.ARRAY_DIR)
public record HeroList(List<Hero> list) {
    public record Hero(String name, String city) {}
}
As a map (filename as key)
@DataMapping(value = "heroes", type = DataMapping.Type.OBJECT_DIR)
public record HeroMap(Map<String, Hero> map) {
    public record Hero(String name, String city) {}
}

Type reference

The type attribute on @DataMapping controls how data is loaded:

Type Source Constructor Description

OBJECT_FILE

Single file

Direct fields

Default. Maps a file to a typed object

ARRAY_FILE

Single file (array)

List<T>

Maps a root-level array file to a list

ARRAY_DIR

Directory

List<T>

Maps each file in a directory to a list item

OBJECT_DIR

Directory

Map<String, T>

Maps each file to a map entry (filename as key)

Qute template access

Data beans are named and can be accessed from any Qute template using the cdi namespace:

{cdi:mountain.name}: {cdi:mountain.elevation}

{#for mountain in cdi:mountains.list}
  <li>{mountain.name}: {mountain.elevation}</li>
{/for}

{cdi:heroes.batman.name}
For type-safety, use a @DataMapping bean and access it using the cdi namespace.

Standalone installation

Roq Data is included as part of the Roq Static Site Generator extension io.quarkiverse.roq:quarkus-roq. You can also use it standalone.

If you want to use this extension standalone, add the io.quarkiverse.roq:quarkus-roq-data extension 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>2.1.1</version>
</dependency>

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.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

quarkus.roq.data.log-data-beans

Log data beans as info during build

Environment variable: QUARKUS_ROQ_DATA_LOG_DATA_BEANS

boolean

true