Merge pull request #112 from OP-TED/TEDEFO-4367-adds-global-variables-and-functions

Tedefo 4367 adds global variables and functions

Author: rousso

pom.xml

@@ -60,7 +60,7 @@
 
     <!-- Versions - eForms -->
     <version.eforms-sdk-1>1.13.0</version.eforms-sdk-1>
-    <version.eforms-sdk-2>2.0.0-alpha.1</version.eforms-sdk-2>
+    <version.eforms-sdk-2>2.0.0-SNAPSHOT</version.eforms-sdk-2>
     <version.eforms-core>1.4.0</version.eforms-core>
 
     <!-- Versions - Third-party libraries -->

src/main/java/eu/europa/ted/efx/EfxTranslator.java

@@ -16,6 +16,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.file.Path;
+
 import eu.europa.ted.efx.component.EfxTranslatorFactory;
 import eu.europa.ted.efx.interfaces.TranslatorDependencyFactory;
 import eu.europa.ted.efx.interfaces.TranslatorOptions;
@@ -25,9 +26,15 @@
  * an EFX translator to translate EFX expressions and templates.
  */
 public class EfxTranslator {
+
+  private EfxTranslator() {
+    throw new UnsupportedOperationException("This is a utility class and cannot be instantiated");
+  }
 
   private static TranslatorOptions defaultOptions = EfxTranslatorOptions.DEFAULT;
 
+  //#region Translate EFX expressions -----------------------------------------
+
   /**
    * Instantiates an EFX expression translator and translates a given expression.
    * 
@@ -54,6 +61,10 @@ public static String translateExpression(final TranslatorDependencyFactory depen
     return translateExpression(dependencyFactory, sdkVersion, expression, defaultOptions, expressionParameters);
   }
 
+  //#endregion Translate EFX expressions --------------------------------------
+
+  //#region Translate EFX templates -------------------------------------------
+
   /**
    * Instantiates an EFX template translator and translates the EFX template contained in the given
    * file.
@@ -82,6 +93,14 @@ public static String translateTemplate(final TranslatorDependencyFactory depende
     return translateTemplate(dependencyFactory, sdkVersion, pathname, defaultOptions);
   }
 
+  public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
+      final String qualifier,
+      final Path pathname, TranslatorOptions options)
+      throws IOException, InstantiationException {
+    return EfxTranslatorFactory.getEfxTemplateTranslator(sdkVersion, qualifier, dependencyFactory, options)
+        .renderTemplate(pathname);
+  }
+
   /**
    * Instantiates an EFX template translator and translates the given EFX template.
    * 
@@ -98,8 +117,7 @@ public static String translateTemplate(final TranslatorDependencyFactory depende
   public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
       final String template, TranslatorOptions options)
       throws InstantiationException {
-    return EfxTranslatorFactory.getEfxTemplateTranslator(sdkVersion, dependencyFactory, options)
-        .renderTemplate(template);
+    return translateTemplate(dependencyFactory, sdkVersion, "", template, options);
   }
 
   public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
@@ -108,6 +126,13 @@ public static String translateTemplate(final TranslatorDependencyFactory depende
     return translateTemplate(dependencyFactory, sdkVersion, template, defaultOptions);
   }
 
+  public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
+      final String qualifier, final String template, TranslatorOptions options)
+      throws InstantiationException {
+    return EfxTranslatorFactory.getEfxTemplateTranslator(sdkVersion, qualifier, dependencyFactory, options)
+        .renderTemplate(template);
+  }
+
   /**
    * Instantiates an EFX template translator and translates the EFX template contained in the given
    * InputStream.
@@ -126,13 +151,21 @@ public static String translateTemplate(final TranslatorDependencyFactory depende
   public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
       final InputStream stream, TranslatorOptions options)
       throws IOException, InstantiationException {
-    return EfxTranslatorFactory.getEfxTemplateTranslator(sdkVersion, dependencyFactory, options)
-        .renderTemplate(stream);
+      return translateTemplate(dependencyFactory, sdkVersion, "", stream, options);
   }
 
   public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
       final InputStream stream)
       throws IOException, InstantiationException {
     return translateTemplate(dependencyFactory, sdkVersion, stream, defaultOptions);
   }
+
+  public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
+      final String qualifier, final InputStream stream, TranslatorOptions options)
+      throws IOException, InstantiationException {
+    return EfxTranslatorFactory.getEfxTemplateTranslator(sdkVersion, qualifier, dependencyFactory, options)
+        .renderTemplate(stream);
+  }
+
+  //#endregion Translate EFX templates ----------------------------------------
 }

src/main/java/eu/europa/ted/efx/EfxTranslatorOptions.java

@@ -10,28 +10,50 @@
 
 public class EfxTranslatorOptions implements TranslatorOptions {
 
+    /**
+     * This is the default namespace for user-defined functions (UDFs) in EFX.
+     * There is no need to change this but we made it customizable anyway.
+     * 
+     * This setting is relevant mostly for the EFX to XSLT translation process but it can also 
+     * be used for other target languages that need a namespace declaration for UDFs.
+     */
+    public static final String DEFAULT_UDF_NAMESPACE = "efx-udf";
+
     // Change to EfxDecimalFormatSymbols.EFX_DEFAULT to use the decimal format
     // preferred by OP (space as thousands separator and comma as decimal separator).
-    public static final EfxTranslatorOptions DEFAULT = new EfxTranslatorOptions(DecimalFormat.XSL_DEFAULT, Locale.ENGLISH);
+    public static final EfxTranslatorOptions DEFAULT = new EfxTranslatorOptions(DEFAULT_UDF_NAMESPACE, DecimalFormat.XSL_DEFAULT, Locale.ENGLISH);
 
     private final DecimalFormat symbols;
-    private Locale primaryLocale;
-    private ArrayList<Locale> otherLocales;
+    private final Locale primaryLocale;
+    private final ArrayList<Locale> otherLocales;
+    private final String userDefinedFunctionNamespace;
 
     public EfxTranslatorOptions(DecimalFormat symbols) {
-        this(symbols, Locale.ENGLISH);
+        this(DEFAULT_UDF_NAMESPACE, symbols);
+    }
+
+    public EfxTranslatorOptions(String udfNamespace, DecimalFormat symbols) {
+        this(udfNamespace, symbols, Locale.ENGLISH);
     }
 
     public EfxTranslatorOptions(DecimalFormat symbols, String primaryLanguage, String... otherLanguages) {
         this(symbols, Locale.forLanguageTag(primaryLanguage), Arrays.stream(otherLanguages).map(Locale::forLanguageTag).toArray(Locale[]::new));
     }
 
+    public EfxTranslatorOptions(String udfNamespace, DecimalFormat symbols, String primaryLanguage, String... otherLanguages) {
+        this(udfNamespace, symbols, Locale.forLanguageTag(primaryLanguage), Arrays.stream(otherLanguages).map(Locale::forLanguageTag).toArray(Locale[]::new));
+    }
+
     public EfxTranslatorOptions(DecimalFormat symbols, Locale primaryLocale, Locale... otherLocales) {
+        this(DEFAULT_UDF_NAMESPACE, symbols, primaryLocale, otherLocales);
+    }
+    
+    public EfxTranslatorOptions(String udfNamespace, DecimalFormat symbols, Locale primaryLocale, Locale... otherLocales) {
+        this.userDefinedFunctionNamespace = udfNamespace;
         this.symbols = symbols;
         this.primaryLocale = primaryLocale;
         this.otherLocales = new ArrayList<>(Arrays.asList(otherLocales));
     }
-    
 
     @Override
     public DecimalFormat getDecimalFormat() {
@@ -68,8 +90,13 @@ public String[] getAllLanguage3LetterCodes() {
         return languages.toArray(new String[0]);
     }
 
-    public EfxTranslatorOptions withLanguage(String language) {
-        this.primaryLocale = Locale.forLanguageTag(language);
-        return this;
+    /**
+     * This will be used by the Script Generator when generating script to invoke a user-defined function.
+     * It will also be used by the Markup Generator to generate the namespace declaration as well as the
+     * user-defined function definitions.
+     */
+    @Override
+    public String getUserDefinedFunctionNamespace() {
+        return this.userDefinedFunctionNamespace;
     }
 }

src/main/java/eu/europa/ted/efx/interfaces/MarkupGenerator.java

@@ -14,6 +14,7 @@
 package eu.europa.ted.efx.interfaces;
 
 import java.util.List;
+import java.util.Map;
 import java.util.Set;
 
 import org.apache.commons.lang3.tuple.Pair;
@@ -23,6 +24,7 @@
 import eu.europa.ted.efx.model.expressions.scalar.NumericExpression;
 import eu.europa.ted.efx.model.expressions.scalar.StringExpression;
 import eu.europa.ted.efx.model.templates.Markup;
+import eu.europa.ted.efx.model.types.EfxDataType;
 
 /**
  * The role of this interface is to allow the reuse of the Sdk6EfxTemplateTranslator to generate
@@ -45,6 +47,39 @@ public interface MarkupGenerator {
    */
   Markup composeOutputFile(final List<Markup> content, final List<Markup> fragments);
 
+  /**
+   * Given a body (main content) and a set of fragments, this method returns the full content of the
+   * target template file.
+   * 
+   * @param variables the variables to be included in the template file.
+   * @param functions the functions to be included in the template file.
+   * @param content the body (main content) of the template.
+   * @param fragments the fragments to be included in the template file.
+   * @return the full content of the target template file.
+   */
+  Markup composeOutputFile(List<Markup> globals, final List<Markup> content, final List<Markup> fragments);
+
+  /**
+   * Renders the markup necessary to declare and initialize the variable making it available at runtime.
+   *
+   * @param type        A subclass of {@link EfxDataType} specifying the type of the variable.
+   * @param name        The name of the variable to be declared.
+   * @param initialiser The expression used to initialize the variable.
+   * @return A {@link Markup} object that contains the variable declaration.
+   */
+  Markup renderVariableDeclaration(final Class<? extends EfxDataType> type, final String name, final Expression initialiser);
+
+  /**
+   * Renders the Markup necessary to make the function available at runtime.
+   *
+   * @param type        A sub-class of EfxDataType that represents the return type of the function.
+   * @param name        The name of the function.
+   * @param parameters  The function parameters as a map of parameter names to their corresponding EfxDataType.
+   * @param expression  The function body (the expression that must be evaluated when the function is invoked).
+   * @return            A Markup object that declares the function.
+   */
+  Markup renderFunctionDeclaration(final Class<? extends EfxDataType> type, final String name, final Map<String, Class<? extends EfxDataType>> parameters, final Expression expression);
+
   /**
    * Given an expression (which will eventually, at runtime, evaluate to the value of a field), this
    * method returns the template code that dereferences it (retrieves the value) in the target

src/main/java/eu/europa/ted/efx/interfaces/ScriptGenerator.java

@@ -110,6 +110,8 @@ public <T extends PathExpression> T composeFieldAttributeReference(
    */
   public <T extends TypedExpression> T composeVariableReference(String variableName, Class<T> type);
 
+  public <T extends TypedExpression> T composeParameterReference(String parameterName, Class<T> type);
+
   public <T extends TypedExpression> T composeVariableDeclaration(String variableName, Class<T> type);
 
   public <T extends TypedExpression> T composeParameterDeclaration(String parameterName, Class<T> type);
@@ -302,9 +304,7 @@ public NumericExpression composeNumericOperation(NumericExpression leftOperand,
 
   public DurationExpression getDurationLiteralEquivalent(final String efxLiteral);
 
-  /*
-   * Numeric Functions
-   */
+  // #region Numeric Functions ------------------------------------------------
 
   public NumericExpression composeCountOperation(final SequenceExpression list);
 
@@ -314,9 +314,9 @@ public NumericExpression composeNumericOperation(NumericExpression leftOperand,
 
   public NumericExpression composeStringLengthCalculation(StringExpression text);
 
-  /*
-   * String Functions
-   */
+  // #endregion Numeric Functions -------------------------------------------
+
+  // #region String Functions -----------------------------------------------
 
   public StringExpression composeStringConcatenation(List<StringExpression> list);
 
@@ -392,9 +392,9 @@ public StringExpression composeSubstringExtraction(StringExpression text, Numeri
    */
   public StringExpression getTextInPreferredLanguage(final PathExpression fieldReference);
 
-  /*
-   * Boolean Functions
-   */
+  // #endregion String Functions ----------------------------------------------
+
+  // #region Boolean Functions ------------------------------------------------
 
   public BooleanExpression composeExistsCondition(PathExpression reference);
 
@@ -404,9 +404,9 @@ public BooleanExpression composeUniqueValueCondition(PathExpression needle,
   public BooleanExpression composeSequenceEqualFunction(SequenceExpression one,
       SequenceExpression two);
 
-  /*
-   * Date Functions
-   */
+  // #endregion Boolean Functions --------------------------------------------
+
+  // #region Date Functions ---------------------------------------------------
 
   public DateExpression composeToDateConversion(StringExpression pop);
 
@@ -416,17 +416,15 @@ public DateExpression composeAddition(final DateExpression date,
   public DateExpression composeSubtraction(final DateExpression date,
       final DurationExpression duration);
 
-  /*
-   * Time Functions
-   */
+  //#endregion Date Functions -------------------------------------------------
 
-  public TimeExpression composeToTimeConversion(StringExpression pop);
+  // #region Time Functions ---------------------------------------------------
 
+  public TimeExpression composeToTimeConversion(StringExpression pop);
 
+  // #endregion Time Functions ------------------------------------------------
 
-  /*
-   * Duration Functions
-   */
+  // #region Duration Functions -----------------------------------------------
 
   public DurationExpression composeToDayTimeDurationConversion(StringExpression text);
 
@@ -446,9 +444,9 @@ public DurationExpression composeAddition(final DurationExpression left,
   public DurationExpression composeSubtraction(final DurationExpression left,
       final DurationExpression right);
 
-  /*
-   * Sequence Functions
-   */
+  // #endregion Duration Functions --------------------------------------------
+
+  // #region Sequence Functions --------------------------------------------
 
   public <T extends SequenceExpression> T composeDistinctValuesFunction(
       T list, Class<T> listType);
@@ -464,4 +462,24 @@ public <T extends SequenceExpression> T composeExceptFunction(T listOne,
 
   public <T extends ScalarExpression> T composeIndexer(SequenceExpression list,
       NumericExpression index, Class<T> type);
+
+  // #endregion Sequence Functions -----------------------------------------
+
+  // #region Function Invocation ------------------------------------------
+
+  /**
+   * Composes a function invocation expression with the specified function name, parameters, 
+   * and return type.
+   *
+   * @param <T> The type of the resulting expression, which must extend {@link TypedExpression}.
+   * @param functionName The name of the function to be invoked.
+   * @param parameters A list of parameters to be passed to the function, each of which must 
+   *                   extend {@link TypedExpression}.
+   * @param type The class object representing the expected return type of the function invocation.
+   * @return An expression that will invoke the function at runtime.
+   */
+  public <T extends TypedExpression> T composeFunctionInvocation(String functionName,
+          List<? extends TypedExpression> parameters, Class<T> type);
+
+  // #endregion Function Invocation -----------------------------------------
 }

src/main/java/eu/europa/ted/efx/interfaces/TranslatorOptions.java

@@ -12,4 +12,6 @@ public interface TranslatorOptions {
     public String[] getAllLanguage2LetterCodes();
 
     public String[] getAllLanguage3LetterCodes();
+
+    public String getUserDefinedFunctionNamespace();
 }