geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From strub...@apache.org
Subject svn commit: r1771058 - in /geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json: JsonArray.java JsonNumber.java JsonObject.java JsonString.java JsonStructure.java JsonValue.java
Date Wed, 23 Nov 2016 22:59:53 GMT
Author: struberg
Date: Wed Nov 23 22:59:53 2016
New Revision: 1771058

URL: http://svn.apache.org/viewvc?rev=1771058&view=rev
Log:
GERONIMO-6558 JavaDoc for JsonValues

Modified:
    geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonArray.java
    geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonNumber.java
    geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonObject.java
    geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonString.java
    geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonStructure.java
    geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonValue.java

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonArray.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonArray.java?rev=1771058&r1=1771057&r2=1771058&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonArray.java (original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonArray.java Wed
Nov 23 22:59:53 2016
@@ -17,30 +17,142 @@
 package javax.json;
 
 import java.util.List;
-
+import java.util.function.Function;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+/**
+ * A JsonArray e.g.
+ * <pre>
+ * [1,5,8]
+ * </pre>
+ * or
+ * <pre>
+ *  [
+ *   {"name":"karl", "age": 38},
+ *   {"name":"sue", "age": 42},
+ *  ]
+ * </pre>
+ *
+ *
+ */
 public interface JsonArray extends JsonStructure, List<JsonValue> {
+
+    /**
+     * @return the JsonObject at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to the JsonObject
+     */
     JsonObject getJsonObject(int index);
 
+    /**
+     * @return the JsonArray at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to the JsonArray
+     */
     JsonArray getJsonArray(int index);
 
+    /**
+     * @return the JsonNumber at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to the JsonNumber
+     */
     JsonNumber getJsonNumber(int index);
 
+    /**
+     * @return the JsonString at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to the JsonString
+     */
     JsonString getJsonString(int index);
 
+    /**
+     * @return the respective JsonValue at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to the given slazz
+     */
     <T extends JsonValue> List<T> getValuesAs(Class<T> clazz);
 
+    /**
+     * Returns a list for the array. The value and the type of the elements
+     * in the list is specified by the {@code func} argument.
+     * <p>This method can be used to obtain a list of the unwrapped types, such as
+     * <pre>{@code
+     *     List<String> strings = ary1.getValuesAs(JsonString::getString);
+     *     List<Integer> ints = ary2.getValuesAs(JsonNumber::intValue);
+     * } </pre>
+     * It can also be used to obtain a list of simple projections, such as
+     * <pre> {@code
+     *     Lsit<Integer> stringsizes = arr.getValueAs((JsonString v) -> v.getString().length();
+     * } </pre>
+     * @param <K> The element type (must be a subtype of JsonValue) of this JsonArray.
+     * @param <T> The element type of the returned List
+     * @param func The function that maps the elements of this JsonArray to the target elements.
+     * @return A List of the specified values and type.
+     * @throws ClassCastException if the {@code JsonArray} contains a value of wrong type
+     */
+    default <T, K extends JsonValue> List<T> getValuesAs(Function<K, T>
func) {
+        Stream<K> stream = (Stream<K>) stream();
+        return stream.map(func).collect(Collectors.toList());
+    }
+
+    /**
+     * @return the native String at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to a String
+     */
     String getString(int index);
 
+    /**
+     * @return the native String at the given position or the defaultValue if null
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to a String
+     */
     String getString(int index, String defaultValue);
 
+    /**
+     * @return the native int value at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to an int
+     */
     int getInt(int index);
 
+    /**
+     * @return the native int value at the given position or the defaultValue if null
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to an int
+     */
     int getInt(int index, int defaultValue);
 
+    /**
+     * @return the native boolean value at the given position
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to a boolean
+     */
     boolean getBoolean(int index);
 
+    /**
+     * @return the native boolean value at the given position or the defaultValue if null
+     * @throws IndexOutOfBoundsException if the index is out of range
+     * @throws ClassCastException if the value at the specified position is not
+     *                            assignable to a boolean
+     */
     boolean getBoolean(int index, boolean defaultValue);
 
+    /**
+     * @return whether the value at the given position is {@link JsonValue#NULL}.
+     * @throws IndexOutOfBoundsException if the index is out of range
+     */
     boolean isNull(int index);
 }
 

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonNumber.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonNumber.java?rev=1771058&r1=1771057&r2=1771058&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonNumber.java (original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonNumber.java Wed
Nov 23 22:59:53 2016
@@ -19,6 +19,13 @@ package javax.json;
 import java.math.BigDecimal;
 import java.math.BigInteger;
 
+/**
+ * JsonValue which represents a number.
+ *
+ * The decimal point is defined as dot '.'.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4627">RFC-4627 JSON Specification</a>
+ */
 public interface JsonNumber extends JsonValue {
     boolean isIntegral();
 

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonObject.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonObject.java?rev=1771058&r1=1771057&r2=1771058&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonObject.java (original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonObject.java Wed
Nov 23 22:59:53 2016
@@ -18,26 +18,86 @@ package javax.json;
 
 import java.util.Map;
 
+/**
+ * A JsonObject, e.g.
+ * <pre>
+ * {
+ *     "name":"karl",
+ *     "age":38,
+ *     "address": {
+ *         "street":"dummystreet"
+ *         "housenumber":12
+ *     }
+ * }
+ * </pre>
+ *
+ * A JsonObject is always also a Map which uses the attribute names as key mapping
+ * to their JsonValues.
+ */
 public interface JsonObject extends JsonStructure, Map<String, JsonValue> {
+
+    /**
+     * @return the JsonArray with the given name or {@code null} if there is no attribute
with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     JsonArray getJsonArray(String name);
 
+    /**
+     * @return the JsonObject with the given name or {@code null} if there is no attribute
with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     JsonObject getJsonObject(String name);
 
+    /**
+     * @return the JsonNumber with the given name or {@code null} if there is no attribute
with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     JsonNumber getJsonNumber(String name);
 
+    /**
+     * @return the JsonString with the given name or {@code null} if there is no attribute
with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     JsonString getJsonString(String name);
 
+    /**
+     * @return the native string with the given name or {@code null} if there is no attribute
with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     String getString(String name);
 
+    /**
+     * @return the native string with the given name or the default value if there is no
attribute with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     String getString(String name, String defaultValue);
 
+    /**
+     * @return the int with the given name or {@code null} if there is no attribute with
that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     int getInt(String name);
 
+    /**
+     * @return the int with the given name or the default value if there is no attribute
with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     int getInt(String name, int defaultValue);
 
+    /**
+     * @return the boolean with the given name or {@code null} if there is no attribute with
that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     boolean getBoolean(String name);
 
+    /**
+     * @return the boolean with the given name or the default value if there is no attribute
with that name
+     * @throws ClassCastException if the JsonValue cannot be correctly cast
+     */
     boolean getBoolean(String name, boolean defaultValue);
 
+    /**
+     * @return whether the attribute with the given name is {@link JsonValue#NULL}
+     */
     boolean isNull(String name);
 }

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonString.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonString.java?rev=1771058&r1=1771057&r2=1771058&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonString.java (original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonString.java Wed
Nov 23 22:59:53 2016
@@ -16,6 +16,9 @@
  */
 package javax.json;
 
+/**
+ * JsonValue which represents a string.
+ */
 public interface JsonString extends JsonValue {
     String getString();
 

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonStructure.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonStructure.java?rev=1771058&r1=1771057&r2=1771058&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonStructure.java
(original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonStructure.java
Wed Nov 23 22:59:53 2016
@@ -18,6 +18,10 @@ package javax.json;
 
 import javax.json.spi.JsonProvider;
 
+/**
+ * A complex type as JsonValue.
+ * This could either be a {@link JsonArray} or a {@link JsonObject}.
+ */
 public interface JsonStructure extends JsonValue {
 
     default JsonValue getValue(String jsonPointer) {

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonValue.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonValue.java?rev=1771058&r1=1771057&r2=1771058&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonValue.java (original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonValue.java Wed
Nov 23 22:59:53 2016
@@ -16,19 +16,26 @@
  */
 package javax.json;
 
+/**
+ * A single value in a JSON expression.
+ */
 public interface JsonValue {
 
     /**
      * The empty JSON object.
      */
-    static final JsonObject EMPTY_JSON_OBJECT = Json.createObjectBuilder().build();
+    JsonObject EMPTY_JSON_OBJECT = Json.createObjectBuilder().build();
 
     /**
      * The empty JSON array.
      */
-    static final JsonArray EMPTY_JSON_ARRAY = Json.createArrayBuilder().build();
+    JsonArray EMPTY_JSON_ARRAY = Json.createArrayBuilder().build();
+
 
-    static final JsonValue NULL = new JsonValue() {
+    /**
+     * A constant JsonValue for null values
+     */
+    JsonValue NULL = new JsonValue() {
         @Override
         public ValueType getValueType() {
             return ValueType.NULL;
@@ -49,7 +56,11 @@ public interface JsonValue {
             return "null";
         }
     };
-    static final JsonValue TRUE = new JsonValue() {
+
+    /**
+     * A constant JsonValue for TRUE
+     */
+    JsonValue TRUE = new JsonValue() {
         @Override
         public ValueType getValueType() {
             return ValueType.TRUE;
@@ -70,7 +81,11 @@ public interface JsonValue {
             return Boolean.TRUE.toString();
         }
     };
-    static final JsonValue FALSE = new JsonValue() {
+
+    /**
+     * A constant JsonValue for FALSE
+     */
+    JsonValue FALSE = new JsonValue() {
         @Override
         public ValueType getValueType() {
             return ValueType.FALSE;
@@ -111,4 +126,5 @@ public interface JsonValue {
     default JsonArray asJsonArray() {
         return JsonArray.class.cast(this);
     }
+
 }



Mime
View raw message