...

There are 7 main elements in a DDL configuration model file:

• <systemDetails>: Defines  Defines system metadata that is used by tools and emitted by an XVM in XVM in heartbeats. 
• <env>: Defines environment variables that can be used for substitution of values in the document and are exposed to the application and talon runtimes.
• <busProviders>: Defines custom message bus provider implementations.
• <buses>: Defines the message buses that are used for applications to communicate with one another.
• <apps>: Defines and configures the applications that make up the system. 
• <xvms>: Defines the XVMXVMs (Talon lightweight containers) that host one or more applications. 
• <profiles>: Defines profiles that can be dynamically activated to localize the configuration for different operating environments.

A main tenant of the X Platform is to separate out (and shield) an application's business logic from the complex machinery underpinning high availability, performance, and scalability. As such there are is a wealth of tuning knobs and configuration operations that can be applied without making application code changes. Most applications will not use the majority of the settings described here unless they are being tuned for special cases. 

...

A JVM configured using DDL xml XML is configured using the VMConfigurer class which accepts the XML either as a file or input stream. The VMConfigurer  parss parses the XML and seeds the configuration repository that will subsequently be used to configure components as they are loaded. For application portability, It is often convenient to define some value in the DDL as variables that are later localized to the environment in where which an application is to run. 

The values in an a DDL XML document can be overridden in two ways: environment variable substitution and via DDL Override Properties. In both cases, the source of properties for substitution are is provided to the parser passed to the VMConfigurer.  When running in Non-Embedded mode, the substitution values provided by the Talon XVM to the  VMConfigurer are sourced from the following sources (in increasing order of precedence)

...

When running in embedded mode or with a bootstrap configurer, the application provides the substitution value resolver to the  VMConfigurer  directly directly via API, giving the application full control of the property source. In this case, the application may provide VMConfigurer with the platform's environment value substitution resolver by passing in UtlTailoring.ENV_SUBSTITUTION_RESOLVER as the valueResolver. 

...

If the substitution resolver contains a value for FRONTOFFICE_BUSDESCRIPTOR, then that will be used for the bus descriptor. Otherwise, the default value of "falcon://fastmachine:8040" will be used. This substitution is done before the xml XML is validated, so in cases where the ${} syntax yields invalid xmlXML, it will be substituted before parsing the document. 

...

Properties defined in the <env> section of an X-DDL document have the lowest priority of all configuration sources and can be easily overridden using system properties and environment vars. Properties values defined in the <env> section may use ${} variables, but variable values are only resolved from the property source passed in, not other properties defined in the <env> section. If a value defined in an <env> section was already defined in the property source passed in to into VMConfigurer, that <env> value is replaced (overridden by) the value passsed passed in. 

XVM Specific Env Properties

...

The 3.8 release introduced the ability to configure xvm configure XVM specific <env> properties. When DDL is being localized for a specific XVM, properties defined for an XVM are included and override <env> properties defined in the top-level portion of the DDL when parsing the environment variables. An xvm template An XVM template may also provide <env> properties. Template provided properties are merged with those defined in the <xvm> with the <xvm> values overriding any values defined in the template.

The target xvm target XVM used to localize configuration can be passed to the VMConfigurer using VMConfigurer by passing value nv.ddl.targetxvm=<xvm-name> as value resolver property. This property is automatically set by an XVM prior to invoking the VMConfigurer, but applications running in an embedded mode or using a bootstrap configurer must set this value manually for the environment to be available for ${} substitution. 

<model>
  <env>
    <prop1>top-level-value1</prop1>
    <prop2>top-level-value2</prop2>
    <prop3>top-level-value3</prop3>
  </env>
 
  <xvms>
    <templates>
      <xvm name="xvm-template">
        <env>
          <prop2>xvm-template-value2</prop2>
    	  <prop3>xvm-template-value3</prop3>
        </env>
      </xvm>
    </templates>
    <xvm name="my-xvm" template="xvm-template">
      <env>
    	<prop3>my-xvm-value3</prop3>
      </env>
    </xvm>
  </xvms>
</model>

would resolve to an xvm specific XVM specific env of:

• prop1=top-level-value1 (as defined in top-level env since not overridden).
• prop2=xvm-template-value2 (picked up from xvm-template to override top-level <env>).
• prop3=my-xvm-value3 (picked up from my-xvm, overrides the template and top-level value).

Note that if any of the above properties were specifed specified in the environment passed in (e.g System.getenv or System.getProperty) the values passed in would take precedence. 

...

Any attribute or value element listed in this document that has an X an X DDL Override property  Override property can be overridden by passing the the corresponding  value value into the substitution environment used by the VMConfigurer. DDL overrides are particularly useful for applications that internally bundle ddl DDL on the classpath, making it difficult to edit by hand at runtime. 

...

... even though initial env substitution would substitute "falcon://slowmachine:8040", and the ddl DDL override would override that value with direct://frontoffice resulting in the bus being localized as a direct bus. 

<persister enabled="${FORWARDER_PERSISTER_ENABLED::true}">
  ...
</persister>

-DFORWARDER_PERSISTER_ENABLED=false

...

The buses, apps, and xvms each support specifying templates. Templates allow common configuration elements to specified in a singel single place to reduce repetition in the configuration. For example, if all applications defined in a system will be configured to collect statistics putting this configuration in a template is more compact than specifying the configuration in each application.

...

• Templates are defined under the <templates> element of the section to which they apply (buses, apps, xvms)
• The <templates> element can specify the same configuration as the element for to which they apply (bus, app or xvm)
• You can define multiple templates, but each bus, app, xvm can only specify a single template.
• When the DDL is parsed each element in the template is applied to the element using the template unless the element on the template overrides the same element or template in its configuration. 
• DDL template values can be overridden with DDL overrides. For example, 'x.buses.templates.orders-bus-template.desriptor descriptor' can be used to override the descriptor attribute defined in the 'orders-bus-template' bus template.

...

DDL profiles provide a means of making a single DDL configuration document more portable to different environments, by allowing the specification of profiles that can be activated to augment and override the structure of the DDL.

Some good usecase use cases for profiles include:

• Localizing the system to a specif specific environment by overriding ports, paths and hostnames to the target environment.
• Creating a test profile to be used when unit testing an application. 

Each profile defined in an inan DDL document, can specify all of the elements that can be specified in the DDL model. When a profile is activated all of the configuration it specifies is overlayed on top of the main DDL configuration. Values that already exist in the main DDL are overriden - for example exampl,e if an <app> is defined in the DDL document and an <app> with the same name attribute is defined in a profile, then all of the elements and attributes in the profile are applied on top ot the <app> defined at the top level. 

...

A profile can specify an <activation> element that can accept a list of properties that must match values in the bootstrap environment to be activated. This can be useful to localize an application based on the environment it is running in. For example exampl,e the following profile could be automatically activated to set the discovery address to use when running in the prod environment based on the environment variable ENVIRONMENT_NAME=PROD being set in that environment. 

...