Overview

DollarBrace library provides a mechanisms to filter strings, files and XML trees to perform property resolution for a common dollar-brace expressions. For instance, given document

<name>${name}</name>

and properties file

name=Stephan

The filtering result will be

<name>Stephan</name>

Changes

2.0 (2015-07-17) Change name to DollarBrace Better error reporting for recursive property resolution

1.3 (2014-11-30) fix: PropertyFilter returned from getFilter was not thread-safe

1.2 (2014-04-06) Added file filtering

1.1 (2014-03-12) fix: incorrectly returning circular dependencies for missing properties

1.0 (2014-02-13) Splitted from evo-config Separated filtering (PropertyFilter) from property resolution (PropertyResolver)

Usage

First add the following dependency to your POM file:

<dependency>
    <groupId>org.atteo.dollarbrace</groupId>
    <artifactId>dollarbrace</artifactId>
    <version>2.0</version>
</dependency>

Then create a property resolver instance:

Properties properties = new Properties();
properties.putProperty("name", "Stephan");
PropertyResolver propertyResolver = new PropertiesPropertyResolver(properties);

Finally create a property filter and use it to interpolate dollar-brace expression within a string:

PropertyFilter propertyFilter = DollarBrace.getFilter(propertyResolver);

// will print 'His name is Stephan'
System.out.println(propertyFilter.filter("His name is ${name}"));

Property filter

DollarBrace.getFilter(...) returns a PropertyFilter instance. It contains several methods which allow you to interpolate dollar-brace expressions:

• filter(String) - filters given string interpolating dollar-brace expressions inside
• filter(Element) - filters given XML subtree interpolating tag content and attribute values
• filter(Path source, Path destination) - filters source file and stores the result in the destination file
• getProperty(String) - returns the value of the given property

Property resolvers

DollarBrace.getFilter(resolver1, resolver2, ...) method takes a number of property resolvers. Each resolver will be tried in turn to get the values for dollar-brace expressions.

There are several PropertyResolvers already available for your convenience:

EnvironmentPropertyResolver

Resolves ${env.NAME} with the value of environment variable named NAME.

SystemPropertyResolver

Resolves ${NAME} from the Java system property provided with -DNAME="value"

PropertiesPropertyResolver

Resolves property from the provided Properties object.

XmlPropertyResolver

Takes XML DOM tree as an input and resolves any ${tag.tag.tag} as a dot-separated path to the XML element. For instance, given document:

<a>
	<b>test</b>
</a>

"${a.b}" will resolve to "test".

OneOfPropertyResolver

Matches any name prefixed with 'oneof:' and formatted as comma separated list of values - 'oneof:value1,value2,value3'. It returns first of the values which is correctly defined.

For instance

'${oneof:${env.HOME},~/}'

will return the value of the environment variable 'HOME' or '~/' if the 'HOME' variable is undefined

RawPropertyResolver

Matches any name prefixed with 'raw:' and returns the same string without 'raw:' prefix. This is handy in case some special characters would otherwise trigger recursive filtering.

For instance

'${raw:${a}}'

will return exactly '${a}' (without trying to resolve dollar brace inside it).

JaninoPropertyResolver

Matches any name prefixed with 'java:'. It treats the following string as Java expression which is executed to obtain the value.

For instance '${java:2+2}'

will return '4' and

'${java:new java.util.Date()'}

will return current date and time.

If the returned Java object is not a String type, 'toString()' method is automatically executed.

To use this resolver you need to add additional Maven dependency:

<dependency>
    <groupId>org.atteo.dollarbrace</groupId>
    <artifactId>janino</artifactId>
    <version>1.3</version>
</dependency>

Custom property resolver

Basics

You can easily prepare your own property resolvers by implementing PropertyResolver interface.

public interface PropertyResolver {
	String resolveProperty(String name, PropertyFilter filter) throws PropertyNotFoundException;
}

For instance here is the resolver which matches on a "date" string and always returns current date and time:

public class DatePropertyResolver implements PropertyResolver {
	String resolveProperty(String name, PropertyFilter filter) throws PropertyNotFoundException() {
		if ("date".equals(name)) {
			return new Date().toString();
		}
		throw new PropertyNotFoundException(name);
	}
}

Recursive resolution

PropertyResolvers can support recursive resolution. That is one dollar-brace expression can be itself built using several other dollar-brace expressions like this:

properties.putProperty("name1", "John");
properties.putProperty("number", "1");
PropertyFilter propertyFilter = DollarBrace.getFilter(new PropertiesPropertyResolver(properties));

System.out.println(propertyFilter.filter("My name is ${name${number}}"));

To support recursive resolution your custom property resolver must execute extra step to filter property name using the provided PropertyFilter. Here is the example:

public class DatePropertyResolver implements PropertyResolver {
	String resolveProperty(String name, PropertyFilter filter) throws PropertyNotFoundException() {
		// filter the name to support recursive resolution
		name = filter.filter(name);

		if ("date".equals(name)) {
			return new Date().toString();
		}
		throw new PropertyNotFoundException(name);
	}
}