Introduction

The configuration framework is designed to administrators and developers decide from where to read a configuration. The purpose of the configuration framework is to have the ability to ask one manager for a property, but to read, if necessary, from multiple sources. Due to its extendable framework it can easily be customized.

The heart of the configuration are the configuration.xml files located in the core and configuration cartridge. These files include the configuration of the configuration engine instance used at ConfigurationMgr.

References

• Cookbook - Configuration

Code Examples

The following examples illustrate the use of the configuration framework. Each access is started at the ConfigurationMgr (which starts a configuration engine and loads the configuration.xml of each cartridge).

Intershop recommends to extract the retrieval of configuration to context-specific configuration classes.

Providing a context-specific configuration interface and implementation has several advantages:

• Better documentation capabilities for the configuration of “getter” methods

• Better testability of business logic using different configuration values (mocking or providing different configurations to the logic)

• Centralized access to the configuration framework (fewer platform dependencies in the business logic)

Access Cluster or Server Configuration

In previous versions, it was helpful to have different configurations on different application servers (e.g., for JobServer). In K8s, all application servers should behave the same. So @ClusterConfiguration is best suited for global or application server configuration.
Intershop recommends providing a default configuration. This will result in a consistent behavior for values that are not configured. Otherwise, null values may be handled differently in different implementation classes.

import com.intershop.beehive.core.capi.configuration.Configuration;
import com.intershop.beehive.core.capi.configuration.ServerConfiguration;
import com.intershop.beehive.core.capi.configuration.ClusterConfiguration;

public class BusinessConfigurationImpl implements BusinessConfiguration
{
    @Inject
    @ClusterConfiguration
    Configuration clusterConfig;
    
    @Inject
    @ServerConfiguration
    Configuration serverConfig;
    
    public boolean isFeatureEabled()
    {
        return serverConfig.getBoolean("config.key.boolean", true);
    }
    public boolean getGlobalMaxSize()
    {
        return clusterConfig.getInteger("config.key.integer", 42);
    }
}

Access Domain-specific Configuration

Business configurations are typically related to an organization, channel, or other context. Domain-specific configuration fits to most of these requirements.

// via domain configuration
public Integer getMaxSize(Domain domain)
{
    return domain.getConfiguration().getInteger("config.key.integer", 24);
}

Access via Static ConfigurationMgr

For the rare cases where injection is not available, the ConfigurationMgr provides a static getInstance() method to provide full access to the configuration framework.

@Inject
ConfigurationMgr configMgr;
# or via static (avoid static class members for assignment)
ConfigurationMgr configMgr = ConfigurationMgr.getInstance();
// get a configuration for scope=instance
Configuration configInstance = configMgr.getInstanceConfiguration();

// get a configuration for scope=cluster
Configuration configCluster = configMgr.getClusterConfiguration();

// full definition of configuration context
Configuration yourConfig = configMgr.getConfiguration(String scope, ConfigurationContext context);

// configuration manager provides more capabilities to define the configuration context
String configDomainString = configMgr.getConfiguration(eTest).getString("config.key.string", "defaultValue");

Access via Object Path in Templates

The object path is often used in templates and queries. It is possible to access the configuration using the object path notation. The domain (#CurrentSite) has a getConfiguration() method, which is used for this example.

<isprint value="#CurrentSite:Configuration:String("<parameter>")#" />
<isprint value="#CurrentSite:Configuration:Integer(<group>.<subgroup>.<parameter-of-subgroup>)#" />

Access by Other Configuration Values

Configuration values can reference other configuration values by key using the ${key} syntax.

For instance:

intershop.jdbc.host=sql-icm-mycompany-prd.database.windows.net
intershop.jdbc.databaseName=icm_live
intershop.jdbc.url=jdbc:sqlserver://${intershop.jdbc.host}:1433;database=${intershop.jdbc.databaseName};

The effective configuration will be:

intershop.jdbc.host=sql-icm-mycompany-prd.database.windows.net
intershop.jdbc.databaseName=icm_live
intershop.jdbc.url=jdbc:sqlserver://sql-icm-mycompany-prd.database.windows.net:1433;database=icm_live;

Priority and Declaration of Properties in configuration.xml

Declaration

Besides the configuration files of the core and configuration cartridge, all cartridges can define their own configuration.xml to extend the lookup and behavior of the configuration framework. The file has a predefined location in the cartridge resource folder /resources/${CartridgeName}/config/configuration.xml. Important declarations take place in the following cartridges:

• configuration: system scopes and finder

• orm: finder declaration to find/declare orm.properties

• core: main declarations of property files, readers, and scopes

• bc_service: service-specific configuration

The file contains any:

• reader - can read a configuration file or resource from URI locations

• finder - provides a lookup in the system to find URIs (which can be read by the “readers”)

• writer - can write adapted configuration to a resource (URI) - the counterpart to the reader

• scope - defines which sets belong together

• set - declares scope/finder/writer combination and represents the loaded properties

<configuration-setup>
  <readers>
    <reader class="..." />
  </readers>
  <finders>
    <finder name="..." class="..." />
  </finders>
  <writers>
    <writer name="..." class="..." />
  </writers>
  <scopes>
    <scope name="..." depends="..." />
  </scopes>
  <sets>
    <set finder="..." scope="..." writer="..." defaultWriter="..." writableKeys="..." />
  </sets>
</configuration-setup>

• The readers section defines the readers to use:

  • class: the class name of the reader; if no class is found, an exception will be thrown

• The finders section defines the finders to use:

  • name: the name by which this finder will be registered

  • class: the class name of the finder to use; if no class is found, an exception will be thrown

• The writers section defines the writers to use:

  • name: the name by which this writer will be registered

  • class: the class name of the writer to use; if no class is found, an exception will be thrown

• The scopes section defines the different scopes for which configurations will be created:

  • name: the name of the scope

  • depends: if a scope depends on the existence of other scopes

• The set section defines the configuration sets that will be found and read:

  • finder: the finder to use to find a URI that a proper reader can read and return a configuration set

  • scope: the comma-separated list of scopes for which this configuration set is intended

  • writer: the name of a writer to use if this set should also be written

  • defaultWriter: used if the writer of this set is the default writer

  • writableKeys: the comma-separated list of keys that the writer can write

  • priority: defines the order of the configuration value lookup across multiple configuration sets (within the same scope). A higher priority means: earlier lookup (overrides lower priority). The default priority is 50.

  • Any other attribute of this tag will be treated as a bean property of the defined finder and a setter method with the given attribute name will be triggered; e.g., <set fileName="..."/> will trigger the setFileName(...) method.

Priority of Configuration Values

Each configuration set has a priority attribute. This priority is used to order the lookup. Sets with higher priority are loaded earlier. As a result of the declaration in the core cartridge, domain specific configuration (preferences) have a higher priority as properties declared in cartridges. That means, domain configuration can override standard values for a specific domain. Cartridge configuration values can override “standard” configurations for all domains.

Scopes

The configuration engine can provide different configurations for different purposes. For this reason, the concept of scopes has been introduced. A scope is a logical structuring of configurations needed for that purpose.

Saying that a scope depends on one or more other scopes means that in order to load configurations for this scope (e.g., instance), you must first load all the configurations that this scope depends on (startup). Since startup uses the system configuration that provides you with all system properties (intershop.HomeDirectory), the instance scope cannot be loaded properly as long as it depends on the values from the startup scope.

The fact that one scope depends on another scope does not automatically mean that when you request a configuration for that scope, you will also have configuration sets of the dependent scopes in it.
That is, if you request a configuration for the scope instance that depends on startup, not every startup configuration set is necessarily included in the instance scope.

The following figure outlines the scopes that are currently in use:

Finders

These are the finders known to the ICM by default:

Details About the system Finder

The system-finder determines the configuration values from three different sources:

1. JVM system properties (the -Dkey=value parameter during JVM startup)

2. (All) system environment variables

3. System environment variables prefixed by ISH_ENV_

The configuration values from these three different sources can overlap/override each other if they contain the same keys. Therefore, the priorities are defined as listed above (higher overrides lower).

JVM System Properties

• The keys are taken as they are, for example, intershop.jdbc.url can be found using the intershop.jdbc.url key.

• Additionally, all values are duplicated under the property-key namespace system, for example, intershop.jdbc.url can also be found using the system.intershop.jdbc.url key.

(All) System Environment Variables

• The keys are translated during lookup as follows:

  • Letters are translated into the upper case.

  • Dots (.) are translated to underscore (_).

  • For example, if an environment variable INTERSHOP_JDBC_URL is defined, it can be found using the intershop.jdbc.url key.

• Additionally, all values are duplicated under the property-key namespace system. For example, INTERSHOP_JDBC_URL can also be found using the system.intershop.jdbc.url key.

Prefixed System Environment Variables

Sometimes the above-mentioned translation results in key collisions because the transaction is nott a 1-to-1-function. For example, intershop.servletEngine.connector.port and intershop.servletengine.connector.port are both translated to INTERSHOP_SERVLETENGINE_CONNECTOR_PORT. Therefore, there is a third variant that provides system environment variables:

• All environment variables prefixed with ISH_ENV_ are picked.

• The value of these environment variables is interpreted as a list of key-value-pairs separated by commas (,).

  • For example, the environment variable ISH_ENV_DATABASE=intershop.jdbc.url=jdbc:sqlserver://myhost:1433;database=icmdb;,intershop.jdbc.user=intershop,intershop.jdbc.password=topsecret provides the following three configuration values:

    • intershop.jdbc.url=jdbc:sqlserver://myhost:1433;database=icmdb;

    • intershop.jdbc.user=intershop

    • intershop.jdbc.password=topsecret

• The prefix ISH_ENV_ can be followed by any string (proposal: use something that matches the semantics of the contained configuration values).

Details about the keyvault Finder

The keyvault-finder determines configuration values of Azure Key Vault. The secrets that will be determined from the Key Vault are referenced by the keys-attribute of the set-declaration:

• e.g: keys=database,mail will result in retrieval of secrets database and mail.

Each secret’s value can have a content type assigned. The following content types are supported:

• application/json: the secret's value is interpreted as a JSON string where the structure is mapped onto property namespaces:

  • For example, the following JSON:

    {
      "intershop" : {
        "jdbc" : {
          "url": "jdbc:sqlserver://myhost:1433;database=icmdb;",
          "user": "intershop",
          "password": "topsecret"
        }
      }
    }

  • is equivalent to:

    intershop.jdbc.url=jdbc:sqlserver://myhost:1433;database=icmdb;
    intershop.jdbc.user=intershop
    intershop.jdbc.password=topsecret

• <none>: the secret’s value is interpreted as a list of properties (separated by line breaks)

If there are conflicts between the property keys of the read secrets, the order within the keys-attribute of the set declaration gets relevant: It defines the priority of the referenced secrets, with leading secrets getting a higher priority than trailing secrets, for example:

• If configured as:

<set finder="keyvault"
			 scope="cluster,server,domain"
             uri="${IS_KEYVAULT_URI}"
             keys="${environment}-${staging.system.type},${environment},global"
             priority="900"
			 enabled="${IS_KEYVAULT_ENABLED}"
			 required="false"/>

intershop.jdbc.url=jdbc:sqlserver://${intershop.jdbc.host}:1433;database=${intershop.jdbc.databaseName};
intershop.jdbc.user=intershop

intershop.jdbc.host=sql-icm-mycompany-prd.database.windows.net

intershop.jdbc.databaseName=icm_live
intershop.jdbc.password=prd_icm_live_pwd

intershop.jdbc.databaseName=icm_edit
intershop.jdbc.password=prd_icm_edit_pwd

intershop.jdbc.host=sql-icm-mycompany-uat.database.windows.net

intershop.jdbc.databaseName=icm_live
intershop.jdbc.password=uat_icm_live_pwd

intershop.jdbc.databaseName=icm_edit
intershop.jdbc.password=uat_icm_edit_pwd

• The effective configuration values will be:

intershop.jdbc.url=jdbc:sqlserver://sql-icm-mycompany-prd.database.windows.net:1433;database=icm_live;
intershop.jdbc.user=intershop
intershop.jdbc.password=prd_icm_live_pwd

intershop.jdbc.url=jdbc:sqlserver://sql-icm-mycompany-prd.database.windows.net:1433;database=icm_edit;
intershop.jdbc.user=intershop
intershop.jdbc.password=prd_icm_edit_pwd

intershop.jdbc.url=jdbc:sqlserver://sql-icm-mycompany-uat.database.windows.net:1433;database=icm_live;
intershop.jdbc.user=intershop
intershop.jdbc.password=uat_icm_live_pwd

intershop.jdbc.url=jdbc:sqlserver://sql-icm-mycompany-uat.database.windows.net:1433;database=icm_edit;
intershop.jdbc.user=intershop
intershop.jdbc.password=uat_icm_edit_pwd

Placeholders in Set Declaration

The configuration set will be configured with a finder and specific attribute values for this finder. Each attribute value can use the placeholder "${key}" to reference an existing property of an upper scope. For example, the sets for domain scope can use "cluster"-scoped configuration values.

The standard configuration.xml contains placeholders for system-specific folders and environments. The way it works, e.g., for environments is shown below:

• The environment is defined in environment.properties (e.g., "environment=PRD"), which is defined in scope "instance" first.

• All "PRD"-specific configurations can be placed in PRD.properties if the configuration.xml contains:

  <set finder="property" scope="cluster,server,domain" fileName="${IS_CLUSTER_CONFIG}/system/config/cluster/${environment}.properties"/>

• The domain-specific configuration is more complex since a regular expression is used to check the matched files (e.g., PRD_uri.properties):

  <set finder="domain-folder" scope="domain" matches="^${environment}_[\w&&[^_]]*$" fileExtensions="properties,xml"/>

• In case domain properties should be environment and staging type dependent (staging.system.type mostly defined at staging.properties), an additional line in the configuration.xml will load such property files (e.g., PRD_editing_uri.properties):

  <set finder="domain-folder" scope="domain" matches="^${environment}_${staging.system.type}_[\w&&[^_]]*$" fileExtensions="properties,xml"/>

• Sets support an attribute priority that is used for sorting (default: 50). This example declares a resource-based property file inside cartridge demo with a high priority:

  <set finder="resource" scope="cluster,server,domain" cartridge="demo" resourceName="config/cluster/demo.properties" priority="100"/>

Reloading

For development purposes, a reloading mechanism of property files has been implemented. It can be enabled by setting intershop.configuration.CheckSource to true. The delay for checking (and necessarily reloading) the property files can be set using intershop.configuration.CheckSourceInterval (which specifies the reloading interval in milliseconds).

Configuration Locations

Who should store configuration values and where?

Configuration of Developer

A developer wants to open up an implementation for configuration values. So the developer has to include a line to get the configuration from the framework.

String value = configurationMgr.getString(key, defaultValue);

Providing a default value in here is the direct and best way to do it, because the code does not depend on any further configuration step.

A developer of an application type can override this defaultValue via a cartridge property file, located in the cartridge source directory resources/resources/<cartridge>/config. These configurations are included in the cartridge configuration finder.

Configuration of Administrator

An administrator can declare configuration values via environment variables.

Configuration of Business User

Business users' configuration values should be stored in the database. There are two ways to do this:

• Application preferences (for functionality and behavior) and

• Domain preferences (for data-related configuration)

The developer of the business management application is responsible for deciding on the correct location of the property.

Developers often define configuration values for different environments and domains. This can be accomplished with a custom configuration.xml declaration that can provide domain and environment-specific configuration values.

Service Configurations

There is another scope called service with finder, reader, and writer. This scope is used for the Managed Service Framework.

The finder creates URIs for the service scope that only the reader can read and only the writer can write to.

The reader creates configuration sets that look at the ServiceConfigurationPOAttributeValuePO table using the ServiceConfigurationPO that must be provided in the context used to retrieve the configuration values from the set.

The writer, on the other hand, writes to the same table, also using the ServiceConfigurationPO provided in the context.

The service scope is sort of a standalone scope. When someone requests configurations from this scope, only one reader is triggered, which returns only one type of configuration set. Currently, this scope does not contain any properties other than properties from the ServiceConfigurationPOAttributeValuePO table. For example, values from the appserver.properties or PreferencePO table are not included. Of course, this can be changed at any time by creating a custom configuration.xml file.