Skip to content

Define an escape syntax for $ and ${ in StringPropertyReplacer placeholders #55355

Description

@ahus1

Enhancement Description

StringPropertyReplacer replaces ${name} and ${name:default} placeholders in several places. There is no defined way to write a literal $ or a literal ${ when the text would otherwise be read as a placeholder. This enhancement defines one escape syntax, documents it, and applies it consistently.

The behavior of $ directly before a placeholder is also inconsistent today: a leading $${b} passed to the String API is replaced with $B, because the String API only starts scanning at the first ${. The same text stays $${b} after an earlier placeholder (${a}$${b} gives A$${b}) and when it is read through the stream API.

This is a potentially breaking change and therefore it should target 27.0.

Value Proposition

Users can write placeholder-like text, for example in workflow emails, theme properties or realm import files, without depending on a property being undefined. Today the only workaround is a default value of an undefined property, such as ${undefined:$} for a $, which stops working as soon as the property is defined.

Goals

  • Define one syntax to write a literal $ and a literal ${.
  • Make the String API and the stream API behave the same for a $ before a placeholder.
  • Document the placeholder syntax and the escape in one place in the guides, and link to it from the themes, realm import and workflow documentation.
  • List the change in the upgrade guide, as it changes the result for existing values that contain $${.

Non-Goals

  • Changing how ${name} and ${name:default} are resolved.
  • Changing the SmallRye expression handling for KC_ configuration.

Discussion

Follows from #55326 and the pull request #55327, which fix only a trailing $ and a $ directly before the closing brace of a placeholder.

Notes

Candidates for the syntax:

  • Doubled dollar: $${ gives a literal ${. It matches Java and SmallRye conventions and no parsing layer rewrites it. It changes the result for existing values that contain $${.
  • Backslash: \${ gives a literal ${. A backslash is consumed earlier in some places: Properties.load handles it in theme.properties, and \$ is not a valid JSON escape in realm import files. It would need \\${ there.
  • No escape: only document the limitation and the ${undefined:$} workaround.

Places that use the replacer and would be affected: workflow notify-user subject and message, theme.properties, realm import files, SAML adapter configuration, authorization client configuration and ResolveRelative.

Metadata

Metadata

Assignees

No one assigned

    Fields

    Value

    None yet

    Effort

    None yet

    Votes

    None yet

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions