Introduce util class Json for constants and static methods

Since JsonValue has two subclasses JsonArray and JsonObject, the
constants NULL, TRUE, and FALSE defined on JsonValue are available
on the subclasses by inheritance. For example, the expression

    JsonArray.TRUE

actually compiles even though it's non-sense. The same is true for
the static factory methods. I've seen this happen, despite compiler
warnings, and it can result in pretty incomprehensible code.

Move constants to a dedicated util class Json and deprecate the
constants on JsonValue to prevent those cases.

This also results in shorter code and matches common language: for
example, Json.NULL represents "json null".

In a next step, static factory methods can be moved to this class as
well.

See #52

com.eclipsesource.json/src/main/java/com/eclipsesource/json/Json.java

@@ -0,0 +1,49 @@
+/*******************************************************************************
+ * Copyright (c) 2015 EclipseSource.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ ******************************************************************************/
+package com.eclipsesource.json;
+
+
+/**
+ * Utility class that provides JSON constants.
+ */
+public abstract class Json {
+
+  private Json() {
+    // not meant to be instantiated
+  }
+
+  /**
+   * Represents the JSON literal <code>true</code>.
+   */
+  public static final JsonValue TRUE = JsonLiteral.TRUE;
+
+  /**
+   * Represents the JSON literal <code>false</code>.
+   */
+  public static final JsonValue FALSE = JsonLiteral.FALSE;
+
+  /**
+   * Represents the JSON literal <code>null</code>.
+   */
+  public static final JsonValue NULL = JsonLiteral.NULL;
+
+}

com.eclipsesource.json/src/main/java/com/eclipsesource/json/JsonParser.java

@@ -163,15 +163,15 @@ private JsonValue readNull() throws IOException {
     readRequiredChar('u');
     readRequiredChar('l');
     readRequiredChar('l');
-    return JsonValue.NULL;
+    return Json.NULL;
   }
 
   private JsonValue readTrue() throws IOException {
     read();
     readRequiredChar('r');
     readRequiredChar('u');
     readRequiredChar('e');
-    return JsonValue.TRUE;
+    return Json.TRUE;
   }
 
   private JsonValue readFalse() throws IOException {
@@ -180,7 +180,7 @@ private JsonValue readFalse() throws IOException {
     readRequiredChar('l');
     readRequiredChar('s');
     readRequiredChar('e');
-    return JsonValue.FALSE;
+    return Json.FALSE;
   }
 
   private void readRequiredChar(char ch) throws IOException {

com.eclipsesource.json/src/main/java/com/eclipsesource/json/JsonValue.java

@@ -65,18 +65,24 @@ public abstract class JsonValue implements Serializable {
 
   /**
    * Represents the JSON literal <code>true</code>.
+   * @deprecated Use <code>Json.TRUE</code> instead
    */
-  public static final JsonValue TRUE = JsonLiteral.TRUE;
+  @Deprecated
+  public static final JsonValue TRUE = Json.TRUE;
 
   /**
    * Represents the JSON literal <code>false</code>.
+   * @deprecated Use <code>Json.FALSE</code> instead
    */
-  public static final JsonValue FALSE = JsonLiteral.FALSE;
+  @Deprecated
+  public static final JsonValue FALSE = Json.FALSE;
 
   /**
    * Represents the JSON literal <code>null</code>.
+   * @deprecated Use <code>Json.NULL</code> instead
    */
-  public static final JsonValue NULL = JsonLiteral.NULL;
+  @Deprecated
+  public static final JsonValue NULL = Json.NULL;
 
   JsonValue() {
     // prevent subclasses outside of this package

com.eclipsesource.json/src/test/java/com/eclipsesource/json/JsonArray_Test.java

@@ -153,7 +153,7 @@ public void iterator_hasNextAfterAdd() {
 
     Iterator<JsonValue> iterator = array.iterator();
     assertTrue(iterator.hasNext());
-    assertEquals(JsonValue.TRUE, iterator.next());
+    assertEquals(Json.TRUE, iterator.next());
     assertFalse(iterator.hasNext());
   }
 
@@ -182,7 +182,7 @@ public void values_containsValueAfterAdd() {
     array.add(true);
 
     assertEquals(1, array.values().size());
-    assertEquals(JsonValue.TRUE, array.values().get(0));
+    assertEquals(Json.TRUE, array.values().get(0));
   }
 
   @Test
@@ -198,7 +198,7 @@ public void values_reflectsChanges() {
   public void values_preventsModification() {
     List<JsonValue> values = array.values();
 
-    values.add(JsonValue.TRUE);
+    values.add(Json.TRUE);
   }
 
   @Test
@@ -296,7 +296,7 @@ public void add_string_toleratesNull() {
 
   @Test
   public void add_jsonNull() {
-    array.add(JsonValue.NULL);
+    array.add(Json.NULL);
 
     assertEquals("[null]", array.toString());
   }
@@ -317,7 +317,7 @@ public void add_jsonObject() {
 
   @Test
   public void add_json_enablesChaining() {
-    assertSame(array, array.add(JsonValue.NULL));
+    assertSame(array, array.add(Json.NULL));
   }
 
   @Test
@@ -468,7 +468,7 @@ public void set_string_enablesChaining() {
   public void set_jsonNull() {
     array.add(false);
 
-    array.set(0, JsonValue.NULL);
+    array.set(0, Json.NULL);
 
     assertEquals("[null]", array.toString());
   }
@@ -504,14 +504,14 @@ public void run() {
 
   @Test(expected = IndexOutOfBoundsException.class)
   public void set_json_failsWithInvalidIndex() {
-    array.set(0, JsonValue.NULL);
+    array.set(0, Json.NULL);
   }
 
   @Test
   public void set_json_enablesChaining() {
     array.add(false);
 
-    assertSame(array, array.set(0, JsonValue.NULL));
+    assertSame(array, array.set(0, Json.NULL));
   }
 
   @Test

com.eclipsesource.json/src/test/java/com/eclipsesource/json/JsonObject_Test.java

@@ -198,7 +198,7 @@ public void iterator_nextReturnsActualValue() {
     object.add("a", true);
     Iterator<Member> iterator = object.iterator();
 
-    assertEquals(new Member("a", JsonValue.TRUE), iterator.next());
+    assertEquals(new Member("a", Json.TRUE), iterator.next());
   }
 
   @Test
@@ -209,7 +209,7 @@ public void iterator_nextProgressesToNextValue() {
 
     iterator.next();
     assertTrue(iterator.hasNext());
-    assertEquals(new Member("b", JsonValue.FALSE), iterator.next());
+    assertEquals(new Member("b", Json.FALSE), iterator.next());
   }
 
   @Test(expected = NoSuchElementException.class)
@@ -253,14 +253,14 @@ public void get_returnsNullForNonExistingMember() {
   public void get_returnsValueForName() {
     object.add("foo", true);
 
-    assertEquals(JsonValue.TRUE, object.get("foo"));
+    assertEquals(Json.TRUE, object.get("foo"));
   }
 
   @Test
   public void get_returnsLastValueForName() {
     object.add("foo", false).add("foo", true);
 
-    assertEquals(JsonValue.TRUE, object.get("foo"));
+    assertEquals(Json.TRUE, object.get("foo"));
   }
 
   @Test
@@ -425,7 +425,7 @@ public void add_string_enablesChaining() {
 
   @Test
   public void add_jsonNull() {
-    object.add("a", JsonValue.NULL);
+    object.add("a", Json.NULL);
 
     assertEquals("{\"a\":null}", object.toString());
   }
@@ -446,7 +446,7 @@ public void add_jsonObject() {
 
   @Test
   public void add_json_enablesChaining() {
-    assertSame(object, object.add("a", JsonValue.NULL));
+    assertSame(object, object.add("a", Json.NULL));
   }
 
   @Test
@@ -572,7 +572,7 @@ public void set_string_enablesChaining() {
 
   @Test
   public void set_jsonNull() {
-    object.set("a", JsonValue.NULL);
+    object.set("a", Json.NULL);
 
     assertEquals("{\"a\":null}", object.toString());
   }
@@ -593,21 +593,21 @@ public void set_jsonObject() {
 
   @Test
   public void set_json_enablesChaining() {
-    assertSame(object, object.set("a", JsonValue.NULL));
+    assertSame(object, object.set("a", Json.NULL));
   }
 
   @Test
   public void set_addsElementIfMissing() {
-    object.set("a", JsonValue.TRUE);
+    object.set("a", Json.TRUE);
 
     assertEquals("{\"a\":true}", object.toString());
   }
 
   @Test
   public void set_modifiesElementIfExisting() {
-    object.add("a", JsonValue.TRUE);
+    object.add("a", Json.TRUE);
 
-    object.set("a", JsonValue.FALSE);
+    object.set("a", Json.FALSE);
 
     assertEquals("{\"a\":false}", object.toString());
   }
@@ -617,7 +617,7 @@ public void set_modifiesLastElementIfMultipleExisting() {
     object.add("a", 1);
     object.add("a", 2);
 
-    object.set("a", JsonValue.TRUE);
+    object.set("a", Json.TRUE);
 
     assertEquals("{\"a\":1,\"a\":true}", object.toString());
   }
@@ -944,61 +944,61 @@ public void deserializedObjectCanBeAccessed() throws Exception {
 
   @Test
   public void member_returnsNameAndValue() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
     assertEquals("a", member.getName());
-    assertEquals(JsonValue.TRUE, member.getValue());
+    assertEquals(Json.TRUE, member.getValue());
   }
 
   @Test
   public void member_equals_trueForSameInstance() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
     assertTrue(member.equals(member));
   }
 
   @Test
   public void member_equals_trueForEqualObjects() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
-    assertTrue(member.equals(new Member("a", JsonValue.TRUE)));
+    assertTrue(member.equals(new Member("a", Json.TRUE)));
   }
 
   @Test
   public void member_equals_falseForDifferingObjects() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
-    assertFalse(member.equals(new Member("b", JsonValue.TRUE)));
-    assertFalse(member.equals(new Member("a", JsonValue.FALSE)));
+    assertFalse(member.equals(new Member("b", Json.TRUE)));
+    assertFalse(member.equals(new Member("a", Json.FALSE)));
   }
 
   @Test
   public void member_equals_falseForNull() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
     assertFalse(member.equals(null));
   }
 
   @Test
   public void member_equals_falseForSubclass() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
-    assertFalse(member.equals(new Member("a", JsonValue.TRUE) {}));
+    assertFalse(member.equals(new Member("a", Json.TRUE) {}));
   }
 
   @Test
   public void member_hashCode_equalsForEqualObjects() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
-    assertTrue(member.hashCode() == new Member("a", JsonValue.TRUE).hashCode());
+    assertTrue(member.hashCode() == new Member("a", Json.TRUE).hashCode());
   }
 
   @Test
   public void member_hashCode_differsForDifferingobjects() {
-    Member member = new Member("a", JsonValue.TRUE);
+    Member member = new Member("a", Json.TRUE);
 
-    assertFalse(member.hashCode() == new Member("b", JsonValue.TRUE).hashCode());
-    assertFalse(member.hashCode() == new Member("a", JsonValue.FALSE).hashCode());
+    assertFalse(member.hashCode() == new Member("b", Json.TRUE).hashCode());
+    assertFalse(member.hashCode() == new Member("a", Json.FALSE).hashCode());
   }
 
   private static JsonObject object(String... namesAndValues) {

com.eclipsesource.json/src/test/java/com/eclipsesource/json/JsonParser_Test.java

@@ -71,7 +71,7 @@ public void parse_acceptsStrings() {
 
   @Test
   public void parse_acceptsLiterals() {
-    assertSame(JsonValue.NULL, parse("null"));
+    assertSame(Json.NULL, parse("null"));
   }
 
   @Test
@@ -391,7 +391,7 @@ public void numbers_incomplete() {
 
   @Test
   public void null_complete() {
-    assertEquals(JsonValue.NULL, parse("null"));
+    assertEquals(Json.NULL, parse("null"));
   }
 
   @Test
@@ -411,7 +411,7 @@ public void null_withIllegalCharacter() {
 
   @Test
   public void true_complete() {
-    assertSame(JsonValue.TRUE, parse("true"));
+    assertSame(Json.TRUE, parse("true"));
   }
 
   @Test
@@ -431,7 +431,7 @@ public void true_withIllegalCharacter() {
 
   @Test
   public void false_complete() {
-    assertSame(JsonValue.FALSE, parse("false"));
+    assertSame(Json.FALSE, parse("false"));
   }
 
   @Test