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

[David M. Lloyd]

The jboss-common-core project became a sort of 'dumping ground' for 
literally any utility that anyone could think of, no matter how broad or 
narrow its use, yet everyone required it because it contained a number 
of essential pieces of shared code.  So to avoid repeating that, the 
wildfly-common project is very strictly curated with a policy that it's 
the last possible home for utilities that generally useful yet have no 
greater possible categorization.

For example if I have 50 useful collections classes, maybe that's enough 
to justify a separate library (and release cycle) given that they share 
a categorization.  But a one- or two-class utility that is very broadly 
useful (such as this expression parser) but doesn't really fit into 
another category might make sense to include in wildfly-common.

On 02/06/2017 03:00 PM, Peter Palaga wrote:
> Hi David,
>
> having this on one place from where other projects can consume it is
> clearly a good thing. I can remember having seen this kind of code
> copied to Hawkular and Keycloak because there was no reasonable way to
> reuse it.
>
> Could you please explain why you have chosen to place the new expression
> expander to Commons? I thought we had "commons must die" policy. Don't
> we have that kind of policy anymore?
>
> Thanks,
>
> Peter
>
> On 01/23/2017 05:59 PM, David M. Lloyd wrote:
>> 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