Class TranslationPattern

java.lang.Object
adql.translator.TranslationPattern

public final class TranslationPattern extends Object
Tool box for translation patterns.

Note No instance of this class can be created. Its usage is only restricted to its public static functions.

Translation Pattern

A "translation pattern" is a string representing a pattern to follow when translating an ADQLFunction into a target language like SQL thanks to an ADQLTranslator.

Validation & Translation

This class provides 2 main features:

check(String, int)
To check whether a translation pattern is valid considering a given maximum number of function parameters.
apply(String, ADQLFunction, ADQLTranslator)
To translate a given ADQL function using a given translation pattern.

Behind the hood, both functions actually use the same function: apply(String, ParameterTranslator). This is a more generic approach that can be used to parse a pattern, check its syntax and resolve any argument reference or ternary expression. In the case of check(String, int), the argument reference is returned as such. apply(String, ADQLFunction, ADQLTranslator) however returns the exact translation of each argument reference.

If the proposed applications of apply(String, ParameterTranslator) do not suit your needs, you should use this function.

Supported syntax

Referencing a single function parameter

This can be done using the character $ followed by a positive non-null integer.

Examples: $1, $13

If 0, a negative value or an index greater than the maximum number of allowed parameters in the target function, then a ParseException is thrown. Any validation or translation process is then interrupted.

Escaping $

If the $ character aims to be a simple character in the translation string instead of a prefix for an argument index, it has to be escaped by prefixing it with another $.

Example: $$

Referencing consecutive function parameters

It is possible to reference a list of consecutive function parameters by suffixing the start index with ... By doing so, the entire dollar expression is replaced by all function parameters separated by a comma.

Example: the following expressions are equivalent for a function with 4 parameters:

 $2..
 $2, $3, $4

Ternary conditional expression

If the target function has a variable number of parameters, it is possible to adapt the translation in function of the available parameters. To do that one has to use the following ternary expression:

$IF?{THEN}{ELSE}

, where:

  • $IF must be a reference to the single function parameter whose existence has to be tested,
  • THEN should be the translation to apply if $IF exists,
  • ELSE should be the translation to apply if $IF does NOT exist.

Example: $2?{, $2*10}{}

As illustrated above, the expression THEN and ELSE can include parameter references (single or consecutive) but also other ternary conditional expressions.

Examples:

 $2?{, $2..}{}
 $2?{$3?{$2+$2}{$2}}{-1}
 

Warning: There is currently no way to escape the character } indicating the end of a THEN or ELSE expression.

Since:
2.0
  • Method Details

    • check

      public static String check(String transPattern, int nbMaxParams) throws NullPointerException, ParseException
      Validate the syntax of the translation pattern and all included argument indices.

      This function returns a resolved version of the input pattern. This means that:

      • Single argument references are kept as such (e.g. $1)
      • Argument references list (e.g. $2..) are "exploded" (e.g. $2, $3, $4).
      • Ternary conditional expressions are replaced by either the THEN or the ELSE expression depending on whether $IF exists or not.

      Note: This resolved version of the pattern is just informative.

      Implementation note: This function is actually a specialized usage of apply(String, ParameterTranslator). Instead of translating the target function arguments, only argument indices are checked and no real translation is operated.

      Parameters:
      transPattern - The translation pattern to validate.
      nbMaxParams - Maximum number of parameters for the target function. If negative, replaced by 0.
      Returns:
      The resolved pattern.
      Throws:
      NullPointerException - If any of the parameter is NULL or empty.
      ParseException - If the given pattern is incorrect.
      See Also:
    • apply

      public static String apply(String transPattern, ADQLFunction fct, ADQLTranslator translator) throws NullPointerException, TranslationException
      Apply the given translation pattern to the given ADQL function.
      Parameters:
      transPattern - The translation pattern to apply.
      fct - The actual ADQL function to translate.
      translator - The ADQL translator to use for parameters translation (e.g. columns, other functions).
      Returns:
      The resulting translation.
      Throws:
      NullPointerException - If any of the parameter is missing.
      TranslationException - If there is a problem when parsing the given translation pattern, or when translating arguments.
      See Also:
    • apply

      Apply a translation pattern in a generic way. The target function's arguments are translating through a TranslationPattern.ParameterTranslator.

      Implementation note: There are 2 more specific variants of this function:

      Parameters:
      transPattern - The translation pattern to apply.
      paramTranslator - How to translate any target function's argument.
      Returns:
      The resulting translation.
      Throws:
      NullPointerException - If any input argument is missing.
      ParseException - If the syntax of the given translation pattern is incorrect.
      TranslationException - If an error occurred while translating the target function's arguments.