Instant On Documenation - Behavior of config property when no default value is set

[anjumfatima90]

The config property when no default value is set and the value is updated after checkpoint before restore.

• For @ApplicationScoped beans

1. Scenario 1: Config property is accessed early during checkpoint.

   Result: A warning CWWKC0651W is logged to let the user know that the updated value of the property might not be used
   during restore.

2. Scenario 2: Config property is NOT accessed early during checkpoint.

   Result: The updated config value should be used on restore.

• For @RequestScoped beans - The updated config value should be used on restore.

[dmuelle]

Hi @anjumfatima90 - is there a development epic associated with this update? If so, what is the target release? Thanks

[anjumfatima90]

Hi @dmuelle - Please ignore the above content. Updated content is as below. This content is related to the existing functionalities and they is no target release associated with it and it should probably go under https://openliberty.io/docs/latest/instanton-limitations.html#mp-config

The configuration property can be introduced inside the application in two ways: either statically through <T> or Optional<T>, or dynamically using a Provider<T>.

When statically injecting a property, it is necessary to define a default value for it in microprofile-config.properties or by employing a variable with a defaultValue in server.xml. The actual value can be assigned via server.env or by altering the server.xml configuration after the checkpoint. However, it's important to note that using server.env to supply configuration values before the checkpoint is restricted. If you use environment variables for configuration values before the checkpoint, you may encounter a configuration exception, specifically, io.smallrye.config.inject.ConfigException: SRCFG02000: Failed to Inject @ConfigProperty for the key, as the configuration property might not be found in any configuration source.

To prevent this exception, you can set a default value for the statically injected property in microprofile-config.properties, a variable with a defaultValue within the server.xml, or by utilizing defaultValue within the @ConfigProperty annotation. Additionally, you can inject the configuration property using static Optional<T> or a dynamic configuration source Provider<T> to avoid the exception.

In cases where an application includes early startup code and you are using the afterAppStart checkpoint option, attempting to access the configuration property injected with Optional<T> or Provider<T> without a default value will result in a java.util.NoSuchElementException: SRCFG00014: The configuration is required, but it couldn't be found in any configuration source. Hence, in such cases it becomes necessary to check if the value is present before accessing it.

@tjwatson please review the above content and kindly let me know if I have missed anything here.

[tjwatson]

The configuration property can be introduced inside the application in two ways: either statically through <T> or Optional<T>, or dynamically using a Provider<T>.

I think we need some examples that use the annotations for injecting config, we have static, static-optional, dynamic and dynamic-optional:

    @Inject
    @ConfigProperty(name = "static_config")
    String staticConfig;

    @Inject
    @ConfigProperty(name = "static_optional_config")
    Optional<String> staticOptionalConfig;

    @Inject
    @ConfigProperty(name = "dynamic_config")
    Provider<String> dynamicConfig;

    @Inject
    @ConfigProperty(name = "dynamic_optional_config")
    Provider<Optional<String>> dynamicOptionalConfig;

The non-optional ones above named static_config and dynamic_config both will cause errors if there is no value found in an existing config source during checkpoint. We need an example of what that error looks like for the docs. I suggest we use the examples above and show what the error looks like with these names.

The actual value can be assigned via server.env or by altering the server.xml configuration after the checkpoint.

We should not mention updating the server.env nor the server.xml for InstantOn scenarios because that is not a convenient thing to do for in-container scenarios. Instead we should reference updating config with variable substitution precedence where the typical in-container deployment is going to update configuration with environment variables or with the variables loaded from a mounted variable source directory.

If you use environment variables for configuration values before the checkpoint, you may encounter a configuration exception, specifically, io.smallrye.config.inject.ConfigException: SRCFG02000: Failed to Inject @ConfigProperty for the key, as the configuration property might not be found in any configuration source.

We need to phrase the in a more general way that doesn't mention environment variables because this can happen if there is simply no default value to be found. Something like:

If no default value is found for a named configuration key (e.g. `static_config` or `dynamic_config`) then the following error will occur:
SRCFG02000: Failed to Inject @ConfigProperty for the key, as the configuration property might not be found in any configuration source.
io.smallrye.config.inject.ConfigException: SRCFG02000: Failed to Inject @ConfigProperty for key static_config into Example.staticConfig since the config property could not be found in any config source

This error can be avoided by providing a default value for the configuration key in one of the following ways:

• Specify the default value on the @ConfigProperty annotation like the following:

    @Inject
    @ConfigProperty(name = "static_config", defaultValue = "defaultValue")
    String staticConfig;

    @Inject
    @ConfigProperty(name = "dynamic_config", defaultValue = "defaultValue")
    Provider<String> dynamicConfig;

• Specify the default value in the application META-INF/microprofile-config.properties resource

static_config=defaultValue
dynamic_config=defaultValue

• Specify a default value in a server.xml variable

    <variable name="static_config" defaultValue="defaultValue" />
    <variable name="dynamic_config" defaultValue="defaultValue" />

The "defaultValue" can then be overridden on restore by configuring the value with an environment variable or values from the variable source directory. Caution is needed for CDI beans that are @ApplicationScope which are created during application startup when using the afterAppStart checkpoint option. If no default value is found for the configuration key then the following error will occur:

java.util.NoSuchElementException: SRCFG00014: The configuration is required, but it couldn't be found in any configuration source

Furthermore, if the @ConfigProperty injection site is not using dynamic config then any default value injected into the application scoped bean before checkpoint will not be updated on restore. This is already mentioned in the docs at Accessing MicroProfile Config too early

@anjumfatima90 I would like you to take a look at updating the limitations doc with this information at https://github.com/OpenLiberty/docs/blob/vNext/modules/ROOT/pages/instanton-limitations.adoc then we can do a technical review before handing it over to @dmuelle to do a doc review.

[dmuelle]

Hi @anjumfatima90 @tjwatson - looking over these comments to include this update with the 23.0.0.11 release. Are you planning to submit an initial draft of the update? Let me know how I help. I can get started based on these comments or happy to review any proposed updates when you have them ready.

FYI our doc freeze for this release is 11/9 so we need the proposed content at least a week before that (~11/2) to make sure we can get everything sorted for the release. Thanks

[tjwatson]

looking over these comments to include this update with the 23.0.0.11 release

I'm hoping to have @anjumfatima90 look at doing the initial draft. Note that this isn't to document new behavior for 23.0.0.11. Rather it is to document existing behavior from 23.0.0.6.