BIGTOP-685. provide a way to specify the parameters expected by a test (Wing Yew Poon via rvs)

7 files changed, 341 insertions, 25 deletions

diff --git a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Parameters.java b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Contract.java
index 7eb55dfa..1a79df21 100644
--- a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Parameters.java
+++ b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Contract.java
@@ -25,11 +25,15 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Specifies the contract for a test: what environment variables and system
+ * properties are used or expected by the test.
+ */
 @Documented
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
-public @interface Parameters {
+public @interface Contract {
   Variable[] env();
   Property[] properties();
 }
diff --git a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/ParameterSetter.java b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/ParameterSetter.java
index d42b7895..2930f193 100644
--- a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/ParameterSetter.java
+++ b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/ParameterSetter.java
@@ -23,52 +23,155 @@ import java.lang.reflect.Field;
 import static org.junit.Assert.assertNotNull;
 
 /**
-   Class containing utility methods for test classes to use (in a static
-   setup method) for obtaining the values of parameters passed in via
-   environment variables or system properties. The parameters are obtained
-   by introspecting the {@link org.apache.bigtop.itest.Parameters [Parameters]}
-   annotation of the test class.
+ * Class containing utility methods for test classes to use (in a static
+ * setup method) for obtaining the values of parameters passed in via
+ * environment variables or system properties. The parameters are obtained
+ * by introspecting the {@link org.apache.bigtop.itest.Contract Contract}
+ * annotation of the test class.
  */
 public class ParameterSetter {
 
+  /**
+   * Sets the values of parameters passed in via environment variables, using
+   * convention.
+   * Assumes the presence in the target class of static fields (the parameters)
+   * with the same names as the environment variables.
+   * (Unix/Linux environment variable names shall consist solely of uppercase
+   * letters, digits, and the '_' (underscore) character, and shall not begin
+   * with a digit.)
+   * If an environment variable is required and it is not set, an
+   * AssertionError is thrown.
+   * @param target the test class
+   * @throws NoSuchFieldException
+   * @throws IllegalAccessException
+   */
+  public static void setEnv(Class target)
+      throws NoSuchFieldException, IllegalAccessException {
+    Contract contract = (Contract) target.getAnnotation(Contract.class);
+    Variable[] vars = contract.env();
+    for (int i = 0; i < vars.length; i++) {
+      Variable var = vars[i];
+      String name = var.name();
+      Field field = target.getDeclaredField(name);
+      String value = System.getenv(name);
+      if (value == null && var.required()) {
+        assertNotNull(name + " is not set", value);
+      }
+      field.setAccessible(true);
+      field.set(target, value);
+    }
+  }
+
+  /**
+   * Sets the values of parameters passed in via environment variables.
+   * Assumes the presence in the target class of static fields with the given
+   * names.
+   * If an environment variable is required and it is not set, an
+   * AssertionError is thrown.
+   * @param target the test class
+   * @param fieldNames the names of the static fields corresponding to the
+   * environment variables; the number of names must match the number of
+   * environment variables
+   * @throws NoSuchFieldException
+   * @throws IllegalAccessException
+   */
   public static void setEnv(Class target, String[] fieldNames)
       throws NoSuchFieldException, IllegalAccessException {
-    Parameters params = (Parameters) target.getAnnotation(Parameters.class);
-    Variable[] vars = params.env();
+    Contract contract = (Contract) target.getAnnotation(Contract.class);
+    Variable[] vars = contract.env();
     assert vars.length == fieldNames.length;
     for (int i = 0; i < vars.length; i++) {
       Variable var = vars[i];
-      Field field = target.getField(fieldNames[i]);
-      String value = System.getenv(var.name());
+      String name = var.name();
+      Field field = target.getDeclaredField(fieldNames[i]);
+      String value = System.getenv(name);
       if (value == null && var.required()) {
-	assertNotNull(var.name() + " is not set", value);
+        assertNotNull(name + " is not set", value);
+      }
+      field.setAccessible(true);
+      field.set(target, value);
+    }
+  }
+
+  /**
+   * Sets the values of parameters passed in via system properties, using
+   * convention.
+   * Assumes the presence in the target class of static fields (the parameters)
+   * with the same names as the system properties, except with '.' replaced by
+   * '_'. (The names of the system properties shall be chosen so that the
+   * corresponding field names are valid Java identifiers.)
+   * If a system property is not set, the parameter is set to a default value.
+   * Therefore usable default values must be provided in the annotation or else
+   * test logic must be written to handle the lack thereof.
+   * @param target the test class
+   * @throws NoSuchFieldException
+   * @throws IllegalAccessException
+   */
+  public static void setProperties(Class target)
+      throws NoSuchFieldException, IllegalAccessException {
+    Contract contract = (Contract) target.getAnnotation(Contract.class);
+    Property[] props = contract.properties();
+    for (int i = 0; i < props.length; i++) {
+      Property prop = props[i];
+      String name = prop.name();
+      Field field = target.getDeclaredField(name.replace('.', '_'));
+      Object value = null;
+      switch (prop.type()) {
+      case STRING:
+        value = System.getProperty(name, prop.defaultValue());
+        break;
+      case INT:
+        value = Integer.getInteger(name, prop.intValue());
+        break;
+      case LONG:
+        value = Long.getLong(name, prop.longValue());
+        break;
+      case BOOLEAN:
+        value = Boolean.getBoolean(name);
       }
+      field.setAccessible(true);
       field.set(target, value);
     }
   }
 
+  /**
+   * Sets the values of parameters passed in via system properties.
+   * Assumes the presence in the target class of static fields with the given
+   * names.
+   * If a system property is not set, the parameter is set to a default value.
+   * Therefore usable default values must be provided in the annotation or else
+   * test logic must be written to handle the lack thereof.
+   * @param target the test class
+   * @param fieldNames the names of the static fields corresponding to the
+   * system properties; the number of names must match the number of
+   * system properties
+   * @throws NoSuchFieldException
+   * @throws IllegalAccessException
+   */
   public static void setProperties(Class target, String[] fieldNames)
       throws NoSuchFieldException, IllegalAccessException {
-    Parameters params = (Parameters) target.getAnnotation(Parameters.class);
-    Property[] props = params.properties();
+    Contract contract = (Contract) target.getAnnotation(Contract.class);
+    Property[] props = contract.properties();
     assert props.length == fieldNames.length;
     for (int i = 0; i < props.length; i++) {
       Property prop = props[i];
-      Field field = target.getField(fieldNames[i]);
+      String name = prop.name();
+      Field field = target.getDeclaredField(fieldNames[i]);
       Object value = null;
       switch (prop.type()) {
       case STRING:
-	value = System.getProperty(prop.name(), prop.defaultValue());
-	break;
+        value = System.getProperty(name, prop.defaultValue());
+        break;
       case INT:
-	value = Integer.getInteger(prop.name(), prop.intValue());
-	break;
+        value = Integer.getInteger(name, prop.intValue());
+        break;
       case LONG:
-	value = Long.getLong(prop.name(), prop.longValue());
-	break;
+        value = Long.getLong(name, prop.longValue());
+        break;
       case BOOLEAN:
-	value = Boolean.getBoolean(prop.name());
+        value = Boolean.getBoolean(name);
       }
+      field.setAccessible(true);
       field.set(target, value);
     }
   }
diff --git a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Property.java b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Property.java
index edd106f2..12e18d3b 100644
--- a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Property.java
+++ b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Property.java
@@ -32,7 +32,7 @@ public @interface Property {
   }
   String name();
   Type type() default Type.STRING;
-  String defaultValue();
-  int intValue();
-  long longValue();
+  String defaultValue() default "";
+  int intValue() default 0;
+  long longValue() default 0L;
 }
diff --git a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Variable.java b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Variable.java
index 6a11fa6c..f6594d2c 100644
--- a/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Variable.java
+++ b/bigtop-test-framework/src/main/groovy/org/apache/bigtop/itest/Variable.java
@@ -22,7 +22,7 @@ package org.apache.bigtop.itest;
    Specifies a parameter to be passed into a test via an environment variable.
    The parameter is a String.
    By default, the parameter is required. If it is required and a non-null value
-   cannot be found for it, an exception may be thrown.
+   cannot be found for it, an error may be thrown.
 */
 public @interface Variable {
   String name();
diff --git a/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractGroovy.groovy b/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractGroovy.groovy
new file mode 100644
index 00000000..98211d2c
--- /dev/null
+++ b/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractGroovy.groovy
@@ -0,0 +1,69 @@
+package org.apache.bigtop.itest;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+import static org.junit.Assert.*
+
+import org.apache.bigtop.itest.Contract;
+import org.apache.bigtop.itest.ParameterSetter;
+import org.apache.bigtop.itest.Property;
+import org.apache.bigtop.itest.Variable;
+
+@Contract(
+  properties = [
+    @Property(name="foo.int1", type=Property.Type.INT, intValue=1000),
+    @Property(name="foo.int2", type=Property.Type.INT),
+    @Property(name="foo.bar1", type=Property.Type.STRING, defaultValue="xyz"),
+    @Property(name="foo.bar2", type=Property.Type.STRING),
+    @Property(name="foo.bool1", type=Property.Type.BOOLEAN),
+    @Property(name="foo.bool2", type=Property.Type.BOOLEAN)
+  ],
+  env = [
+    @Variable(name="HOME"),
+    @Variable(name="BIGTOP_UNLIKELY_FOO_ENV", required=false)
+  ]
+)
+class TestContractGroovy {
+  public static int foo_int1;
+  public static int foo_int2;
+  protected static String foo_bar1;
+  protected static String foo_bar2;
+  private static boolean foo_bool1;
+  private static boolean foo_bool2;
+
+  static String HOME;
+  static String BIGTOP_UNLIKELY_FOO_ENV;
+
+  @BeforeClass
+  static void setUp() throws ClassNotFoundException, InterruptedException, NoSuchFieldException, IllegalAccessException {
+    System.setProperty("foo.int2", "100");
+    System.setProperty("foo.bool2", "true")
+
+    ParameterSetter.setProperties(TestContractGroovy.class);
+    ParameterSetter.setEnv(TestContractGroovy.class);
+  }
+
+  @Test
+  void testPropSettings() {
+    assertEquals("checking the value of foo_int1 from default value",
+                  1000, foo_int1);
+    assertEquals("checking the value of foo_int2 from foo.int2",
+                  100, foo_int2);
+    assertEquals("checking the value of foo_bar1 from default value",
+                  "xyz", foo_bar1);
+    assertEquals("checking the value of foo_bar2 from unset value",
+                  "", foo_bar2);
+    assertEquals("checking the value of foo_bool1 from unset value",
+                  false, foo_bool1);
+    assertEquals("checking the value of foo_bar2 from foo.bool2",
+                  true, foo_bool2);
+  }
+
+  @Test
+  void testEnvSettings() {
+    assertEquals("checking the value of \$HOME",
+                 System.getenv("HOME"), HOME);
+    assertEquals("checking the value of \$BIGTOP_UNLIKELY_FOO_ENV",
+                 null, BIGTOP_UNLIKELY_FOO_ENV);
+  }
+}
diff --git a/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractJava.java b/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractJava.java
new file mode 100644
index 00000000..6d3fb8d0
--- /dev/null
+++ b/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractJava.java
@@ -0,0 +1,69 @@
+package org.apache.bigtop.itest;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+import static org.junit.Assert.*;
+
+import org.apache.bigtop.itest.Contract;
+import org.apache.bigtop.itest.ParameterSetter;
+import org.apache.bigtop.itest.Property;
+import org.apache.bigtop.itest.Variable;
+
+@Contract(
+        properties = {
+                @Property(name="foo.int1", type=Property.Type.INT, intValue=1000),
+                @Property(name="foo.int2", type=Property.Type.INT),
+                @Property(name="foo.bar1", type=Property.Type.STRING, defaultValue="xyz"),
+                @Property(name="foo.bar2", type=Property.Type.STRING),
+                @Property(name="foo.bool1", type=Property.Type.BOOLEAN),
+                @Property(name="foo.bool2", type=Property.Type.BOOLEAN)
+        },
+        env = {
+                @Variable(name="HOME"),
+                @Variable(name="BIGTOP_UNLIKELY_FOO_ENV", required=false)
+        }
+)
+public class TestContractJava {
+    public static int foo_int1;
+    public static int foo_int2;
+    protected static String foo_bar1;
+    protected static String foo_bar2;
+    private static boolean foo_bool1;
+    private static boolean foo_bool2;
+
+    static String HOME;
+    static String BIGTOP_UNLIKELY_FOO_ENV;
+
+    @BeforeClass
+    public static void setUp() throws ClassNotFoundException, InterruptedException, NoSuchFieldException, IllegalAccessException {
+        System.setProperty("foo.int2", "100");
+        System.setProperty("foo.bool2", "true");
+
+        ParameterSetter.setProperties(TestContractJava.class);
+        ParameterSetter.setEnv(TestContractJava.class);
+    }
+
+    @Test
+    public void testPropSettings() {
+        assertEquals("checking the value of foo_int1 from default value",
+                1000, foo_int1);
+        assertEquals("checking the value of foo_int2 from foo.int2",
+                100, foo_int2);
+        assertEquals("checking the value of foo_bar1 from default value",
+                "xyz", foo_bar1);
+        assertEquals("checking the value of foo_bar2 from unset value",
+                "", foo_bar2);
+        assertEquals("checking the value of foo_bool1 from unset value",
+                false, foo_bool1);
+        assertEquals("checking the value of foo_bar2 from foo.bool2",
+                true, foo_bool2);
+    }
+
+    @Test
+    public void testEnvSettings() {
+        assertEquals("checking the value of $HOME",
+                System.getenv("HOME"), HOME);
+        assertEquals("checking the value of $BIGTOP_UNLIKELY_FOO_ENV",
+                null, BIGTOP_UNLIKELY_FOO_ENV);
+    }
+}
\ No newline at end of file
diff --git a/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractJavaProc.java b/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractJavaProc.java
new file mode 100644
index 00000000..875af1e2
--- /dev/null
+++ b/bigtop-test-framework/src/test/groovy/org/apache/bigtop/itest/TestContractJavaProc.java
@@ -0,0 +1,71 @@
+package org.apache.bigtop.itest;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+import static org.junit.Assert.*;
+
+import org.apache.bigtop.itest.Contract;
+import org.apache.bigtop.itest.ParameterSetter;
+import org.apache.bigtop.itest.Property;
+import org.apache.bigtop.itest.Variable;
+
+@Contract(
+        properties = {
+                @Property(name="foo.int1", type=Property.Type.INT, intValue=1000),
+                @Property(name="foo.int2", type=Property.Type.INT),
+                @Property(name="foo.bar1", type=Property.Type.STRING, defaultValue="xyz"),
+                @Property(name="foo.bar2", type=Property.Type.STRING),
+                @Property(name="foo.bool1", type=Property.Type.BOOLEAN),
+                @Property(name="foo.bool2", type=Property.Type.BOOLEAN)
+        },
+        env = {
+                @Variable(name="HOME"),
+                @Variable(name="BIGTOP_UNLIKELY_FOO_ENV", required=false)
+        }
+)
+public class TestContractJavaProc {
+    public static int foo_int1;
+    public static int foo_int2;
+    protected static String foo_bar1;
+    protected static String foo_bar2;
+    private static boolean foo_bool1;
+    private static boolean foo_bool2;
+
+    static String HOME;
+    static String BIGTOP_UNLIKELY_FOO_ENV;
+
+    @BeforeClass
+    public static void setUp() throws ClassNotFoundException, InterruptedException, NoSuchFieldException, IllegalAccessException {
+        System.setProperty("foo.int2", "100");
+        System.setProperty("foo.bool2", "true");
+
+        ParameterSetter.setProperties(TestContractJavaProc.class,
+                new String[] { "foo_int1", "foo_int2", "foo_bar1", "foo_bar2", "foo_bool1", "foo_bool2" });
+        ParameterSetter.setEnv(TestContractJavaProc.class,
+                new String[] { "HOME", "BIGTOP_UNLIKELY_FOO_ENV"});
+    }
+
+    @Test
+    public void testPropSettings() {
+        assertEquals("checking the value of foo_int1 from default value",
+                1000, foo_int1);
+        assertEquals("checking the value of foo_int2 from foo.int2",
+                100, foo_int2);
+        assertEquals("checking the value of foo_bar1 from default value",
+                "xyz", foo_bar1);
+        assertEquals("checking the value of foo_bar2 from unset value",
+                "", foo_bar2);
+        assertEquals("checking the value of foo_bool1 from unset value",
+                false, foo_bool1);
+        assertEquals("checking the value of foo_bar2 from foo.bool2",
+                true, foo_bool2);
+    }
+
+    @Test
+    public void testEnvSettings() {
+        assertEquals("checking the value of $HOME",
+                System.getenv("HOME"), HOME);
+        assertEquals("checking the value of $BIGTOP_UNLIKELY_FOO_ENV",
+                null, BIGTOP_UNLIKELY_FOO_ENV);
+    }
+}