Use variables in configuration files

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

Variables can be defined by setting a property in any of the following places:

  • server.xml or an included file
  • bootstrap.properties

The following predefined variables can be referenced:

If the same variable is specified in multiple places, the precedence is as follows:

  • variables in bootstrap.properties override the process environment variables
  • variables in server.xml, or included XML files, override the variables in bootstrap.properties and process environment variables

Variable names must begin with an alphabetic character, and must contain the following characters only: alphabetic characters, numeric characters, and the "_" and "." characters.

Best practice: Variables specific to a particular server, for example port numbers, are specified in the bootstrap.properties file, allowing the server.xml to be shared across multiple servers while we keep those values different in each server. Variables shared across a group of servers, for example database configuration for a particular host, is better specified in an xml file included into the parent configuration file.

  • Specify a variable in a configuration file.

    The variable definition syntax is variable_name=value. Variables are scoped to the configuration elements in which they are used. For example, the following code fragment creates a variable called updateTrigger_var to be used in applicationMonitor configuration elements:

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

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

    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.

    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"

  • Specify a variable in the bootstrap.properties file.

    Variables defined in the bootstrap.properties file are not scoped to particular configuration elements. We 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.

    We 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 server.xml. For example: 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 we use the env. configuration variable prefix, for example:

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

  • 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, we can use a limited variable expression syntax with the format...

      ${<operand><operator><operand>}

    ...where...

      operand Operands can either be long integer literals or the name of a variable containing 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 Available operators:

      • + 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.

    We can override the default values of inheritable attributes in the configuration. The inheritable attributes are listed on the Liberty features page. We can identify the elements with the inherited attributes by looking for Inherits type. For example, the onError attribute is one of inheritable attributes. We 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 server.xml 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.


Parent topic: Use include elements, variables, and Ref tags in configuration files