Descriptor property substitution in EAP6 and JBoss AS7


In a software development process, there are usually multiple environments, such as development, test and production, etc. The development team usually provides the QA users a test version before acceptance and production, as illustrated below.
deployment chain in development
If, however, the application contains assumptions about the environment, this chain is broken. Therefore it is good practice, for the deployment to make no assumptions about the target environment. A good way to achieve this is that the application servers provide the environment specific configurations of the application, such as datasource configuration or integration of other Enterprise Information Systems (EIS). But this is often not so easy.

An Example

Let us assume that our application contains a message driven bean that subscribes an external destination of a message broker. A typical configuration of the bean in AS7 might look like this:

@MessageDriven(activationConfig = {
  @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
  @ActivationConfigProperty(propertyName = "destination", propertyValue = "jms/queue/test"),
  @ActivationConfigProperty(propertyName = "connectorClassName", propertyValue = "org.hornetq.core.remoting.impl.netty.NettyConnectorFactory"),
  @ActivationConfigProperty(propertyName = "connectionParameters", propertyValue = "host=;port=5445"),
  @ActivationConfigProperty(propertyName = "user", propertyValue = "admin"),
  @ActivationConfigProperty(propertyName = "password", propertyValue = "secret") })
public class ExampleQueueMDB implements MessageListener {

	public void onMessage(Message message) { ... }


It is necessary to configure the connection parameter, such as the host name and the respective port. The Java EE specification does not contain any standard way to externalize this kind of configuration.

Externalize configuration with property substitution in EAP6 / AS7

The EAP6 and the community version, JBoss AS 7.1.2, allow the replacement of descriptor properties. In our example, the message driven bean can also be configured with a deployment descriptor instead of annotations. Now, configurations such as the host name can be replaced with system properties, as shown in the following listing:

<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar version="3.0" xmlns=""


            <activation-config-property-value> ${jms.connection.parameters:'host=localhost;port=5445'}</activation-config-property-value>




These properties are replaced at deployment time, if it is enabled on the server. This can be done in the EE subsystem of the AS7 in the standalone.xml or domain.xml configuration file by the follwing configuration:

<subsystem xmlns="urn:jboss:domain:ee:1.1">

Setting the spec-descriptor-property-replacement to the value true enables the substitution of the following Java EE descriptors:

  • ejb-jar.xml
  • persistence.xml

Subsitution of Java EE descriptors is disabled by default.

The jboss-descriptor-property-replacement configuration allows substitution of properties in the following JBoss-specific descriptors:

  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml

The default configuration of the JBoss-specific descriptor property replacement is true.

The values can be provided at server startup as follows:

./ -DconnectionParameters='host=;port=5445' -Dapplication.user=test –Dapplication.password=secret


This feature of the EAP6 and the community version allows the configuration of deployments by the server at deployment time with system properties. The deployment of a particular version is thus idempotent. It is no longer necessary to replace properties via the build system with different profiles and maintain different artefacts for various environments. But, the drawback is that the properties are system wide and not limited to the scope of the corresponding component.

3 thoughts on “Descriptor property substitution in EAP6 and JBoss AS7

  1. You can also use regular properties files, that you can then pass to the startup Script ( with the -P Option. You can also pass it multiple times, which means you can structure/group the properties logically and let developers add their properties for dev, which you can then alter for QA or Prod Environments. For Domain Mode, you can define global and host properties as well.

  2. Just to make clear because it is not explicitly mentioned above:

    The examples show how to define default values using the expression language:


    Here, “admin” is the default value, in case the property is not passed via command line, etc.

  3. Hi , Thank you for this information, I recently have seen a similar issue during our migration form Jboss4 to jboss 5.x. if anyone looking for the same feature ( Descriptor property substitution ) in EAP 5 version , you can do the following recomendation• Defining the SystemProperitesService MBean in a -service.xml deployed in the /server//deployers directory. This will load the properties first in the JVM.

Comments are closed.