Added/updated code comments.

rousso · rousso · commit 75aa136596a0 · 2022-10-30T20:44:53.000+01:00
diff --git a/src/main/java/eu/europa/ted/efx/EfxTranslator.java b/src/main/java/eu/europa/ted/efx/EfxTranslator.java
@@ -1,3 +1,16 @@
+/*
+ * Copyright 2022 European Union
+ *
+ * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European
+ * Commission – subsequent versions of the EUPL (the "Licence"); You may not use this work except in
+ * compliance with the Licence. You may obtain a copy of the Licence at:
+ * https://joinup.ec.europa.eu/software/page/eupl
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the Licence
+ * is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the Licence for the specific language governing permissions and limitations under
+ * the Lic
+ */
 package eu.europa.ted.efx;
 
 import java.io.IOException;
@@ -6,28 +19,85 @@
 import eu.europa.ted.efx.component.EfxTranslatorFactory;
 import eu.europa.ted.efx.interfaces.TranslatorDependencyFactory;
 
+/**
+ * Provided for convenience, this class exposes static methods that allow you to quickly instantiate
+ * an EFX translator to translate EFX expressions and templates.
+ */
 public class EfxTranslator {
  
+  /**
+   * Instantiates an EFX expression translator and translates a given expression.
+   * 
+   * @param dependencyFactory A {@link TranslatorDependencyFactory} to be used for instantiating the
+   *        dependencies of the EFX expression translator.
+   * @param sdkVersion The version of the eForms SDK that defines the EFX grammar used by the
+   *        expression to be translated.
+   * @param expression The EFX expression to translate.
+   * @param expressionParameters The values of any parameters that the EFX expression requires.
+   * @return The translated expression in the target script language supported by the given
+   *         {@link TranslatorDependencyFactory}.
+   * @throws InstantiationException
+   */
   public static String translateExpression(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
       final String expression, final String... expressionParameters) throws InstantiationException {
     return EfxTranslatorFactory.getEfxExpressionTranslator(sdkVersion, dependencyFactory)
         .translateExpression(expression, expressionParameters);
   }
 
+  /**
+   * Instantiates an EFX template translator and translates the EFX template contained in the given
+   * file.
+   * 
+   * @param dependencyFactory A {@link TranslatorDependencyFactory} to be used for instantiating the
+   *        dependencies of the EFX template translator.
+   * @param sdkVersion The version of the eForms SDK that defines the EFX grammar used by the EFX
+   *        template to be translated.
+   * @param pathname The path to the file containing the EFX template to translate.
+   * @return The translated template in the target markup language supported by the given
+   *         {@link TranslatorDependencyFactory}.
+   * @throws IOException
+   * @throws InstantiationException
+   */
   public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion, 
       final Path pathname)
       throws IOException, InstantiationException {
     return EfxTranslatorFactory.getEfxTemplateTranslator(sdkVersion, dependencyFactory)
         .renderTemplate(pathname);
   }
 
+  /**
+   * Instantiates an EFX template translator and translates the given EFX template.
+   * 
+   * @param dependencyFactory A {@link TranslatorDependencyFactory} to be used for instantiating the
+   *        dependencies of the EFX template translator.
+   * @param sdkVersion The version of the eForms SDK that defines the EFX grammar used by the EFX
+   *        template to be translated.
+   * @param template A string containing the EFX template to translate.
+   * @return The translated template in the target markup language supported by the given
+   *         {@link TranslatorDependencyFactory}.
+   * @throws InstantiationException
+   */
   public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion,
       final String template)
       throws InstantiationException {
     return EfxTranslatorFactory.getEfxTemplateTranslator(sdkVersion, dependencyFactory)
         .renderTemplate(template);
   }
 
+  /**
+   * Instantiates an EFX template translator and translates the EFX template contained in the given
+   * InputStream.
+   * 
+   * @param dependencyFactory A {@link TranslatorDependencyFactory} to be used for instantiating the
+   *        dependencies of the EFX template translator.
+   * @param sdkVersion The version of the eForms SDK that defines the EFX grammar used by the EFX
+   *        template to be translated.
+   * @param stream An InputStream containing the EFX template to be translated.
+   * @return The translated template in the target markup language supported by the given
+   *         {@link TranslatorDependencyFactory}.
+   * @throws IOException
+   * @throws InstantiationException
+   */
   public static String translateTemplate(final TranslatorDependencyFactory dependencyFactory, final String sdkVersion, 
       final InputStream stream)
       throws IOException, InstantiationException {
diff --git a/src/main/java/eu/europa/ted/efx/interfaces/EfxExpressionTranslator.java b/src/main/java/eu/europa/ted/efx/interfaces/EfxExpressionTranslator.java
@@ -1,5 +1,33 @@
+/*
+ * Copyright 2022 European Union
+ *
+ * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European
+ * Commission – subsequent versions of the EUPL (the "Licence"); You may not use this work except in
+ * compliance with the Licence. You may obtain a copy of the Licence at:
+ * https://joinup.ec.europa.eu/software/page/eupl
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the Licence
+ * is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the Licence for the specific language governing permissions and limitations under
+ * the Lic
+ */
+
 package eu.europa.ted.efx.interfaces;
 
+/**
+ * Defines the API of an EFX expression translator.
+ * 
+ * Note that the behaviour of the translator is defined once during its instantiation using a
+ * TranslatorDependencyFactory.
+ */
 public interface EfxExpressionTranslator {
+
+  /**
+   * Translate the given EFX expression,
+   * 
+   * @param expression A string containing the EFX expression to be translated.
+   * @param expressionParameters The values of any parameters that the given expression expects.
+   * @return
+   */
   String translateExpression(final String expression, final String... expressionParameters);
 }
diff --git a/src/main/java/eu/europa/ted/efx/interfaces/EfxTemplateTranslator.java b/src/main/java/eu/europa/ted/efx/interfaces/EfxTemplateTranslator.java
@@ -1,19 +1,53 @@
+/*
+ * Copyright 2022 European Union
+ *
+ * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European
+ * Commission – subsequent versions of the EUPL (the "Licence"); You may not use this work except in
+ * compliance with the Licence. You may obtain a copy of the Licence at:
+ * https://joinup.ec.europa.eu/software/page/eupl
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the Licence
+ * is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the Licence for the specific language governing permissions and limitations under
+ * the Lic
+ */
 package eu.europa.ted.efx.interfaces;
 
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.file.Path;
 
+/**
+ * Defines the API of an EFX template translator.
+ * 
+ * Note that the behaviour of the translator is defined once during its instantiation using a
+ * TranslatorDependencyFactory.
+ */
 public interface EfxTemplateTranslator extends EfxExpressionTranslator {
+
   /**
-   * Opens the indicated EFX file and translates the EFX template it contains.
+   * Translate the EFX template stored in a file, given the pathname of the file.
+   * 
+   * @param pathname The path and filename of the EFX template file to translate.
+   * @return A string containing the translated template.
+   * @throws IOException
    */
   String renderTemplate(Path pathname) throws IOException;
 
   /**
-   * Translates the template contained in the string passed as a parameter.
+   * Translate the EFX template stored in the given string.
+   * 
+   * @param template A string containing an EFX template to be translated.
+   * @return A string containing the translated template.
    */
   String renderTemplate(String template);
 
+  /**
+   * Translate the EFX template given as an InputStream.
+   * 
+   * @param stream An InputStream with the EFX template to be translated.
+   * @return A string containing the translated template.
+   * @throws IOException
+   */
   String renderTemplate(InputStream stream) throws IOException;
 }
diff --git a/src/main/java/eu/europa/ted/efx/interfaces/MarkupGenerator.java b/src/main/java/eu/europa/ted/efx/interfaces/MarkupGenerator.java
@@ -1,3 +1,16 @@
+/*
+ * Copyright 2022 European Union
+ *
+ * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European
+ * Commission – subsequent versions of the EUPL (the "Licence"); You may not use this work except in
+ * compliance with the Licence. You may obtain a copy of the Licence at:
+ * https://joinup.ec.europa.eu/software/page/eupl
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the Licence
+ * is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the Licence for the specific language governing permissions and limitations under
+ * the Lic
+ */
 package eu.europa.ted.efx.interfaces;
 
 import java.util.List;
diff --git a/src/main/java/eu/europa/ted/efx/interfaces/ScriptGenerator.java b/src/main/java/eu/europa/ted/efx/interfaces/ScriptGenerator.java
@@ -1,3 +1,16 @@
+/*
+ * Copyright 2022 European Union
+ *
+ * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European
+ * Commission – subsequent versions of the EUPL (the "Licence"); You may not use this work except in
+ * compliance with the Licence. You may obtain a copy of the Licence at:
+ * https://joinup.ec.europa.eu/software/page/eupl
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the Licence
+ * is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the Licence for the specific language governing permissions and limitations under
+ * the Lic
+ */
 package eu.europa.ted.efx.interfaces;
 
 import java.util.List;
@@ -15,6 +28,17 @@
 import eu.europa.ted.efx.model.Expression.StringExpression;
 import eu.europa.ted.efx.model.Expression.TimeExpression;
 
+/**
+ * A ScriptGenerator is used by the EFX expression translator to translate specific computations to
+ * the target language script.
+ * 
+ * Each method defined by this interface corresponds to a specific computation that needs to be
+ * translated. The parameters necessary for each computation are passed to the method already
+ * translated to the target language. Each method should appropriately combine the given parameters
+ * to form the target language script and return it as an {@link Expression}.
+ * 
+ * As a reference implementation you can use the XPathScriptGenerator class.
+ */
 public interface ScriptGenerator {
 
   /**
diff --git a/src/main/java/eu/europa/ted/efx/interfaces/SymbolResolver.java b/src/main/java/eu/europa/ted/efx/interfaces/SymbolResolver.java
@@ -1,31 +1,55 @@
+/*
+ * Copyright 2022 European Union
+ *
+ * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by the European
+ * Commission – subsequent versions of the EUPL (the "Licence"); You may not use this work except in
+ * compliance with the Licence. You may obtain a copy of the Licence at:
+ * https://joinup.ec.europa.eu/software/page/eupl
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the Licence
+ * is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the Licence for the specific language governing permissions and limitations under
+ * the Lic
+ */
 package eu.europa.ted.efx.interfaces;
 
 import java.util.List;
 import eu.europa.ted.efx.model.Expression.PathExpression;
 
 /**
- * EFX expressions contain references to eForms fields and nodes. These references are in the form
- * of field or node identifiers (a.k.a. symbols). The role of the {@link SymbolResolver} is to
- * provide further information on these referenced fields or nodes by looking them up in a
- * repository.
+ * A SymbolResolver is a mechanism used by EFX translators to resolve symbols.
+ * 
+ * EFX expressions contain references to eForms entities (fields, nodes or codelists). These
+ * references are in the form of entity identifiers (a.k.a. symbols). The role of the
+ * {@link SymbolResolver} is to provide further information on these referenced entities by looking
+ * them up in a symbol dictionary (or repository). This symbol repository is typically the eForms
+ * SDK itself.
  */
 public interface SymbolResolver {
 
   /**
    * Gets the identifier of the parent node of the given field.
    * 
+   * This information is typically retrieved directly from the eForms SDK.
+   * 
    * @param fieldId The identifier of the field to look for.
    * @return The identifier of the parent node of the given field.
    */
   public String getParentNodeOfField(final String fieldId);
 
   /**
-   * Gets the path that can be used to locate the give field in the data source, relative to another
-   * given path.
+   * Gets the path that can be used to locate the given field in the data source, relative to
+   * another given path.
+   * 
+   * The "path" points to a location in the data source. The path will be eventually used to retrieve
+   * the data from the data source. Typically, the data source is an XML file, in which case the
+   * path should be an XPath. If the data source is a JSON file, then the path should be a JsonPath.
+   * If you intend to use a function call to retrieve the data from the data source then that is what
+   * you should return as path. In general keep in mind that the path is used as target language script.
    * 
    * @param fieldId The identifier of the field to look for.
    * @param contextPath The path relative to which we expect to find the return value.
-   * @return The path to the given field relative to the given context path.
+   * @return The path to the given field relative to the given contextPath.
    */
   public PathExpression getRelativePathOfField(final String fieldId,
       final PathExpression contextPath);
@@ -34,6 +58,8 @@ public PathExpression getRelativePathOfField(final String fieldId,
    * Gets the path that can be used to locate the given node in the data source, relative to another
    * given path.
    * 
+   * See {@link getRelativePathOfField} for a description of the concept of "path".
+   *  
    * @param nodeId The identifier of the node to look for.
    * @param contextPath The path relative to which we expect to find the return value.
    * @return The path to the given node relative to the given context path.
@@ -46,6 +72,8 @@ public PathExpression getRelativePathOfNode(final String nodeId,
   /**
    * Gets the absolute path that can be used to locate a field in the data source.
    * 
+   * See {@link getRelativePathOfField} for a description of the concept of "path".
+   * 
    * @param fieldId The identifier of the field to look for.
    * @return The absolute path to the field as a PathExpression.
    */
@@ -54,6 +82,8 @@ public PathExpression getRelativePathOfNode(final String nodeId,
   /**
    * Gets the absolute path the can be used to locate a node in the data source.
    * 
+   * See {@link getRelativePathOfField} for a description of the concept of "path".
+   * 
    * @param nodeId The identifier of the node to look for.
    * @return The absolute path to the node as a PathExpression.
    */
@@ -62,6 +92,8 @@ public PathExpression getRelativePathOfNode(final String nodeId,
   /**
    * Gets the type of the given field.
    * 
+   * This information is typically retrieved directly from the eForms SDK.
+   * 
    * @param fieldId The identifier of the field to look for.
    * @return The type of the field as a string.
    */
@@ -71,6 +103,8 @@ public PathExpression getRelativePathOfNode(final String nodeId,
    * Gets the codelist associated with the given field. If the codelist is a tailored codelist then
    * this method will return the identifier of its parent codelist.
    *
+   * This information is typically retrieved directly from the eForms SDK.
+   * 
    * @param fieldId The identifier of the field to look for.
    * @return The "root" codelist associated ith the given field.
    */
@@ -79,6 +113,8 @@ public PathExpression getRelativePathOfNode(final String nodeId,
   /**
    * Gets the list of all codes in a given codelist as a list of strings.
    * 
+   * This information is typically retrieved directly from the eForms SDK.
+   * 
    * @param codelistId The identifier of the codelist to expand.
    * @return The list of codes in the given codelist.
    */
diff --git a/src/main/java/eu/europa/ted/efx/interfaces/TranslatorDependencyFactory.java b/src/main/java/eu/europa/ted/efx/interfaces/TranslatorDependencyFactory.java
