Vidocq Documentation
Version

This page consolidates Heisenberg’s public surface: Maven artifacts, Java modules, full table of MP FT 4.1 annotations with the canonical composition order, and the MicroProfile Config keys recognised through Ravel.

Maven artifacts

groupId artifactId Role

io.vidocq.heisenberg

heisenberg-api

Stable public SPI: FtMetricsRecorder (metrics recorder) and FaultToleranceException; re-exports the MP FT 4.1 spec API (requires transitive).

io.vidocq.heisenberg

heisenberg-core

Pure Java 25 policy engines without CDI: RetryEngine, TimeoutEngine, CircuitBreakerEngine, BulkheadEngine, FallbackResolver, PolicyComposer.

io.vidocq.heisenberg

heisenberg-cdi-vauban

Single CDI interceptor (FaultToleranceInterceptor) and Vauban BCE (HeisenbergExtension).

io.vidocq.heisenberg

heisenberg-mp-ft-api

Modularised repackage of microprofile-fault-tolerance-api (named Java module, jlink-compatible).

io.vidocq.heisenberg

heisenberg-bench

JMH benchmarks (vs SmallRye Fault Tolerance). Not for production.

io.vidocq.heisenberg

heisenberg-examples

Usage examples, standalone or integrated.

io.vidocq.heisenberg

heisenberg-tck

Official MP FT 4.1 TCK runner — in-reactor, gated by the tck Maven profile. Do not declare as an application dependency.

All versions at 0.3.0 (latest release on Maven Central: 0.3.0).

Java modules

Module Contents

io.vidocq.heisenberg.api

io.vidocq.heisenberg.api — public SPI: FtMetricsRecorder (metrics SPI with its NOOP constant and the RetryResult, CBCallResult, CBState enums) and FaultToleranceException. Re-exports the spec annotations via requires transitive microprofile.fault.tolerance.api.

io.vidocq.heisenberg.core

Internal implementations: engines, PolicyComposer, the CircuitBreakerStateRegistry / BulkheadStateRegistry interfaces and the immutable *Config records. The io.vidocq.heisenberg.internal package is exported only to io.vidocq.heisenberg.cdi.vauban.

io.vidocq.heisenberg.cdi.vauban

CDI integration: FaultToleranceInterceptor, HeisenbergExtension (BCE), StateRegistryBean, BulkheadStateRegistryBean, MetricsRecorderResolver, CompositeFtMetricsRecorder.

io.vidocq.heisenberg.internal is invisible to application modules (qualified export to io.vidocq.heisenberg.cdi.vauban only). Any application class depending on it indicates a regression to fix.

MicroProfile Fault Tolerance 4.1 annotations

Summary table of the six annotations, in wrapping order from the outside in.

Annotation Level Effect Status

@Asynchronous

Method

Runs the method on a virtual thread. Return type: CompletionStage<T> or Future<T>.

✅

@Fallback

Method

Provides an alternative result on failure. Parameters: fallbackMethod or FallbackHandler<T> class.

✅

@Retry

Method or class

Bounded retries with delay, jitter, retryOn / abortOn.

✅

@CircuitBreaker

Method or class

CLOSED/OPEN/HALF_OPEN breaker over a sliding window.

✅

@Timeout

Method or class

Bounds an attempt’s duration — virtual thread + join(Duration).

✅

@Bulkhead

Method or class

Isolation via semaphore (sync) or semaphore-bounded waiting queue (async).

✅

Detailed parameters

@Retry

Parameter Default Effect

maxRetries

3

Maximum number of retries after the first attempt. -1 = unbounded (use with maxDuration).

delay

0

Base delay between attempts.

delayUnit

MILLIS

delay unit.

maxDuration

180000

Total maximum duration (across all attempts).

durationUnit

MILLIS

maxDuration unit.

jitter

200

Random variation added to delay.

jitterDelayUnit

MILLIS

jitter unit.

retryOn

Throwable

Exceptions that trigger a retry.

abortOn

None

Exceptions that abort immediately (take precedence over retryOn).

@Timeout

Parameter

Default

Effect

value

1000

Maximum duration of an attempt.

unit

MILLIS

value unit.

Beyond that, TimeoutException is raised. For @Asynchronous, the underlying virtual thread is interrupted (best-effort).

@CircuitBreaker

Parameter

Default

Effect

requestVolumeThreshold

20

Sliding window size.

failureRatio

0.5

Opening threshold (failure proportion).

delay

5000

OPEN state duration before transition to HALF_OPEN.

delayUnit

MILLIS

delay unit.

successThreshold

1

Number of consecutive OK probes to re-close.

failOn

Throwable

Exceptions counted as failure.

skipOn

None

Exceptions not counted (take precedence over failOn).

@Bulkhead

Parameter

Default

Effect

value

10

Maximum concurrency (semaphore permits).

waitingTaskQueue

10

Waiting queue size (@Asynchronous mode only).

@Fallback

Parameter

Default

Effect

value

Fallback.DEFAULT

FallbackHandler<T> class.

fallbackMethod

""

Name of a private/package-local method on the class.

applyOn

Throwable

Exceptions that trigger the fallback.

skipOn

None

Exceptions that skip the fallback.

Note: value and fallbackMethod are mutually exclusive.

@Asynchronous

No parameter. The method must return CompletionStage<T> or Future<T>.

MicroProfile Config keys

All keys are read through ConfigProvider.getConfig(). Precedence: method > class > global > annotation default (spec §12).

Key Effect

<Annotation>/<param>

Global value.

<FQCN>/<Annotation>/<param>

Class override.

<FQCN>/<method>/<Annotation>/<param>

Method override — highest precedence.

MP_Fault_Tolerance_NonFallback_Enabled

Boolean. false disables @Retry, @Timeout, @CircuitBreaker, @Bulkhead, @Asynchronous; @Fallback stays active (spec §11). Dotted alias: mp.fault.tolerance.nonFallback.enabled.

mp.fault.tolerance.metrics.enabled

Boolean. false disables §9 and §10 recorders. Default true.

mp.fault.tolerance.interceptor.priority

Interceptor priority (@Priority). Default 4010 (Platform.AFTER + 10); Integer.MAX_VALUE disables the interceptor entirely.

Examples with their parameters:

# Global
Retry/maxRetries=5
Timeout/value=2000
CircuitBreaker/failureRatio=0.6

# Per class
io.example.CatalogClient/Retry/maxRetries=2

# Per method (highest precedence)
io.example.CatalogClient/fetch/Retry/maxRetries=1
io.example.CatalogClient/fetch/Retry/delay=500
io.example.CatalogClient/fetch/CircuitBreaker/delay=30000
io.example.CatalogClient/fetch/Bulkhead/value=20

Exceptions

Exception Case

org.eclipse.microprofile.faulttolerance.exceptions.TimeoutException

@Timeout exceeded on an attempt.

org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException

Call rejected in OPEN state.

org.eclipse.microprofile.faulttolerance.exceptions.BulkheadException

Bulkhead saturated.

org.eclipse.microprofile.faulttolerance.exceptions.FaultToleranceException

Generic runtime error.

org.eclipse.microprofile.faulttolerance.exceptions.FaultToleranceDefinitionException

Invalid annotation detected at startup (@Asynchronous signature, out-of-range values, etc.).

Vidocq SPI exposed by heisenberg-api

The public surface of heisenberg-api is deliberately small — two types, plus the re-exported spec annotations.

Type Role

io.vidocq.heisenberg.api.FtMetricsRecorder

Metrics recorder SPI, implementable by a third-party module. Provided implementations (in heisenberg-cdi-vauban): DiracFtMetricsRecorder (MP Metrics) and OtelFtMetricsRecorder (OpenTelemetry); several recorders are composed via CompositeFtMetricsRecorder, and the FtMetricsRecorder.NOOP constant is used when none is present.

io.vidocq.heisenberg.api.FaultToleranceException

Base Heisenberg exception for configuration errors detected at container startup — distinct from the spec-defined runtime exceptions above.

The shared state registries (CircuitBreakerStateRegistry, BulkheadStateRegistry), the policy engines and the policy configuration records are internal (io.vidocq.heisenberg.internal, exported only to the CDI module) — they are not extension points.

Compatibility

  • Java 25 (LTS), Maven 3.9.16.

  • CDI 4.1 Lite (Vauban) or any CDI 4.1 Lite-compatible container.

  • MicroProfile Config 3.1 (Ravel) in provided.

  • OpenTelemetry 1.39 (Humboldt) in requires static — optional.

  • MicroProfile Metrics 5.x (Dirac) — optional.

Bugs and benchmarks

  • BUG.md — tracked reproducible bugs.

  • BENCH.md — JMH benchmarks vs SmallRye Fault Tolerance.

Going further

  • Concepts — MP FT model, canonical order.

  • Internals — pure engines, virtual threads.

  • TCK — execution and status.