Includes, substitutions and scripted values in the configuration

1 Includes

A JPPF configuration source, whether as a file or as a plugin, can include other configuration sources by adding one or more "#!include" statements in the following format:

#!include source_type source_path

The possible values for source_type are "file", "url" or "class". For each of these values, source_path has a different meaning:

- when source_type is "file", source_path is the path to a file on the file_system or in the JVM's classpath. If the file exists in both classpath and file system, the file system will have priority over the classpath. Relative paths are interpeted as relative to the JVM's current user directory, as determined by System.getProperty("user.dir").

- when source_type is "url", source_path is a URL pointing to a configuration file. It must be a URL such that the JVM can open a stream from it.

- when source_type is "class", source_path is the fully qualified class name of a configuration plugin, i.e. an implementation of either JPPFConfiguration.ConfigurationSource or JPPFConfiguration.ConfigurationSourceReader.

Examples:

# a config file in the file system
#!include file /home/me/jppf/jppf.properties

# a config file in the classpath
#!include file META-INF/jppf.properties

# a config file obtained from a url
#!include url http://www.myhost.com/jppf/jppf.properties

# configuration obtained from a configuration plugin
#!include class myPackage.MyConfigurationSourceReader

Includes can be nested without any limit on the nesting level. Thus, you need to be careful not to introduce cycles in your includes. If that happens, JPPF will catch the resulting StackOverflowException and display an error message in the console output and in the log.

2 Substitutions in the values of properties

The JPPF configuration can handle a syntax of the form "propertyName = prefix${otherPropertyName}suffix", where prefix and suffix are arbitrary strings and ${otherPropertyName} is a placeholder referencing another property, whose value will be substituted to the placeholder. If you have experience with Apache Ant, this syntax is very similar to the way Ant properties are used in a build script.

Let's take an example illustrating how this works. The following property definitions:

prop.1 = value1
prop.2 = ${prop.1}
prop.3 = value3 ${prop.2}
prop.4 = value4 ${prop.2} + ${prop.3}

will be resolved into:

prop.1 = value1
prop.2 = value1
prop.3 = value3 value1
prop.4 = value4 value1 + value3 value1

Note 1: the order in which the properties are defined has no impact on the resolution of substitutions.

Note 2: substitutions are resolved after all includes are fully resolved and loaded.

Unresolved substitutions

A referenced property is unresolvable if, and only if, it refers to a property that is not defined or it is involved in a resolution cycle. In this case, the value of the unresolved value will be the literal syntax in its initial definition, that is in the literal form "${otherPropertyName}". Let's illustrate this with examples.

In the following configuration:

prop.1 = ${prop.2}

the value of "prop.1" will remain "${prop.2}", since the property "prop.2" is not defined.

In this configuration:

prop.1 = ${prop.2}
prop.2 = ${prop.3} ${prop.1}
prop.3 = value3

"prop.1" and "prop.2" introduce an unresolvable cycle, and only the reference to "prop.3" can be fully resolved. According to this, the final values will be:

prop.1 = ${prop.2}
prop.2 = value3 ${prop.1}
prop.3 = value3

Environment variable substitutions

Any reference to a property name in the form "env.variableName" will be substituted with the value of the environment variable whose name is "variableName". For example, if the environment variable JAVA_HOME is defined as "/opt/java/jdk1.7.0", then the following configuration:

prop.1 = ${env.JAVA_HOME}/bin/java

will be resolved into:

prop.1 = /opt/java/jdk1.7.0/bin/java

If the value of a property refers to an undefined environment variable, then the reference will be replaced with an empty string.

3 Scripted property values

The values of configuration properties can be partially or complety computed as expressions written in any JSR 223-compliant dynamic script language. Such properties contain one or more expressions of the form:

my.property = $script:language:source_type{script_source}$

Where:

• language is the script language to use, such as provided by the javax.script APIs. It defaults to "javascript"
• source_type determines how to find the script, with possible values "inline", "file" or "url". It defaults to "inline"
• script_source is either the script expression, or its location, depending on the value of source_type:
  • if source_type = inline, then script_source is the script itself.
    For example: my.prop = $script:javascript:inline{"hello" + "world"}$
  • if source_type = file, then script_source is a script file, looked up first in the file system, then in the classpath.
    For example: my.prop = $script:javascript:file{/home/me/myscript.js}$
  • if source_type = url, then script_source is a script loaded from a URL.
    For example: my.prop = $script:javascript:url{file:///home/me/myscript.js}$

If the language or source type are left unspecified, they will be assigned their default value. For instance the following patterns will all resolve in language = 'javascript' and source_type = 'inline' :

$script{ 2 + 3 }$
$script:{ 2 + 3 }$
$script::{ 2 + 3 }$
$script::inline{ 2 + 3 }$
$script:javascript{ 2 + 3 }$
$script:javascript:{ 2 + 3 }$

The default script language can be specified with the property 'jppf.script.default.language'. This property is always evaluated first, in case it is also expressed with script expressions. If it is not specified explicitely, it will default to 'javascript'. For example, in the following:

# using javascript expression to set the default language to groovy
jppf.script.default.language = $script{ 'groo' + 'vy' }$
# inline expression using default language 'groovy'
my.property = $script{ return 2 + 3 }$

The value of 'my.property' will evaluate to 5, resulting from the inline groovy expression 'return 2 + 3'.

The scripts are evaluated after all includes and variable substitutions have been resolved. This will allow the scripts to use a variable binding for the Properties (or TypedProperties object) being loaded. For example, in the following:

prop.1 = hello world
prop.2 = $script:javascript{ thisProperties.getString('prop.1') + ' of scripting' }$

the value of 'prop.2' will evaluate to 'hello world of scripting', which is the value of 'prop.1' to which another string is concatenated. The predefined variable thisProperty is bound to the properties object being evaluated. Note that the same result can be achieved with a property substitution:

prop.1 = hello world
prop.2 = $script:javascript{ '${prop.1}' + ' of scripting' }$

Here, the substitution of ${prop.1} is performed before the script evaluation, and must be enclosed within quotes to be parsed as a string literal inside the script.

Finally, property values can contain any number of script expressions, which can be written in different script languages and loaded from different sources. For example, the value of the following property:

prop.1 = hello $script:javascript{'my ' + 'world'}$ number $script:groovy{return 2 + 3}$

will evaluate to 'hello my world number 5'.