Package org.apache.juneau.commons.inject

Class ConfigPropertiesBinder<T>

java.lang.Object

org.apache.juneau.commons.inject.ConfigPropertiesBinder<T>

Type Parameters:

T - The target type.

public final class ConfigPropertiesBinder<T>
extends Object

Reusable, prefix-scoped whole-object config binder — usable with or without the @ConfigProperties annotation.

For each non-static, non-synthetic, non-final field on the target, builds relaxed candidate keys of the form prefix.fieldName (via RelaxedPropertySource.candidates(String)), resolves the first candidate present in the given Settings chain, and converts it via Settings.toType(String, Class). A key absent from every candidate leaves the field's initializer value untouched ("bind-only-present" semantics). The same bind-only-present rule governs a nested @ConfigProperties field that starts out null: the nested type is only materialized if at least one key resolves anywhere under its sub-prefix; otherwise the field is left null.

Usage

MyServiceProperties props = ConfigPropertiesBinder.of(new MyServiceProperties(), "MyService").run();

Precedence (candidate-major)

Precedence is candidate-major: each spelling (in RelaxedPropertySource.candidates(String) order — verbatim, upper-underscore, lower-dotted) is resolved through the full Settings source chain before the next spelling is tried. This means a verbatim hit in a lower-precedence source can outrank a relaxed-spelling override set on a higher-precedence source, if that override used a different spelling than the one that hit first.

Caller-scoped sources

When a beanStore(BeanStore) is supplied, its PropertySource-typed beans are consulted ahead of the global Settings chain for each candidate key, but after any local/global test override recorded on settings(Settings) — a Settings.setLocal/setGlobal override always wins over a scoped source, and among the scoped sources the first one that reports the key present wins. This exactly mirrors the @Value resolution path (PropertyVar), letting a caller layer overriding or supplementary sources without mutating the shared singleton. Absent any scoped PropertySource beans, resolution is identical to binding against settings(Settings) alone.

Limitation — raw-type conversion only

Unlike @Value, conversion here is keyed on the field's raw Class (via FieldInfo.getFieldType()), not its full generic Type. Generic container types such as Optional<T> or Supplier<T> are therefore not supported as @ConfigProperties field types; use a plain field type instead.

Nested fields and circular nesting

A field whose type is itself @ConfigProperties-annotated is bound recursively under prefix.fieldName. The set of nested types along the active recursion path is tracked, and re-entering a type already on that path throws a RuntimeException instead of recursing indefinitely. A nested type that needs to be materialized (see the bind-only-present rule above) must expose an accessible no-arg constructor; if it doesn't, materialization throws a RuntimeException naming the offending field.

See Also:

• @ConfigProperties Annotation Basics

Since:

10.0.0

Method Summary

Modifier and Type	Method	Description
ConfigPropertiesBinder<T>	beanStore(BeanStore value)	Sets a caller-scoped BeanStore whose PropertySource-typed beans are consulted ahead of the global Settings chain when resolving each candidate key.
static <T> ConfigPropertiesBinder<T>	of(T target, String prefix)	Creates a new binder for target's fields under prefix.
ConfigPropertiesBinder<T>	relaxed(boolean value)	Sets whether relaxed matching is enabled.
T	run()	Runs the bind against target.
ConfigPropertiesBinder<T>	settings(Settings value)	Sets the resolver chain to bind against (overridable for tests).
ConfigPropertiesBinder<T>	validator(ConfigPropertiesValidator value)	Sets the post-bind validation hook invoked once on each fully-bound target.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

of

public static <T> ConfigPropertiesBinder<T> of(T target,
 String prefix)

Creates a new binder for target's fields under prefix.

Defaults (overridable via the fluent setters before calling run()): Settings.get() for the settings chain, true for relaxed(boolean), and ConfigPropertiesValidator.NO_OP for validator(ConfigPropertiesValidator).

Type Parameters:

T - The target type.

Parameters:

target - The instance to populate. Must not be null.

prefix - The property-key prefix (no trailing dot). Must not be null.

Returns:

A new binder builder.

settings

public ConfigPropertiesBinder<T> settings(Settings value)

Sets the resolver chain to bind against (overridable for tests).

Parameters:

value - The settings chain. Must not be null when run() is called.

Returns:

This object.

relaxed

public ConfigPropertiesBinder<T> relaxed(boolean value)

Sets whether relaxed matching is enabled.

Parameters:

value - When true, tries RelaxedPropertySource.candidates(String) variants on a verbatim miss. Defaults to true.

Returns:

This object.

validator

public ConfigPropertiesBinder<T> validator(ConfigPropertiesValidator value)

Sets the post-bind validation hook invoked once on each fully-bound target.

Parameters:

value - The post-bind hook. Must not be null when run() is called. Defaults to ConfigPropertiesValidator.NO_OP.

Returns:

This object.

beanStore

public ConfigPropertiesBinder<T> beanStore(BeanStore value)

Sets a caller-scoped BeanStore whose PropertySource-typed beans are consulted ahead of the global Settings chain when resolving each candidate key.

This mirrors the way @Value resolution layers a store's PropertySource beans over the global chain: beanStore.getBeansOfType(PropertySource.class) walks parent→local, so a caller (e.g. a per-RestContext config bridge) can supply overriding or supplementary property sources without mutating the shared singleton. When the store has no PropertySource beans, behavior is identical to binding against settings(Settings) alone (no allocation, no behavior change).

Parameters:

value - The caller-scoped bean store, or null for none (the default).

Returns:

This object.

run

public T run()

Runs the bind against target.

Returns:

The same target instance (for method chaining).

Throws:

IllegalArgumentException - If settings(Settings) or validator(ConfigPropertiesValidator) was set to null.

RuntimeException - If circular @ConfigProperties nesting is detected, a property value could not be converted to its field's type, or a nested @ConfigProperties type could not be instantiated.