<commit_before>= DeltaSpike Configuration Mechanism

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

== Introduction

The goal of the DeltaSpike configuration mechanism is to make it
obsolete to touch released binaries for changing the configuration of
your project. All values which are needed in your code (but should not
be hardcoded as static final constants) can be maintained via
DeltaSpike's own configuration mechanism in a very flexible and powerful
way.

=== Benefits for Production

Once a binary like a WAR file or an EAR got created and tested, it must
_not_ get changed anymore. The exact same binary which got created by
the release manager will get moved to the Test system, then further
propagated to the Staging environment and finally (if all people are
happy with it) will get moved to the Production system. And all this
without any changes on the binary itself!

The Apache DeltaSpike configuration system makes this possible by
providing a default configuration inside the binary and allowing to
amend this configuration (e.g. database credentials, some URLs from
remote REST or SOAP endpoints, etc) from outside like environment
settings, JNDI or the current <<projectstage.adoc#,ProjectStage>>.


=== Drop-In Configuration

This mechanism also allows for dynamic configuration in case of a JAR
drop-in. By adding some JAR to the classpath, all its contained
configuration will get picked up and considered in the property value
evaluation. You could also use this mechanism to switch implementations
of some SPI (Service Provider Interface) in your own code.

=== CDI-Extension Configuration

In some cases low-level configs are needed, for example during the bootstrapping
process of the CDI container.

The good news: our DeltaSpike configuration mechanism does not rely on
any other EE mechanism to be booted. Which means it can perfectly get
used to even configure those parts itself. Since the mechanism does not
rely on CDI it can for example be used to configure CDI-Extensions.

Currently this is, for example, used to configure the value of the current <<projectstage.adoc#,ProjectStage>>, configured values which can be
used in the expressions for `@Exclude`, 'Deactivatable', etc. DeltaSpike
needs such a low-level approach for several features internally, but
users can utilize it for their own needs as well. This is done by using
the `ConfigResolver` which resolves and caches `ConfigSource`s per
application.


== Accessing configured values using ConfigResolver

The `ConfigResolver` is the central point to access configuration in DeltaSpike. There are several different APIs
 and ways to access the individual configured values, each suitable for a different purpose:

 * `ConfigResolver` methods for easy programmatic access to values
 * `TypedResolver` API for typed configuration values and precise control over resolution
 * `@ConfigProperty` for injection of configured values into beans

All three mechanisms are described in the following sections.

=== ConfigResolver methods

ConfigResolver offers several methods for easy access to String values of configured properties.

==== getPropertyValue()

The method `ConfigResolver#getPropertyValue(String key)` returns the value configured for a given key
as `String`, or `null` if no value has been found.

`ConfigResolver#getAllPropertyValues(String key)` has a similar contract
but it returns a list which might be empty if there are no configured
values for the given key.

This is a code excerpt about how to do a simple lookup in the deltaspike
configuration:

[source,java]
-------------------------------------------------------------------------------
String dbUserName = ConfigResolver.getPropertyValue("databaseconfig.username");
-------------------------------------------------------------------------------

==== getProjectStageAwarePropertyValue()

The method
`ConfigResolver#getProjectStageAwarePropertyValue(String key)` utilizes
the <<projectstage.adoc#,DeltaSpike ProjectStage>> mechanism to allow
configured values to depend on the current `ProjectStage` of the running system.

This is done by first looking up the ProjectStage (this internally
happens with the DeltaSpike ConfigResolver as well) and then go down the
following lookup chain until we found a configured value.

* key + '.' + projectStage , e.g. "databaseconfig.username.Production"
* key alone , e.g. "databaseconfig.username"

==== getPropertyAwarePropertyValue()

The method
`ConfigResolver#getProjectStageAwarePropertyValue(String key, String property)`
first looks up the configured value of the given property and uses this
value to determine the final lookup path. All those lookups take the<commit_msg>DELTASPIKE-973 Fixed method name in Configuration doc<commit_after>= DeltaSpike Configuration Mechanism

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

== Introduction

The goal of the DeltaSpike configuration mechanism is to make it
obsolete to touch released binaries for changing the configuration of
your project. All values which are needed in your code (but should not
be hardcoded as static final constants) can be maintained via
DeltaSpike's own configuration mechanism in a very flexible and powerful
way.

=== Benefits for Production

Once a binary like a WAR file or an EAR got created and tested, it must
_not_ get changed anymore. The exact same binary which got created by
the release manager will get moved to the Test system, then further
propagated to the Staging environment and finally (if all people are
happy with it) will get moved to the Production system. And all this
without any changes on the binary itself!

The Apache DeltaSpike configuration system makes this possible by
providing a default configuration inside the binary and allowing to
amend this configuration (e.g. database credentials, some URLs from
remote REST or SOAP endpoints, etc) from outside like environment
settings, JNDI or the current <<projectstage.adoc#,ProjectStage>>.


=== Drop-In Configuration

This mechanism also allows for dynamic configuration in case of a JAR
drop-in. By adding some JAR to the classpath, all its contained
configuration will get picked up and considered in the property value
evaluation. You could also use this mechanism to switch implementations
of some SPI (Service Provider Interface) in your own code.

=== CDI-Extension Configuration

In some cases low-level configs are needed, for example during the bootstrapping
process of the CDI container.

The good news: our DeltaSpike configuration mechanism does not rely on
any other EE mechanism to be booted. Which means it can perfectly get
used to even configure those parts itself. Since the mechanism does not
rely on CDI it can for example be used to configure CDI-Extensions.

Currently this is, for example, used to configure the value of the current <<projectstage.adoc#,ProjectStage>>, configured values which can be
used in the expressions for `@Exclude`, 'Deactivatable', etc. DeltaSpike
needs such a low-level approach for several features internally, but
users can utilize it for their own needs as well. This is done by using
the `ConfigResolver` which resolves and caches `ConfigSource`s per
application.


== Accessing configured values using ConfigResolver

The `ConfigResolver` is the central point to access configuration in DeltaSpike. There are several different APIs
 and ways to access the individual configured values, each suitable for a different purpose:

 * `ConfigResolver` methods for easy programmatic access to values
 * `TypedResolver` API for typed configuration values and precise control over resolution
 * `@ConfigProperty` for injection of configured values into beans

All three mechanisms are described in the following sections.

=== ConfigResolver methods

ConfigResolver offers several methods for easy access to String values of configured properties.

==== getPropertyValue()

The method `ConfigResolver#getPropertyValue(String key)` returns the value configured for a given key
as `String`, or `null` if no value has been found.

`ConfigResolver#getAllPropertyValues(String key)` has a similar contract
but it returns a list which might be empty if there are no configured
values for the given key.

This is a code excerpt about how to do a simple lookup in the deltaspike
configuration:

[source,java]
-------------------------------------------------------------------------------
String dbUserName = ConfigResolver.getPropertyValue("databaseconfig.username");
-------------------------------------------------------------------------------

==== getProjectStageAwarePropertyValue()

The method
`ConfigResolver#getProjectStageAwarePropertyValue(String key)` utilizes
the <<projectstage.adoc#,DeltaSpike ProjectStage>> mechanism to allow
configured values to depend on the current `ProjectStage` of the running system.

This is done by first looking up the ProjectStage (this internally
happens with the DeltaSpike ConfigResolver as well) and then go down the
following lookup chain until we found a configured value.

* key + '.' + projectStage , e.g. "databaseconfig.username.Production"
* key alone , e.g. "databaseconfig.username"

==== getPropertyAwarePropertyValue()

The method
`ConfigResolver#getPropertyAwarePropertyValue(String key, String property)`
first looks up the configured value of the given property and uses this
value to determine the final lookup path. All those lookups take the
{'fraction_non_alphanumeric': 0.07181047197640118, 'fraction_numerical': 0.0010140117994100295, 'mean_word_length': 4.392147117296223, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7653654', 'n_tokens_mistral': 2466, 'n_tokens_neox': 2384, 'n_words': 1457}