Applications typically include some sort of configuration data that might change depending on the environment in which the application is deployed. For example, if an application connects to a database server using JDBC, the configuration data would include the JDBC URL of the database server, the JDBC drvier, and the username and password that the application uses to connect to the database server. This information often changes as the application is deployed to different computers or the application moves from the testing phase to the production phase.

SpringSource dm Server provides a feature called configuration artifacts that makes it very easy for you to manage this configuration data. A configuration artifact is simply a properties file that is made available at runtime using the OSGi ConfigurationAdmin service. When you create this properties file, you set the values of the properties for the specific environment in which you are going to deploy your application, and then update the metadata of your Spring application to use the properties file. You then deploy the application and properties file together, typically as a plan. SpringSource dm Server automatically creates a configuration artifact from the properties file, and you can manage the lifecycle of this configuration artifact in the same way you manage the lifecycle of PARs, bundles, and plans, using both the dm Shell and Admin Console. Additionally, dm Server subscribes your application for notification of any refresh of the configuration artifact and the application can then adapt accordingly, which means you can easily change the configuration of your application without redeploying it.

In sum, configuration artifacts, especially when combined with plans, provide an excellent mechanism for managing external configuration data for your applications.

The following sections describe the format of the configuration artifact, how to update the Spring application context file of your application so that it knows about the configuration artifact, and finally how to include it in a plan alongside your application.

As an example to illustrate the configuration artifact feature, assume that you have a Spring bean called PropertiesController whose constructor requires that four property values be passed to it, as shown in the following snippet of Java code:

@Controller
public class PropertiesController {

    private final String driverClassName;
    private final String url;
    private final String username;
    private final String password;

    public PropertiesController(String driverClassName, String url, String username, String password) {
        this.driverClassName = driverClassName;
        this.url = url;
        this.username = username;
        this.password = password;
}

In the preceding example, the PropertiesController constructor requires four property values: driverClassName, url, username, and password. Note that the example shows just one way that a class might require property values; your application may code it another way.

Additionally, assume that the following snippet of the associated Spring application context XML file shows how the PropertiesController bean is configured:

<bean class="com.springsource.configuration.properties.PropertiesController">
                <constructor-arg value="${driverClassName}"/>
                <constructor-arg value="${url}"/>
                <constructor-arg value="${username}"/>
                <constructor-arg value="${password}"/>
</bean>

The rest of this section describes how the bean can get these property values using a configuration artifact.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:context="http://www.springframework.org/schema/context"
  xmlns:osgi-compendium="http://www.springframework.org/schema/osgi-compendium"
  xsi:schemaLocation="http://www.springframework.org/schema/osgi 
    http://www.springframework.org/schema/osgi/spring-osgi-1.2.xsd
    http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
    http://www.springframework.org/schema/context 
    http://www.springframework.org/schema/context/spring-context-2.5.xsd
    http://www.springframework.org/schema/osgi-compendium 
    http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium-1.2.xsd">

...

        <bean class="com.springsource.configuration.properties.PropertiesController">
                <constructor-arg value="${driverClassName}"/>
                <constructor-arg value="${url}"/>
                <constructor-arg value="${username}"/>
                <constructor-arg value="${password}"/>
        </bean>

        <context:property-placeholder properties-ref="configAdminProperties"/>

        <osgi-compendium:cm-properties id="configAdminProperties" persistent-id="app-properties"/>

...

</beans> 

The preceding example shows how the id configAdminProperites wires the <context:property-placeholder> and <osgi-compendium:cm-properties> elements together. Based on the value of the persistent-id attribute, you must also deploy a properties file called app-properties.properties which dm Server installs as a configuration artifact.

<?xml version="1.0" encoding="UTF-8"?>
<plan name="multi-artifact.plan" version="1.0.0" 
         scoped="false" atomic="false"
        xmlns="http://www.springsource.org/schema/dm-server/plan"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="
            http://www.springsource.org/schema/dm-server/plan
            http://www.springsource.org/schema/dm-server/plan/springsource-dm-server-plan.xsd">

    <artifact type="configuration" name="app-properties" version="0"/>
    <artifact type="bundle" name="com.springsource.configuration.properties" version="1.0.0"/>
</plan>