Using variables in configuration files

You can use variables in the configuration to avoid hardcoding values that might not be appropriate when the configuration is reused in different environments.

• Specify a variable in a configuration file.

  The variable definition syntax is variable_name=value. If the value contains a path, it is normalized during configuration processing by replacing repeated forward and backward slashes with a single forward slash, unless the value starts with double forward or backward slashes, which remain unchanged.

  Best practice: If you need to set the value of a variable to contain repeated forward slashes, as are sometimes used for JDBC driver connection URLs, break the value into two parts at the double slashes. By placing the double forward slashes as the initial characters, normalization is avoided. For example, to store the value "jdbc:db2://host_name.com", use two variables:

  URL_PART_1="jdbc:db2:"
  URL_PART_2="//host_name.com"

  Variables that are defined in the configuration files are scoped to the configuration elements by which they are used. For example, the following code fragment creates a variable that is called updateTrigger_var to be used in applicationMonitor configuration elements:

  <applicationMonitor updateTrigger_var="mbean" />

  To create a variable that is used in a particular configuration instance (such as an application or resource entry), you must also specify the instance identifier. For example:

  <httpEndpoint id="defaultHttpEndpoint" HTTP_default_var="8889" />

• Specify a variable in the bootstrap.properties file.
  Variables that are defined in the bootstrap.properties file are not scoped to particular configuration elements. You enter the variables as key-value pairs. For example:

  HTTP_default_var=8006

• Use a defined variable in the configuration.
  The variable substitution syntax is ${variable_name}. Multiple variable values can be concatenated by specifying ${variable_name1}${variable_name2}. For example, to use the HTTP_default_var variable, add the following code fragment to the configuration file:

  <httpEndpoint id="defaultHttpEndpoint"
  httpPort="${HTTP_default_var}">
  </httpEndpoint>

• Use variable element in the configuration.
  You can use the variable element to define a variable globally in the server configuration. If the same variable is defined in an included file, it is overridden by the one in the server.xml file. For example, to use the variable element, add the following code fragment to the configuration file:

  <variable name="HTTP_default_var" value="8889" />

• Use process environment variables in the configuration.

  Process environment variables are available if you use the env. configuration variable prefix, for example:

  <fileset dir="${env.LIBRARY_DIR}" includes="*.jar"/>

  For more information on specifying environment variables, see Customizing the Liberty environment.

• Use list variables in the configuration.
  Normally variables cannot express a comma-separated list of values for use in a multi-valued configuration attribute. Variables that contain commas are interpreted as a single String rather than multiple values. It is possible to interpret a variable as a comma-separated list of values by specifying the variable name with ${list(...)}. For example:

  <variable name="ports" value="80,9080"/>
  

  ${ports} is interpreted as the string "80, 9080".

  ${list(ports)} is interpreted as a collection containing the strings "80" and "9080".

• Use variable expressions in configuration.
  For configuration variables, you can use a limited variable expression syntax with the format ${<operand><operator><operand>}. The description of the variable is as follows:

  operand

  Operands can either be long integer literals or the name of a variable that contains a long integer value. Variable names must begin with an alphabetic character, and must contain the following characters only: alphabetic characters, numeric characters, and the "_" and "." characters.

  operator

  The available operators are as follows:

  • + for addition
  • - for subtraction
  • * for multiplication
  • / for division

  If the expression cannot be parsed, a non-integer value is used, or an arithmetic error occurs, then the behavior is undefined.

  For example, if the HTTP_port_base variable is defined, a variable expression might be used to define multiple httpEndpoints:

  <httpEndpoint id="defaultHttpEndpoint" httpPort="${HTTP_port_base+0}"/>
  <httpEndpoint id="httpEndpoint2" httpPort="${HTTP_port_base+1}"/>

• Override inheritable attributes in the configuration.

  You can override the default values of inheritable attributes in the configuration. The inheritable attributes are listed on the Liberty features page. You can identify the elements with the inherited attributes by looking for Inherits type. For example, the onError attribute is one of inheritable attributes. You can define a variable name for the onError attribute globally by either setting it in the bootstrap.properties or server.xml file with a variable element. If the same variable name is specified in both files, the value in the server.xml file is used. If the attribute is not explicitly set in either of two files, it uses the default value. If an invalid value is set to the inheritable attribute, the attribute value falls back to the global value defined in bootstrap.properties or server.xml file or the default value if not defined at the global level.

  Another example is logging properties in Liberty.