Module org.tquadrat.foundation.util
Package org.tquadrat.foundation.util

Class Template

java.lang.Object
org.tquadrat.foundation.util.Template
All Implemented Interfaces:
Serializable
@ClassVersion(sourceVersion="$Id: Template.java 1080 2024-01-03 11:05:21Z tquadrat $") @API(status=STABLE, since="0.1.0") public class Template extends Object implements Serializable

An instance of this class is basically a wrapper around a String that contains placeholders ("Variables") in the form ${<name>}, where <name is the variable name.

The variables names are case-sensitive.

Valid variable names may not contain other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

The prefix character is part of the name.

Finally, there is the single underscore that is allowed as a special variable.

When the system data is added as source (see replaceVariableFromSystemData() and replaceVariable() with addSystemData set to true), some additional variables are available:

"org.tquadrat.ipaddress"
One of the outbound IP addresses of the machine that executes the current program, if network is configured at all.
"org.tquadrat.macaddress"
The MAC address of the machine that executes the current program; if no network is configured, a dummy address is used.
"org.tquadrat.nodeid"
The node id of the machines that executes the current program; if no network is configured, a pseudo node id is used.
"org.tquadrat.now"
The current data and time in UTC time zone.
"org.tquadrat.pid"
The process id of the current program.
Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: Template.java 1080 2024-01-03 11:05:21Z tquadrat $
Since:
0.1.0
See Also:
UML Diagram
UML Diagram for "org.tquadrat.foundation.util.Template"⁠

UML Diagram for "org.tquadrat.foundation.util.Template"

UML Diagram for "org.tquadrat.foundation.util.Template"⁠

  • Field Details

  • Constructor Details

    • Template

      public Template(CharSequence templateText)
      Creates a new instance of Template.
      Parameters:
      templateText - The template text, containing variable in the form ${<name>}.

  • Method Details

    • adjustTemplate

      @MountPoint protected String adjustTemplate(String templateText)

      The mount point for template manipulations in derived classes.

      The default implementation will just return the argument.

      Parameters:
      templateText - The template text, as it was given to the constructor on creation of the object instance.
      Returns:
      The adjusted template text.

    • createAdditionalSource

      private static final Map<String,Object> createAdditionalSource()
      Builds the source map with the additional data.
      Returns:
      The source map.
      See Also:

    • escapeRegexReplacement

      @API(status=INTERNAL, since="0.1.0") private static String escapeRegexReplacement(CharSequence input)
      Escapes backslash ('\') and dollar sign ('$') for regex replacements.
      Parameters:
      input - The source string.
      Returns:
      The string with the escaped characters.
      Since:
      0.1.0
      See Also:

    • findVariables

      @API(status=STABLE, since="0.0.5") public static final Set<String> findVariables(CharSequence text)

      Collects all the variables of the form ${<name>} in the given String.

      If there are not any variables in the given String, an empty Set will be returned.

      A valid variable name may not contain any other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

      Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

      Finally, there is the single underscore that is allowed as a special variable.

      Parameters:
      text - The text with the variables; may be null.
      Returns:
      A Collection with the variable (names).
      Since:
      0.0.5
      See Also:

    • findVariables

      public final Set<String> findVariables()

      Collects all the variables of the form ${<name>} in the adjusted template.

      If there are not any variables in there, an empty Collection will be returned.

      A valid variable name may not contain any other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

      Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

      Finally, there is the single underscore that is allowed as a special variable.

      Returns:
      A Collection with the variable (names).
      See Also:

    • formatResult

      @MountPoint protected String formatResult(String text)

      Mountpoint for the formatting of the result after the variables have been replaced.

      The default implementation just returns the result.

      Parameters:
      text - The result from replacing the variables in the template text.
      Returns:
      The reformatted result.

    • getTemplateText

      protected final String getTemplateText()
      Returns the template text after it has been processed by adjustTemplate(String).
      Returns:
      The adjusted template text.

    • hasVariable

      public final boolean hasVariable(String name)
      Checks whether the adjusted template contains the variable of the form ${<name>} (matching the pattern given in VARIABLE_PATTERN) with the given name.
      Parameters:
      name - The name of the variable to look for.
      Returns:
      true if the template contains the variable, false otherwise.
      Throws:
      IllegalArgumentException - The given argument is not valid as a variable name.
      See Also:

    • hasVariables

      @API(status=STABLE, since="0.1.0") public static final boolean hasVariables(CharSequence input)
      Checks whether the given String contains at least one variable of the form ${<name>} (matching the pattern given in VARIABLE_PATTERN).
      Parameters:
      input - The String to test; can be null.
      Returns:
      true if the String contains at least one variable, false otherwise.
      Since:
      0.1.0
      See Also:

    • hasVariables

      public final boolean hasVariables()
      Checks whether the adjusted template contains at least one variable of the form ${<name>} (matching the pattern given in VARIABLE_PATTERN).
      Returns:
      true if the template contains at least one variable, false otherwise.
      See Also:

    • isValidVariableName

      @API(status=STABLE, since="0.1.0") public static final boolean isValidVariableName(CharSequence name)
      Test whether the given String is a valid variable name.
      Parameters:
      name - The bare variable name, without the surrounding "${…}".
      Returns:
      true if the given name is valid for a variable name, false otherwise.
      Since:
      0.1.0
      See Also:

    • isVariable

      @API(status=STABLE, since="0.1.0") public static final boolean isVariable(CharSequence input)
      Checks whether the given String is a variable in the form ${<name>}, according to the pattern provided in VARIABLE_PATTERN.
      Parameters:
      input - The String to test; can be null.
      Returns:
      true if the given String is not null, not the empty String, and it matches the given pattern, false otherwise.
      Since:
      0.1.0

    • replaceVariable

      @SafeVarargs @API(status=STABLE, since="0.1.0") public static final String replaceVariable(CharSequence text, Map<String,? extends Object>... sources)

      Replaces the variables of the form ${<name>} in the given String with values from the given maps. The method will try the maps in the given sequence, it stops after the first match.

      If no replacement value could be found, the variable will not be replaced at all.

      If a value from one of the maps contains a variable itself, this will not be replaced.

      The variables names are case-sensitive.

      Valid variable names may not contain other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

      Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

      The prefix character is part of the name.

      Finally, there is the single underscore that is allowed as a special variable.

      Parameters:
      text - The text with the variables; may be null.
      sources - The maps with the replacement values.
      Returns:
      The new text, or null if the provided value for text was already null.
      Since:
      0.1.0
      See Also:

    • replaceVariable

      @SafeVarargs public final String replaceVariable(Map<String,? extends Object>... sources)

      Replaces the variables of the form ${<name>} in the adjusted template with values from the given maps and returns it after formatting the result. The method will try the maps in the given sequence, it stops after the first match.

      If no replacement value could be found, the variable will not be replaced at all.

      If a value from one of the maps contains a variable itself, this will not be replaced.

      The variables names are case-sensitive.

      Valid variable names may not contain other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

      Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

      The prefix character is part of the name.

      Finally, there is the single underscore that is allowed as a special variable.

      Parameters:
      sources - The maps with the replacement values.
      Returns:
      The new text, or null if the provided value for text was already null.
      See Also:

    • replaceVariable

      @SafeVarargs public final String replaceVariable(boolean addSystemData, Map<String,? extends Object>... sources)

      Replaces the variables of the form ${<name>} in the adjusted template with values from the given maps and returns it after formatting the result. The method will try the maps in the given sequence, it stops after the first match.

      If addSystemData is provided as true, the system properties and System.getenv() system environment} will be searched for replacement values before any other source.

      If no replacement value could be found, the variable will not be replaced at all.

      If a value from one of the maps contains a variable itself, this will not be replaced.

      The variables names are case-sensitive.

      Valid variable names may not contain other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

      Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

      The prefix character is part of the name.

      Finally, there is the single underscore that is allowed as a special variable.

      Parameters:
      addSystemData - true if the system properties and the system environment should be searched for replacement values, too, otherwise false.
      sources - The maps with the replacement values.
      Returns:
      The new text, or null if the provided value for text was already null.
      See Also:

    • replaceVariable

      public final String replaceVariable(Function<? super String,Optional<String>> retriever)

      Replaces the variables of the form ${<name>} in the adjusted template with values returned by the given retriever function for the variable name, and returns it after formatting the result.

      If no replacement value could be found, the variable will not be replaced at all.

      If the retriever function returns a value that contains a variable itself, this will not be replaced.

      The retriever function will be called only once for each variable name; if the text contains the same variable multiple times, it will always be replaced with the same value.

      The variables names are case-sensitive.

      Valid variable names may not contain other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

      Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

      The prefix character is part of the name.

      Finally, there is the single underscore that is allowed as a special variable.

      Parameters:
      retriever - The function that will retrieve the replacement values for the given variable names.
      Returns:
      The new text, or null if the provided value for text was already null.
      See Also:

    • replaceVariable

      @API(status=STABLE, since="0.1.0") public static final String replaceVariable(CharSequence text, Function<? super String,Optional<String>> retriever)

      Replaces the variables of the form ${<name>} in the given String with values returned by the given retriever function for the variable name.

      If no replacement value could be found, the variable will not be replaced at all.

      If the retriever function returns a value that contains a variable itself, this will not be replaced.

      The retriever function will be called only once for each variable name; if the text contains the same variable multiple times, it will always be replaced with the same value.

      The variables names are case-sensitive.

      Valid variable name may not contain other characters than the letters from 'a' to 'z' (upper case and lower case), the digits from '0' to '9' and the special characters underscore ('_') and dot ('.'), after an optional prefix character.

      Allowed prefixes are the tilde ('~'), the slash ('/'), the equal sign ('='), the colon (':'), the percent sign ('%'), and the ampersand ('&').

      The prefix character is part of the name.

      Finally, there is the single underscore that is allowed as a special variable.

      Parameters:
      text - The text with the variables; may be null.
      retriever - The function that will retrieve the replacement values for the given variable names.
      Returns:
      The new text, or null if the provided value for text was already null.
      Since:
      0.1.0
      See Also:

    • replaceVariableFromSystemData

      @SafeVarargs @API(status=STABLE, since="0.1.0") public static final String replaceVariableFromSystemData(CharSequence text, Map<String,? extends Object>... additionalSources)

      Replaces the variables of the form ${<name>} in the given String with values from the system properties, the system environment and the given maps. The method will try the maps in the given sequence, it stops after the first match.

      In addition, five more variables are recognised:

      "org.tquadrat.ipaddress"
      The first IP address for the machine that executes this Java virtual machine.
      "org.tquadrat.macaddress"
      The MAC address of the first NIC in this machine.
      "org.tquadrat.nodeid"
      The node id from the first NIC in this machine.
      "org.tquadrat.now"
      The current date and time as returned by Instant.now().
      "org.tquadrat.pid"
      The process id of this Java virtual machine.

      If no replacement value could be found, the variable will not be replaced at all; no exception will be thrown.

      If a value from one of the maps contains a variable itself, this will not be replaced.

      The variables names are case-sensitive.

      Parameters:
      text - The text with the variables; can be null.
      additionalSources - The maps with additional replacement values.
      Returns:
      The new text, or null if the provided value for text was already null.
      See Also:

    • retrieveVariableValue

      @SafeVarargs private static final Optional<String> retrieveVariableValue(String name, Map<String,? extends Object>... sources)
      Tries to obtain a value for the given key from one of the given sources that will be searched in the given sequence order.
      Parameters:
      name - The name of the value.
      sources - The maps with the values.
      Returns:
      An instance of Optional that holds the value from one of the sources.