[wildfly-dev] The final (?) property expression expander

[David M. Lloyd]

The basic problem is that we have a variety of client libraries that 
need property expansion, which are rolling their own or not doing it at 
all at present.  We have a couple implementations of property expansion 
on the server.  We have some potential future property expansion 
requirements.  Some or all of these things do (or need to do) property 
expansion slightly differently.  We've been balling up and depositing 
the same properties code over and over again, evolving it slightly each 
time, which in turn makes it harder to adapt to the next use case.  So, 
it's time to stop the madness.

In wildfly-common I'm introducing a new properties expander, implemented 
as a pure recursive-descent parser instead of the previous NFA-ish 
parser.  It is divided into two parts: syntax and expansion.

Syntax is handled by the expression compiler, whose API consists of a 
static factory method that accepts a pattern string and syntax flags, 
and returns the resultant Expression.

The syntax flags currently allow for the following syntax behaviors:

• NO_TRIM: Do not trim leading and trailing whitespace off of the 
expression string before parsing it.
• LENIENT_SYNTAX: Ignore syntax problems whenever possible instead of 
throwing an exception.
• MINI_EXPRS: Support single-character expressions that can be 
interpreted without wrapping in curly braces.
• NO_RECURSE_KEY: Do not support recursive expression expansion in the 
key part of the expression.
• NO_RECURSE_DEFAULT: Do not support recursion in default values.
• NO_SMART_BRACES: Do not support smart braces (this is where you have 
{something} inside of a key or default value).
• GENERAL_EXPANSION: Support Policy file style "general" expansion 
alternate expression syntax.  "Smart" braces will only work if the 
opening brace is not the first character in the expression key.
• ESCAPES: Support standard Java escape sequences in plain text and 
default value fields, which begin with a backslash character.
• DOUBLE_COLON: Treat expressions containing a double-colon initial 
delimiter as special, encoding the entire content into the key.

More behaviors can be contributed (along with corresponding tests of 
course).

Once an Expression is compiled, the resultant object can be used for 
expansion by providing an expansion function.  The function is given a 
context which allows introspection into the key sub-expression, the 
default value sub-expression, and the string builder target.  In 
addition, the function may throw at most one checked exception type of 
the user's choice, allowing expansion problems to be reported in any way.

The API provides a few default expanders to support only simple system 
properties and environment variables in the de-facto standard manner 
that we have always done; this is useful for client libraries with basic 
behavior.

Find the initial code here: 
https://github.com/wildfly/wildfly-common/pull/10

I'll merge it pending a bit more testing & any feedback.
-- 
- DML