Add a checker class for Immutable classes

Added a class to use in Unit tests to make sure that
classes are immutable.  It checks for the following conditions:
   - The class must be declared final
   - All data members must be declared private and final
   - There must be no setter methods
     (defined as a method name starting with "set")

Also added a unit test that tests the operation of the checker

Change-Id: I5d0f7a0b84d574938a750ab31cfc7c9677aa59e3
diff --git a/src/test/java/net/onrc/onos/api/rest/RestErrorTest.java b/src/test/java/net/onrc/onos/api/rest/RestErrorTest.java
index f505740..fb72f05 100644
--- a/src/test/java/net/onrc/onos/api/rest/RestErrorTest.java
+++ b/src/test/java/net/onrc/onos/api/rest/RestErrorTest.java
@@ -2,9 +2,12 @@
 
 import org.junit.Test;
 
+import static net.onrc.onos.core.util.ImmutableClassChecker.assertThatClassIsImmutable;
 import static net.onrc.onos.core.util.UtilityClassChecker.assertThatClassIsUtility;
 import static org.hamcrest.MatcherAssert.assertThat;
-import static org.hamcrest.Matchers.*;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
+import static org.hamcrest.Matchers.notNullValue;
 
 
 /**
@@ -78,4 +81,12 @@
     public void assureThatErrorCodesIsUtility() {
         assertThatClassIsUtility(RestErrorCodes.class);
     }
+
+    /**
+     * Make sure that the RestError class is immutable.
+     */
+    @Test
+    public void assureThatRestErrorIsImmutable() {
+        assertThatClassIsImmutable(RestError.class);
+    }
 }
diff --git a/src/test/java/net/onrc/onos/core/util/ImmutableClassChecker.java b/src/test/java/net/onrc/onos/core/util/ImmutableClassChecker.java
new file mode 100644
index 0000000..6002c58
--- /dev/null
+++ b/src/test/java/net/onrc/onos/core/util/ImmutableClassChecker.java
@@ -0,0 +1,112 @@
+package net.onrc.onos.core.util;
+
+import org.hamcrest.Description;
+import org.hamcrest.StringDescription;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+
+/**
+ * Hamcrest style class for verifying that a class follows the
+ * accepted rules for immutable classes.
+ *
+ * The rules that are enforced for immutable classes:
+ *    - the class must be declared final
+ *    - all data members of the class must be declared private and final
+ *    - the class must not define any setter methods
+ */
+
+public class ImmutableClassChecker {
+
+    private String failureReason = "";
+
+    /**
+     * Method to determine if a given class is a properly specified
+     * immutable class.
+     *
+     * @param clazz the class to check
+     * @return true if the given class is a properly specified immutable class.
+     */
+    private boolean isImmutableClass(Class clazz) {
+        // class must be declared final
+        if (!Modifier.isFinal(clazz.getModifiers())) {
+            failureReason = "a class that is not final";
+            return false;
+        }
+
+        // class must have only final and private data members
+        for (final Field field : clazz.getDeclaredFields()) {
+            if (!Modifier.isFinal(field.getModifiers())) {
+                failureReason = "a field named '" + field.getName() +
+                                "' that is not final";
+                return false;
+            }
+            if (!Modifier.isPrivate(field.getModifiers())) {
+                failureReason = "a field named '" + field.getName() +
+                                "' that is not private";
+                return false;
+            }
+        }
+
+        //  class must not define any setters
+        for (final Method method : clazz.getMethods()) {
+            if (method.getDeclaringClass().equals(clazz)) {
+                if (method.getName().startsWith("set")) {
+                    failureReason = "a class with a setter named '" + method.getName() + "'";
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Describe why an error was reported.  Uses Hamcrest style Description
+     * interfaces.
+     *
+     * @param description the Description object to use for reporting the
+     *                    mismatch
+     */
+    public void describeMismatch(Description description) {
+        description.appendText(failureReason);
+    }
+
+    /**
+     * Describe the source object that caused an error, using a Hamcrest
+     * Matcher style interface.  In this case, it always returns
+     * that we are looking for a properly defined utility class.
+     *
+     * @param description the Description object to use to report the "to"
+     *                    object
+     */
+    public void describeTo(Description description) {
+        description.appendText("a properly defined immutable class");
+    }
+
+    /**
+     * Assert that the given class adheres to the utility class rules.
+     *
+     * @param clazz the class to check
+     *
+     * @throws java.lang.AssertionError if the class is not a valid
+     *         utility class
+     */
+    public static void assertThatClassIsImmutable(Class clazz) {
+        final ImmutableClassChecker checker = new ImmutableClassChecker();
+        if (!checker.isImmutableClass(clazz)) {
+            final Description toDescription = new StringDescription();
+            final Description mismatchDescription = new StringDescription();
+
+            checker.describeTo(toDescription);
+            checker.describeMismatch(mismatchDescription);
+            final String reason =
+                    "\n" +
+                    "Expected: is \"" + toDescription.toString() + "\"\n" +
+                    "    but : was \"" + mismatchDescription.toString() + "\"";
+
+            throw new AssertionError(reason);
+        }
+    }
+}
diff --git a/src/test/java/net/onrc/onos/core/util/ImmutableClassCheckerTest.java b/src/test/java/net/onrc/onos/core/util/ImmutableClassCheckerTest.java
new file mode 100644
index 0000000..151c802
--- /dev/null
+++ b/src/test/java/net/onrc/onos/core/util/ImmutableClassCheckerTest.java
@@ -0,0 +1,119 @@
+package net.onrc.onos.core.util;
+
+import org.junit.Test;
+
+import static net.onrc.onos.core.util.ImmutableClassChecker.assertThatClassIsImmutable;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.is;
+
+/**
+ * Set of unit tests to check the implementation of the immutable class
+ * checker.
+ */
+public class ImmutableClassCheckerTest {
+    /**
+     * Test class for non final class check.
+     */
+    static class NonFinal {
+        private NonFinal() {}
+    }
+
+    /**
+     * Check that a non final class correctly produces an error.
+     * @throws Exception if any of the reflection lookups fail.
+     */
+    @Test
+    public void testNonFinalClass() throws Exception {
+        boolean gotException = false;
+        try {
+            assertThatClassIsImmutable(NonFinal.class);
+        } catch (AssertionError assertion) {
+            assertThat(assertion.getMessage(),
+                    containsString("is not final"));
+            gotException = true;
+        }
+        assertThat(gotException, is(true));
+    }
+
+    /**
+     * Test class for non private member class check.
+     */
+    static final class FinalProtectedMember {
+        protected final int x = 0;
+    }
+
+    /**
+     * Check that a final class with a non-private member is properly detected.
+     *
+     * @throws Exception if any of the reflection lookups fail.
+     */
+    @Test
+    public void testFinalProtectedMember() throws Exception {
+        boolean gotException = false;
+        try {
+            assertThatClassIsImmutable(FinalProtectedMember.class);
+        } catch (AssertionError assertion) {
+            assertThat(assertion.getMessage(),
+                       containsString("a field named 'x' that is not private"));
+            gotException = true;
+        }
+        assertThat(gotException, is(true));
+    }
+
+    /**
+     * Test class for non private member class check.
+     */
+    static final class NotFinalPrivateMember {
+        private int x = 0;
+    }
+
+    /**
+     * Check that a final class with a non-final private
+     * member is properly detected.
+     *
+     * @throws Exception if any of the reflection lookups fail.
+     */
+    @Test
+    public void testNotFinalPrivateMember() throws Exception {
+        boolean gotException = false;
+        try {
+            assertThatClassIsImmutable(NotFinalPrivateMember.class);
+        } catch (AssertionError assertion) {
+            assertThat(assertion.getMessage(),
+                    containsString("a field named 'x' that is not final"));
+            gotException = true;
+        }
+        assertThat(gotException, is(true));
+    }
+
+    /**
+     * Test class for non private member class check.
+     */
+    static final class ClassWithSetter {
+        private final int x = 0;
+        public void setX(int newX) {
+        }
+    }
+
+    /**
+     * Check that a final class with a final private
+     * member that is modifyable by a setter is properly detected.
+     *
+     * @throws Exception if any of the reflection lookups fail.
+     */
+    @Test
+    public void testClassWithSetter() throws Exception {
+        boolean gotException = false;
+        try {
+            assertThatClassIsImmutable(ClassWithSetter.class);
+        } catch (AssertionError assertion) {
+            assertThat(assertion.getMessage(),
+                    containsString("a class with a setter named 'setX'"));
+            gotException = true;
+        }
+        assertThat(gotException, is(true));
+    }
+
+}
+