Merge pull request #95 from InseeFr/develop

Version 0.1.2

pom.xml

@@ -5,7 +5,7 @@
     <groupId>fr.insee.trevas</groupId>
     <artifactId>trevas-parent</artifactId>
     <packaging>pom</packaging>
-    <version>0.1.2-SNAPSHOT</version>
+    <version>0.1.2</version>
     <modules>
         <module>vtl-parser</module>
         <module>vtl-model</module>

vtl-engine/pom.xml

@@ -7,25 +7,25 @@
     <parent>
         <groupId>fr.insee.trevas</groupId>
         <artifactId>trevas-parent</artifactId>
-        <version>0.1.2-SNAPSHOT</version>
+        <version>0.1.2</version>
     </parent>
 
     <artifactId>vtl-engine</artifactId>
     <name>VTL Engine</name>
 	<description>VTL engine framework for Trevas</description>
-    <version>0.1.2-SNAPSHOT</version>
+    <version>0.1.2</version>
 
     <dependencies>
         <dependency>
             <groupId>fr.insee.trevas</groupId>
             <artifactId>vtl-parser</artifactId>
-            <version>0.1.2-SNAPSHOT</version>
+            <version>0.1.2</version>
             <scope>compile</scope>
         </dependency>
         <dependency>
             <groupId>fr.insee.trevas</groupId>
             <artifactId>vtl-model</artifactId>
-            <version>0.1.2-SNAPSHOT</version>
+            <version>0.1.2</version>
             <scope>compile</scope>
         </dependency>
         <dependency>

vtl-engine/src/main/java/fr/insee/vtl/engine/exceptions/VtlScriptException.java

@@ -40,7 +40,7 @@ public VtlScriptException(Exception mother, ParseTree tree) {
      * Returns the position in a VTL expression corresponding to a parsing context.
      *
      * @param tree The parsing context whose corresponding position is looked up.
-     * @return The position in the VTL expression, as an <code>Position</code> instance.
+     * @return The position in the VTL expression, as a <code>Position</code> instance.
      */
     public static Position positionOf(ParseTree tree) {
         if (tree instanceof ParserRuleContext) {
@@ -64,9 +64,9 @@ public ParseTree getTree() {
     }
 
     /**
-     * Returns the position in a VTL expressions that caused the exception.
+     * Returns the position in a VTL expression that caused the exception.
      *
-     * @return The position in the VTL expression, as an <code>Position</code> instance.
+     * @return The position in the VTL expression, as a <code>Position</code> instance.
      */
     public Position getPosition() {
         return positionOf(getTree());
@@ -82,28 +82,31 @@ public static class Position {
         private final Integer startColumn;
         private final Integer endColumn;
 
-
+        /**
+         * Constructor taking the tokens that start and end the faulty expression.
+         *
+         * @param from The token that begins the faulty expression.
+         * @param to The token that ends the faulty expression.
+         */
         public Position(Token from, Token to) {
             this.startLine = from.getLine() - 1;
             this.endLine = to.getLine() - 1;
             this.startColumn = from.getCharPositionInLine();
             this.endColumn = to.getCharPositionInLine() + (to.getStopIndex() - to.getStartIndex() + 1);
         }
 
+        /**
+         * Constructor taking a single token that corresponds to the faulty expression.
+         *
+         * @param token The token that corresponds to the faulty expression.
+         */
         public Position(Token token) {
             this.startLine = token.getLine() - 1;
             this.endLine = token.getLine() - 1;
             this.startColumn = token.getCharPositionInLine();
             this.endColumn = token.getCharPositionInLine() + (token.getStopIndex() - token.getStartIndex() + 1);
         }
 
-//        public Position(Integer startLine, Integer endLine, Integer startColumn, Integer endColumn) {
-//            this.startLine = startLine - 1;
-//            this.endLine = endLine - 1;
-//            this.startColumn = startColumn;
-//            this.endColumn = startLine + ( - token.getStartIndex() + 1);
-//        }
-
         /**
          * Returns the number of the line where the <code>Position</code> starts.
          *

vtl-engine/src/main/java/fr/insee/vtl/engine/exceptions/VtlSyntaxException.java

@@ -9,13 +9,19 @@ public class VtlSyntaxException extends VtlScriptException {
 
     private final Position position;
 
+    /**
+     * Constructor taking the error message and the faulty token.
+     *
+     * @param msg The error message for the exception.
+     * @param token The faulty token.
+     */
     public VtlSyntaxException(String msg, Token token) {
         super(msg, null);
         position = new Position(token);
     }
 
     /**
-     * Returns the position in a VTL expressions that caused the exception.
+     * Returns the position in a VTL expression that caused the exception.
      *
      * @return The position in the VTL expression, as an <code>Position</code> instance.
      */
@@ -24,5 +30,4 @@ public Position getPosition() {
         return position;
     }
 
-
 }

vtl-engine/src/main/java/fr/insee/vtl/engine/processors/InMemoryProcessingEngine.java

@@ -11,6 +11,9 @@
 
 import static fr.insee.vtl.model.Structured.*;
 
+/**
+ * The <code>InMemoryProcessingEngine</code> class is an implementation of a VTL engine that performs all operations in memory.
+ */
 public class InMemoryProcessingEngine implements ProcessingEngine {
 
     @Override
@@ -46,7 +49,6 @@ public DataStructure getDataStructure() {
                 return newStructure;
             }
         };
-
     }
 
     @Override
@@ -70,7 +72,6 @@ public Dataset resolve(Map<String, Object> context) {
                         .collect(Collectors.toList());
                 return new InMemoryDataset(result, getDataStructure());
             }
-
         };
     }
 
@@ -232,7 +233,7 @@ public DatasetExpression executeFullJoin(Map<String, DatasetExpression> datasets
     }
 
     /**
-     * Return a structure with the common identifiers only once.
+     * Returns a structure with the common identifiers only once.
      */
     private DataStructure createCommonStructure(List<Component> identifiers, DatasetExpression left, DatasetExpression right) {
         List<Component> components = new ArrayList<>(identifiers);
@@ -249,6 +250,7 @@ private DataStructure createCommonStructure(List<Component> identifiers, Dataset
         return new DataStructure(components);
     }
 
+    // TODO JavaDoc for the private methods below
     private Comparator<DataPoint> createPredicate(List<Component> identifiers) {
         return (dl, dr) -> {
             for (Component identifier : identifiers) {
@@ -391,6 +393,9 @@ public DataStructure getDataStructure() {
         };
     }
 
+    /**
+     * The <code>Factory</code> class is an implementation of a VTL engine factory that returns in-memory engines.
+     */
     public static class Factory implements ProcessingEngineFactory {
 
         @Override

vtl-engine/src/main/java/fr/insee/vtl/engine/utils/TypeChecking.java

@@ -6,32 +6,31 @@
 import fr.insee.vtl.model.TypedExpression;
 import org.antlr.v4.runtime.tree.ParseTree;
 
-import java.util.List;
-import java.util.Map;
 import java.util.Objects;
-import java.util.Set;
-import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 /**
- * <code>TypeChecking</code> class contains useful methods for checking the type of VTL expressions.
+ * The <code>TypeChecking</code> class contains useful methods for checking the type of VTL expressions.
  */
 public class TypeChecking {
 
+    /**
+     * Default constructor overridden to raise an exception: no instance of this class should be created.
+     */
     private TypeChecking() {
         throw new IllegalStateException("Type checking utility class");
     }
 
     /**
-     * Assert that an expression is of the given type.
+     * Asserts that an expression is of a given type.
      *
-     * If expression type is Object (null type), the returned expression will be of expected type.
+     * If the expression is null (see {@link #isNull(TypedExpression)}), the type of the returned expression will be the expected type.
      *
-     * @param expression the expression to check.
-     * @param type       the type to check against.
-     * @param tree       the tree of the expression.
-     * @return the expression.
-     * @throws VtlRuntimeException with {@link InvalidTypeException} as a cause.
+     * @param expression The expression to check.
+     * @param type The type to check against.
+     * @param tree The tree of the expression.
+     * @return The expression with the given type, even if originally null.
+     * @throws VtlRuntimeException with {@link InvalidTypeException} as a cause if the expression is not null and not of the required type.
      */
     public static <T extends TypedExpression> T assertTypeExpression(T expression, Class<?> type, ParseTree tree) {
         if (isNull(expression)) {
@@ -47,18 +46,18 @@ public static <T extends TypedExpression> T assertTypeExpression(T expression, C
      * Checks if an expression can be interpreted as a type.
      *
      * @param expression The expression to check.
-     * @param type       The type to check against.
-     * @return A boolean which is <code>true</code> if the expression can be interpreted as a type, <code>false</code> otherwise.
+     * @param type The type to check against.
+     * @return A boolean which is <code>true</code> if the expression can be interpreted as the given type, <code>false</code> otherwise.
      */
     public static boolean isType(TypedExpression expression, Class<?> type) {
         return type.isAssignableFrom(expression.getType());
     }
 
     /**
-     * Checks if expressions have the same type (or null type, Object for now).
+     * Checks if expressions have the same type (or null type).
      *
-     * @param  expressions    Objects to check.
-     * @return A boolean which is <code>true</code> if the expression can be interpreted as a type, <code>false</code> otherwise.
+     * @param  expressions Resolvable expressions to check.
+     * @return A boolean which is <code>true</code> if the expressions have the same type, <code>false</code> otherwise.
      */
     public static boolean hasSameTypeOrNull(ResolvableExpression... expressions) {
         return Stream.of(expressions)
@@ -68,6 +67,14 @@ public static boolean hasSameTypeOrNull(ResolvableExpression... expressions) {
                 .count() <= 1;
     }
 
+    /**
+     * Checks if an expression evaluates to null.
+     * The check is based on the fact that {@link TypedExpression#getType()} returns <code>Object</code> if the expression evaluates to
+     * null (otherwise, it returns a more specific class like <code>Boolean</code>).
+     *
+     * @param expression The expression to check.
+     * @return A boolean which is <code>true</code> if the expression evaluates to null, <code>false</code> otherwise.
+     */
     public static boolean isNull(TypedExpression expression) {
         return Object.class.equals(expression.getType());
     }
@@ -82,6 +89,13 @@ public static boolean isNumber(TypedExpression expression) {
         return isType(expression, Number.class);
     }
 
+    /**
+     * Asserts that an expression is of type <code>Number</code>, otherwise raises an exception.
+     * @param expression The expression to check.
+     * @param tree The tree of the expression.
+     * @param <T> The class of the expression provided (extends {@link TypedExpression}).
+     * @return The expression (typed as number if it evaluates to null).
+     */
     public static <T extends TypedExpression> T assertNumber(T expression, ParseTree tree) {
         return assertTypeExpression(expression, Number.class, tree);
     }
@@ -96,6 +110,14 @@ public static boolean isLong(TypedExpression expression) {
         return isType(expression, Long.class);
     }
 
+    /**
+     * Asserts that an expression is of type <code>Long</code>, otherwise raises an exception.
+     *
+     * @param expression The expression to check.
+     * @param tree The tree of the expression.
+     * @param <T> The class of the expression provided (extends {@link TypedExpression}).
+     * @return The expression (typed as long integer if it evaluates to null).
+     */
     public static <T extends TypedExpression> T assertLong(T expression, ParseTree tree) {
         return assertTypeExpression(expression, Long.class, tree);
     }
@@ -110,6 +132,13 @@ public static boolean isDouble(TypedExpression expression) {
         return isType(expression, Double.class);
     }
 
+    /**
+     * Asserts that an expression is of type <code>Double</code>, otherwise raises an exception.
+     * @param expression The expression to check.
+     * @param tree The tree of the expression.
+     * @param <T> The class of the expression provided (extends {@link TypedExpression}).
+     * @return The expression (typed as double-precision number if it evaluates to null).
+     */
     public static <T extends TypedExpression> T assertDouble(T expression, ParseTree tree) {
         return assertTypeExpression(expression, Double.class, tree);
     }
@@ -124,6 +153,13 @@ public static boolean isBoolean(TypedExpression expression) {
         return isType(expression, Boolean.class);
     }
 
+    /**
+     * Asserts that an expression is of type <code>Boolean</code>, otherwise raises an exception.
+     * @param expression The expression to check.
+     * @param tree The tree of the expression.
+     * @param <T> The class of the expression provided (extends {@link TypedExpression}).
+     * @return The expression (typed as boolean if it evaluates to null).
+     */
     public static <T extends TypedExpression> T assertBoolean(T expression, ParseTree tree) {
         return assertTypeExpression(expression, Boolean.class, tree);
     }
@@ -138,6 +174,13 @@ public static boolean isString(TypedExpression expression) {
         return isType(expression, String.class);
     }
 
+    /**
+     * Asserts that an expression is of type <code>String</code>, otherwise raises an exception.
+     * @param expression The expression to check.
+     * @param tree The tree of the expression.
+     * @param <T> The class of the expression provided (extends {@link TypedExpression}).
+     * @return The expression (typed as string if it evaluates to null).
+     */
     public static <T extends TypedExpression> T assertString(T expression, ParseTree tree) {
         return assertTypeExpression(expression, String.class, tree);
     }
@@ -152,6 +195,12 @@ public static boolean isDataset(TypedExpression expression) {
         return false;
     }
 
+    /**
+     * Checks if a list of objects contains one or more <code>null</code> values.
+     *
+     * @param objects The objects to check.
+     * @return A boolean which is <code>true</code> if one or more objects is <code>null</code>, <code>false</code> otherwise.
+     */
     public static boolean hasNullArgs(Object... objects) {
         return Stream.of(objects).anyMatch(Objects::isNull);
     }

vtl-jackson/pom.xml

@@ -7,19 +7,19 @@
     <parent>
         <groupId>fr.insee.trevas</groupId>
         <artifactId>trevas-parent</artifactId>
-        <version>0.1.2-SNAPSHOT</version>
+        <version>0.1.2</version>
     </parent>
 
     <artifactId>vtl-jackson</artifactId>
     <name>VTL Jackson</name>
 	<description>Jackson module for the VTL model</description>
-    <version>0.1.2-SNAPSHOT</version>
+    <version>0.1.2</version>
 
     <dependencies>
         <dependency>
             <groupId>fr.insee.trevas</groupId>
             <artifactId>vtl-model</artifactId>
-            <version>0.1.2-SNAPSHOT</version>
+            <version>0.1.2</version>
             <scope>compile</scope>
         </dependency>
         <dependency>

vtl-model/pom.xml

@@ -7,12 +7,12 @@
     <parent>
         <groupId>fr.insee.trevas</groupId>
         <artifactId>trevas-parent</artifactId>
-        <version>0.1.2-SNAPSHOT</version>
+        <version>0.1.2</version>
     </parent>
 
     <artifactId>vtl-model</artifactId>
     <name>VTL Model</name>
 	<description>Model describing VTL expressions and bindings</description>
-    <version>0.1.2-SNAPSHOT</version>
+    <version>0.1.2</version>
 
 </project>