geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From strub...@apache.org
Subject svn commit: r1772799 - /geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatchBuilder.java
Date Mon, 05 Dec 2016 20:50:45 GMT
Author: struberg
Date: Mon Dec  5 20:50:44 2016
New Revision: 1772799

URL: http://svn.apache.org/viewvc?rev=1772799&view=rev
Log:
GERONIMO-6558 applying doc patch from Reinhard

txs to rsandtner for the patch!

Modified:
    geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatchBuilder.java

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatchBuilder.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatchBuilder.java?rev=1772799&r1=1772798&r2=1772799&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatchBuilder.java
(original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatchBuilder.java
Mon Dec  5 20:50:44 2016
@@ -17,54 +17,204 @@
 
 package javax.json;
 
-import javax.json.spi.JsonProvider;
-
 /**
  * TODO this is a final class in the spec, but that makes no sense.
- * Use {@link JsonProvider#createPatchBuilder()}
- * A JsonPatchBuilder contains state and should not get used concurrently.
+ * This class can be used to easily create {@link JsonPatch}es.
+ * To get an instance use {@link Json#createPatchBuilder()} or {@link Json#createPatchBuilder(JsonArray)}
+ * The order of the operations corresponds to the order they are builded.
+ * <p>
+ * NOTICE: A JsonPatchBuilder contains state and therefore is NOT threadsafe and should not
be used concurrently.
+ * </p>
+ * <p>
+ * The following {@link JsonPatch}
+ * <pre>
+ *     "[
+ *         {
+ *           "op": "add",
+ *           "path": "/add/object",
+ *           "value": {
+ *             "foo": "bar"
+ *           }
+ *         },
+ *         {
+ *           "op": "remove",
+ *           "path": "/remove/it"
+ *         },
+ *         {
+ *           "op": "move",
+ *           "path": "move/to",
+ *           "from": "move/from"
+ *         }
+ *     ]"
+ * </pre>
+ * can be build with the JsonPatchBuilder
+ * <pre>
+ *
+ *     JsonPatch patch = Json.createJsonPatchBuilder()
+ *                           .add("/add/object", Json.createObjectBuilder()
+ *                                                   .add("foo", "bar")
+ *                                                   .build())
+ *                           .remove("/remove/it")
+ *                           .move("/move/to", "move/from")
+ *                           .build();
+ *
+ * </pre>
+ * </p>
+ * <p>
+ * An instance of a JsonPatchBuilder can be reused for another {@link JsonPatch} after
+ * the {@link #build()}-Method was called.
+ * </p>
  */
 public interface JsonPatchBuilder {
 
-
-
+    //X TODO 'apply'-methods can be simplified to <T extends JsonStructure> T apply(T
target)
+    /**
+     * Applies the builded {@link JsonPatch} to the given target.<br>
+     * simplified call for {@code build().apply()}.
+     *
+     * @param target {@link JsonStructure} to apply the patch operations
+     *
+     * @return the created {@link JsonStructure} with all patch operations applied
+     *
+     * @throws NullPointerException if the given {@code target} is {@code null}
+     */
     JsonStructure apply(JsonStructure target);
 
+    /**
+     * @see #apply(JsonStructure)
+     */
     JsonObject apply(JsonObject target);
-    
+
+    /**
+     * @see #apply(JsonStructure)
+     */
     JsonArray apply(JsonArray target);
-    
+
+
+    /**
+     * Adds an 'add'-operation to the {@link JsonPatch}
+     *
+     * @param path as {@link JsonPointer} where the value should be added
+     * @param value the value to add
+     *
+     * @return the builder instance for chained method calls
+     *
+     * @throws NullPointerException if the given {@code path} is {@code null}
+     */
     JsonPatchBuilder add(String path, JsonValue value);
 
+    /**
+     * @see #add(String, JsonValue)
+     */
     JsonPatchBuilder add(String path, String value);
 
+    /**
+     * @see #add(String, JsonValue)
+     */
     JsonPatchBuilder add(String path, int value);
 
+    /**
+     * @see #add(String, JsonValue)
+     */
     JsonPatchBuilder add(String path, boolean value);
 
+
+    /**
+     * Adds a 'remove'-operation to the {@link JsonPatch}
+     *
+     * @param path as {@link JsonPointer} of the value which should get removed
+     *
+     * @return the builder instance for chained method calls
+     *
+     * @throws NullPointerException if the given {@code path} is {@code null}
+     */
     JsonPatchBuilder remove(String path);
 
+
+    /**
+     * Adds a 'replace'-operation to the {@link JsonPatch}
+     *
+     * @param path as {@link JsonPointer} to the value which should get replaced
+     * @param value the new value
+     *
+     * @return the builder instance for chained method calls
+     *
+     * @throws NullPointerException if the given {@code path} is {@code null}
+     */
     JsonPatchBuilder replace(String path, JsonValue value);
 
+    /**
+     * @see #replace(String, JsonValue)
+     */
     JsonPatchBuilder replace(String path, String value);
 
+    /**
+     * @see #replace(String, JsonValue)
+     */
     JsonPatchBuilder replace(String path, int value);
 
+    /**
+     * @see #replace(String, JsonValue)
+     */
     JsonPatchBuilder replace(String path, boolean value);
 
+
+    /**
+     * Adds a 'move'-operation to the {@link JsonPatch}
+     *
+     * @param path where the value should get inserted as {@link JsonPointer}
+     * @param from where the value should be taken from as {@link JsonPointer}
+     *
+     * @return the builder instance for chained method calls
+     *
+     * @throws NullPointerException if the given {@code path} is {@code null}
+     *                              if the given {@code from} is {@code null}
+     */
     JsonPatchBuilder move(String path, String from);
- 
+
+
+    /**
+     * Adds a 'copy'-operation to the {@link JsonPatch}
+     *
+     * @param path where the copied value should get inserted as {@link JsonPointer}
+     * @param from value to copy as {@link JsonPointer}
+     *
+     * @return the builder instance for chained method calls
+     *
+     * @throws NullPointerException if the given {@code path} is {@code null}
+     *                              if the given {@code from} is {@code null}
+     */
     JsonPatchBuilder copy(String path, String from);
- 
 
+
+    /**
+     * Adds a 'test'-operation to the {@link JsonPointer}
+     *
+     * @param path as {@link JsonPointer} to the value to test
+     * @param value value to test
+
+     * @return the builder instance for chained method calls
+
+     * @throws NullPointerException if the given {@code path} is {@code null}
+     */
     JsonPatchBuilder test(String path, JsonValue value);
 
+    /**
+     * @see #test(String, JsonValue)
+     */
     JsonPatchBuilder test(String path, String value);
 
+    /**
+     * @see #test(String, JsonValue)
+     */
     JsonPatchBuilder test(String path, int value);
 
+    /**
+     * @see #test(String, JsonValue)
+     */
     JsonPatchBuilder test(String path, boolean value);
 
+
     JsonPatch build();
 }
 



Mime
View raw message