de.smartics.properties.tutorial.config.key
Class ConfigurationKeyTutorial

java.lang.Object
  de.smartics.properties.tutorial.config.key.ConfigurationKeyTutorial

@Document(title="Providing Configuration Keys",
          sortKey="basics1000")
@DocCategory(value="basics")
public class ConfigurationKeyTutorial
     
     

      
      extends 
      
      Object
     
     

This tutorial shows how configuration keys can be provided at runtime.

Constructor Summary

ConfigurationKeyTutorial()

Method Summary

void	accessConfigurationByHardcodedKey() The configuration is created by a ConfigurationPropertiesFactory that is configured via the service API.
void	determineSystemIdAutomatically() Hardcoding the key is usually not what you want.
void	specifyEnvironmentNameAndNodePerSystemProperty() You may also provide the name of the environment and the node within this environment via system properties.
void	specifyEnvironmentNameProgramatically() If you determine the name and node of the environment by other means, you may still use the automatic determination of the application.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConfigurationKeyTutorial

public ConfigurationKeyTutorial()

Method Detail

accessConfigurationByHardcodedKey

@DocChapter
public void accessConfigurationByHardcodedKey()

The configuration is created by a ConfigurationPropertiesFactory that is configured via the service API. Therefore there is a file named

 META - INF / services
     / de.smartics.properties.api.config.app.ConfigurationPropertiesFactory
 

that contains the following information

 de.smartics.properties.impl.config.properties.PropertiesConfigurationPropertiesFactory
 

This example assumes that there are a couple of modules declared as dependencies. For the sake of simplicity we omit the version numbers.

     
     
     
       
      
      
       
       de.smartics.sandbox
      
      
       
      
      
       
       test-module-mail
      
      
     
     
     
     
     
     
       
      
      
       
       de.smartics.sandbox
      
      
       
      
      
       
       test-module-announce
      
      
     
     
     
     
     
     
       
      
      
       
       de.smartics.sandbox
      
      
       
      
      
       
       test-module-agile
      
      
     
     
     
 

Each of these modules can be configured via properties files. The definition for these properties is provided by a dependency like this:

     
     
     
       
      
      
       
       de.smartics.sandbox
      
      
       
      
      
       
       test-application-config
      
      
     
     
     
 

In real systems this dependency may be provided by a deployment process or a build process that bundles the dependency within a deploy- or installable unit. It is required to have this information accessible at runtime.

Now let's have a look how we can access information.

In this default factory is created.

To get access to the configuration provided for a specific environment, a configuration key has to be constructed. In its simplest form this is done by hand as shown in . Note that the configuration key is constructed of two main parts:

1. environment ID - which contains the name of the environment ( test in our example) and an optional node information ( null in our example).
2. application ID - which contains a group name, an artifact name and a version information. This uniquely identifies the application that uses a configuration for its modules.

The key specified in matches the key defined in the definition.xml of artifact test-application-config (referenced in the dependency block above).

With this configuration key we are able to access the configuration as shown in . The property set MailProperties is part of the module test-module-mail. As you may already know we simply access the property set by retrieving it from the configuration by its type name as shown in .

In and we only show that the mails-per-page property value is indeed accessible and shows the expected value.

determineSystemIdAutomatically

@DocChapter
public void determineSystemIdAutomatically()

Hardcoding the key is usually not what you want. You may either retrieve the identity of the system by other means from the environment or let smartics-configuration determine it for you.

In we instantiate the key helper and then load in the relevant information from the environment by using a locator () which is simply a class loaded from the class path of the application. This will access the meta information of the application found in META-INF/MANIFEST.MF. The environment part is determined by this formula:

1. Check if the system property is set. If it is, use it and quit. If not proceed with the next step 3.
2. Use development as environment.
3. After the environment name is determined, the node name is calculated: Either the system property is specified or the canonical host name is derived.
4. Now calculate the application information by reading the following information from the manifest file.
   1. Group:
   2. Artifact:
   3. Version:

If the manifest file is missing, an IllegalStateException is thrown.

specifyEnvironmentNameProgramatically

@DocSection
public void specifyEnvironmentNameProgramatically()

If you determine the name and node of the environment by other means, you may still use the automatic determination of the application.

specifyEnvironmentNameAndNodePerSystemProperty

@DocSection
public void specifyEnvironmentNameAndNodePerSystemProperty()

You may also provide the name of the environment and the node within this environment via system properties.

In we set the system programatically. Usually this will be set on the command line via -D. In we do not pass in an environment, since it is already set. This makes it easy to have the fall back option if no system property is set (as we have seen above, the defaults will be returned in that case). In we see that the expected values are retrieved.