Class TranslationPattern
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
A class implementing this interface should help the parser of translation patterns answering the following questions: How many parameters in the target function?TranslationPattern.ParameterTranslator.getNbParameters()
How to translate/serialize the parameter specified by its index?TranslationPattern.ParameterTranslator.translate(int)
-
Method Summary
Modifier and TypeMethodDescriptionstatic String
apply
(String transPattern, ADQLFunction fct, ADQLTranslator translator) Apply the given translation pattern to the given ADQL function.static String
apply
(String transPattern, TranslationPattern.ParameterTranslator paramTranslator) Apply a translation pattern in a generic way.static String
Validate the syntax of the translation pattern and all included argument indices.
-
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:
-
Single argument references are kept as such (e.g.
-
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
public static String apply(String transPattern, TranslationPattern.ParameterTranslator paramTranslator) throws NullPointerException, ParseException, TranslationException Apply a translation pattern in a generic way. The target function's arguments are translating through aTranslationPattern.ParameterTranslator
.Implementation note: There are 2 more specific variants of this function:
-
check(String, int)
which only check the syntax and argument indices -
apply(String, ADQLFunction, ADQLTranslator)
which translate a given ADQL function using a given ADQL translator.
- 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.
-
-