Vidocq Documentation
Version

Prerequisites

  • Java 25+

  • Maven 3.9.16 (pinned via .sdkmanrc — run sdk env) or Gradle

Installation

Add Ravel to your pom.xml. The API alone is not enough — ConfigProvider.getConfig() throws IllegalStateException when no implementation is present, so pull in ravel-core as well:

<dependencies>
    <dependency>
        <groupId>io.vidocq.ravel</groupId>
        <artifactId>ravel-api</artifactId>
        <version>0.4.0-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>io.vidocq.ravel</groupId>
        <artifactId>ravel-core</artifactId>
        <version>0.4.0-SNAPSHOT</version>
    </dependency>
</dependencies>

For CDI integration (optional), also add:

<dependency>
    <groupId>io.vidocq.ravel</groupId>
    <artifactId>ravel-cdi-vauban</artifactId>
    <version>0.4.0-SNAPSHOT</version>
</dependency>

First configuration lookup

The simplest way to get started is to use ConfigProvider:

import org.eclipse.microprofile.config.ConfigProvider;
import org.eclipse.microprofile.config.Config;

public class Main {
    public static void main(String[] args) {
        Config config = ConfigProvider.getConfig();

        // Get a required string value
        String appName = config.getValue("app.name", String.class);
        System.out.println("App: " + appName);

        // Get an optional value
        Optional<String> appVersion = config.getOptionalValue("app.version", String.class);
        System.out.println("Version: " + appVersion.orElse("1.0.0"));

        // Get an integer
        int port = config.getValue("app.port", Integer.class);
        System.out.println("Port: " + port);
    }
}

Configuration sources

Ravel looks for configuration in this order (highest ordinal first):

  1. System properties (ordinal 400) — set via -Dkey=value

  2. Environment variables (ordinal 300) — PATH, USER, etc., automatically translated to config keys

  3. microprofile-config.properties (ordinal 100) — file in META-INF/ classpath

System properties

java -Dapp.name="My App" -Dapp.port=8080 MyApplication
Config config = ConfigProvider.getConfig();
String appName = config.getValue("app.name", String.class);
// Result: "My App"

Environment variables

export APP_NAME="My App"
export APP_PORT=8080
java MyApplication

Ravel automatically maps: - APP_NAME → app.name - APP_PORT → app.port - my_property → my.property

Config config = ConfigProvider.getConfig();
String appName = config.getValue("app.name", String.class);
// Result: "My App"

microprofile-config.properties

Create a file src/main/resources/META-INF/microprofile-config.properties:

app.name=My App
app.port=8080
app.debug=false

Type conversion

Ravel supports many built-in types:

Config config = ConfigProvider.getConfig();

// Primitives and boxes
int port = config.getValue("app.port", int.class);
Integer portBox = config.getValue("app.port", Integer.class);

// Arrays and multi-valued properties (comma-separated)
String[] items = config.getValue("app.items", String[].class);
List<Integer> ids = config.getValues("app.ids", Integer.class);

// Temporal types
Duration timeout = config.getValue("app.timeout", Duration.class);
LocalDate startDate = config.getValue("app.start", LocalDate.class);

// Custom types
MyCustomType value = config.getValue("app.custom", MyCustomType.class);

See Type Converters for the full list of built-in converters.

Property expressions

Use ${key} to reference other properties:

app.name=MyApp
app.full.name=${app.name} v2.0
String fullName = config.getValue("app.full.name", String.class);
// Result: "MyApp v2.0"

Use ${key:default} to provide a fallback:

app.full.name=${app.name} ${app.version:1.0.0}

See Property Expressions for more details.

Configuration profiles

Use prefixes to switch configuration per environment:

app.name=MyApp
app.debug=false

# Development overrides
%dev.app.debug=true
%dev.app.port=9000

# Production overrides
%prod.app.port=8443
%prod.app.debug=false

Activate the dev profile:

java -Dmp.config.profile=dev MyApplication

See Config Profiles for more details.

Next steps