10:59 a.m.
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
3 p.m.
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.
3:33 p.m.
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
2857
days inactive
2871
days old
2 comments
2 participants
participants (2)
-
David M. Lloyd -
Peter Palaga