Package io.aiven.commons.kafka.connector.common.templating

package io.aiven.commons.kafka.connector.common.templating
Contains code to support Templating in connectors.

Strategy

The templating framework allows users to specify variables that will be placed into strings when they are rendered during the retrieval of the data from the configuration file. This is done by introducing a pattern: {{ foo }} where the variable foo will be replaced during processing.

Variable format

The variable comprises 2 parts: the variableName and an optional parameter. The parts are separated by a colon. There may not be any white space in the variable.

The variable is enclosed within pairs of curly braces, There may be spaces between the braces and the variable. For example {{foo}} and {{ foo }} are both valid.

Parameter format

A parameter, if it is present, consists of the separating colon, the parameterName, and equals sign, and the parameterValue. The parameter is used to provide data to a method that retrieves the data. For example a 'timestamp' variable might take a 'format' parameter that specifies the Java time format string.

Examples

{{ foo }}
Defines a variable with the name "foo" that has no parameters.
{{ foo:bar=baz }}
Defines a variable with the name "foo" that has a parameter "bar" with a value of "baz".
{{ foo:bad = space }}
Is an illegal formation as there are spaces in the parameter definition.
{{ foo bad:bar=baz }}
Is an illegal formation as there are spaces in the variableName.
{{ foo :bad=space }}
Is an illegal formation as there are spaces between the variableName and the parameter definition.

Defining Variables

TempalteVariables are defined using the TemplateVariable.Builder returned from the TemplateVariable.builder(java.lang.String) method. In addition to the @{variableName} that is provided in the builder call, variables have an optional description and optional ParameterDescriptor. If the description is provided it is used when generating documentation for users. The ParameterDescriptor must be provided if the variable has a parameter.

Defining Parameters

As noted above, parameters are defined by a ParameterDescriptor. This descriptor is created using the ParameterDescriptor.Builder returned from ParameterDescriptor.builder(java.lang.String). In addition to the required @{code parameterName} the parameters have a required flag to indicate the parameter is required, an optional description that is used for user documentation, and an optional validator.

The validator, if present, is a ConfigDef.Validator and is used to validate that the values specified in the template are valid. In addition, the validator documentation is used ot provide additional user documentation.

The TemplateVariableRegistry

The TemplateVariableRegistry is used to restrict the possible parameters that can be used in a template and to provide documentation to users. The TemplateVariableRegistry is built using the TemplateVariableRegistry.Builder returned from TemplateVariableRegistry.builder(). The TemplateVariableRegistry is immutable.

The TemplateParser

The TemplateParser parses the template from the textual representation. It will also validate that a textual representation is valid. If the @{code parse} or validate methods are called with a null TemplateVariableRegistry there will be no restrictions on the valid variable names. If the registry is provided, then variable names that are not in the registry will be accepted.

The TemplateValidator

The template validator is used to ensure that the template patterns specified in the configuration file are valid. It should be used in the ConfigDef to ensure that the data are valid before the connector starts running. In addition, the validator will provide information for the user configuration documentation.