variable-expansion.md

Variable Expansion

Externalized Properties has support for expansion of variables in externalized property names and/or any String values. This is made possible by VariableExpanders. By default, a simple implementation is already enabled. If a custom/more powerful variable expansion implementation is necessary, a custom variable expander can be created by implementing the VariableExpander interface and registering it to Externalized Properties.

🌟 Automatic Variable Expansion in Property Names

Variable expansion is supported in property names and is enabled by default e.g.

public interface ApplicationProperties {
  @ExternalizedProperty("environment")
  default String environment() {
    return "dev";
  }

  // ${environment} will be replaced with whatever the 
  // value of the "environment" property is e.g. dev.my.property
  @ExternalizedProperty("${environment}.my.property")
  String myProperty();
}

If custom variable expansion is required, the default variable expander can be overriden via ExternalizedProperties.Builder e.g.

public static void main(String[] args) {
  ExternalizedProperties externalizedProperties = ExternalizedProperties.builder()
      .defaults()
      // Format: #(variable)
      .variableExpander(new SimpleVariableExpander("#(", ")"))
      .build();
  
  ApplicationProperties appProperties = 
      externalizedProperties.initialize(ApplicationProperties.class);
}

Built-in variable expander implementations:

• SimpleVariableExpander - Uses a speficied prefix and suffix to match variables.
• PatternVariableExpander - Uses a regex to match variables.
• NoOpVariableExpander - Disables variable expansion.

✨ Automatic Variable Expansion in Properties

Variable expansion is supported in properties. This can be enabled via the ExternalizedProperties builder e.g.

public interface ApplicationProperties {
  @ExternalizedProperty("my.property")
  String myProperty();
}

# application.properties
variable=variable-value
my.property=${variable}

public static void main(String[] args) {
  ExternalizedProperties externalizedProperties = ExternalizedProperties.builder()
      .enableVariableExpansionInProperties()
      .resolvers(applicationPropertiesResolver())
      .build();
  
  ApplicationProperties appProperties = 
      externalizedProperties.initialize(ApplicationProperties.class);

  // Resolved property is "variable-value"
  String resolved = appProperties.myProperty();
}

🌟 Variable Expansion in Arbitrary Values

Externalized Properties can create proxies that expand variables in any String values. This is made possible by the @VariableExpanderFacade annotation e.g.

(Kindly see @VariableExpanderFacade documentation to learn more about the rules of defining a variable expander facade.)

public interface ProxyInterface {
  @VariableExpanderFacade
  String expandVariables(String value);
}

Invoking the methods annotated with @VariableExpanderFacade will delegate the arguments to the registered VariableExpander to expand any variables in the String value. The expanded value will be returned by the method.