geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rsandt...@apache.org
Subject svn commit: r1782851 - /geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatch.java
Date Mon, 13 Feb 2017 20:18:04 GMT
Author: rsandtner
Date: Mon Feb 13 20:18:04 2017
New Revision: 1782851

URL: http://svn.apache.org/viewvc?rev=1782851&view=rev
Log:
GERONIMO-6558 added JsonPatch#Operation

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

Modified: geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatch.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatch.java?rev=1782851&r1=1782850&r2=1782851&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatch.java (original)
+++ geronimo/specs/trunk/geronimo-json_1.1_spec/src/main/java/javax/json/JsonPatch.java Mon
Feb 13 20:18:04 2017
@@ -35,28 +35,167 @@ package javax.json;
  * The 'operations' are performed in the order they are in the JsonPatch and applied
  * to the 'result' JSON document from the previous operation.
  * <p>
- * Supported operations are
- * <ul>
- * <li>ADD}</li>
- * <li>REMOVE}</li>
- * <li>REPLACE}</li>
- * <li>MOVE}</li>
- * <li>COPY}</li>
- * <li>TEST}</li>
- * </ul>
- * <p>
- * for more infos see <a href="https://tools.ietf.org/html/rfc6902">RFC-6902</a>
- * <p>
- * NOTICE: All JsonValues are immutable and therefore every {@code apply()} method will return
- * new references when the {@link JsonPatch} is applied.
+ *
+ * @see Operation
  *
  * @since 1.1
  */
 public interface JsonPatch {
 
     /**
+     * <p>
+     * An enumeration of available operations for {@link JsonPatch}.<br>
+     * <p>
+     * NOTICE: the behavoir of some operations depends on which {@link JsonValue} they are
performed.
+     * for details please check the documentation of the very operation.
+     *
+     * @see <a href="http://tools.ietf.org/html/rfc6902">RFC-6902</a>
+     *
+     * @since 1.1
+     */
+    enum Operation {
+
+        /**
+         * <p>
+         * required members are:
+         * <ul>
+         * <li>"op": "add"</li>
+         * <li>"path": "path/to/add"</li>
+         * <li>"value": "{@link JsonValue}ToAdd"</li>
+         * </ul>
+         * <p>
+         * if the "path/to" does not exist, this operation will result in an error.<br>
+         * if the "path/to/add" already exists, the value will be <strong>replaced</strong>
+         * <p>
+         * for {@link JsonArray}s the new value will be inserted at the specified index
+         * and the element(s) at/after are shifted to the right. the '-' character is used
to append the value
+         * at the and of the {@link JsonArray}.
+         */
+        ADD("add"),
+
+        /**
+         * <p>
+         * required members are:
+         * <ul>
+         * <li>"op": "remove"</li>
+         * <li>"path": "path/to/remove"</li>
+         * </ul>
+         * <p>
+         * if the "path/to/remove" does not exist, the operation will fail.
+         * <p>
+         * for {@link JsonArray}s the values after the removed value are shifted to the left
+         */
+        REMOVE("remove"),
+
+        /**
+         * <p>
+         * required members are:
+         * <ul>
+         * <li>"op": "replace"</li>
+         * <li>"path": "path/to/replace"</li>
+         * <li>"value": "the new {@link JsonValue}"</li>
+         * </ul>
+         * <p>
+         * this operation is identical to {@link #REMOVE} followed by {@link #ADD}
+         */
+        REPLACE("replace"),
+
+        /**
+         * <p>
+         * required members are:
+         * <ul>
+         * <li>"op": "move"</li>
+         * <li>"from": "path/to/move/from"</li>
+         * <li>"path": "path/to/move/to"</li>
+         * </ul>
+         * <p>
+         * the operation will fail it the "path/to/move/from" does not exist
+         * <p>
+         * NOTICE: a location can not be moved into one of it's children. (from /a/b/c to
/a/b/c/d)
+         * <p>
+         * this operation is identical to {@link #REMOVE} from "from" and {@link #ADD} to
the "path"
+         */
+        MOVE("move"),
+
+        /**
+         * <p>
+         * required members are:
+         * <ul>
+         * <li>"op": "copy"</li>
+         * <li>"from": "path/to/copy/from"</li>
+         * <li>"path": "path/to/add"</li>
+         * </ul>
+         * <p>
+         * the operation will result in an error if the "from" location does not exist
+         * <p>
+         * this operation is identical to {@link #ADD} with the "from" value
+         */
+        COPY("copy"),
+
+        /**
+         * <p>
+         * required members are:
+         * <ul>
+         * <li>"op": "test"</li>
+         * <li>"path": "/path/to/test"</li>
+         * <li>"value": "{@link JsonValue} to test"</li>
+         * </ul>
+         * <p>
+         * this operation fails, if the value is NOT equal with the /path/to/test
+         * <p>
+         * ordering of the elements in a {@link JsonObject} is NOT significant however
+         * the position of an element in a {@link JsonArray} is significant for equality.
+         */
+        TEST("test");
+
+
+        private final String operationName;
+
+
+        private Operation(String operationName) {
+            this.operationName = operationName;
+        }
+
+
+        /**
+         * @return the JSON operation name
+         */
+        public String operationName() {
+            return operationName;
+        }
+
+        /**
+         * Returns the {@link Operation} for the given {@code operationName}. If no {@link
Operation}
+         * is present, a {@link JsonException} will be thrown.
+         *
+         * @param operationName {@code operationName} to convert to the enum constant.
+         *
+         * @return the {@link Operation Operation-constant} for given {@code operationName}
+         *
+         * @throws JsonException if no {@link Operation} has been found for the given {@code
operationName}
+         */
+        public static Operation fromOperationName(String operationName) {
+
+            for (Operation op : values()) {
+                if (op.operationName().equalsIgnoreCase(operationName)) {
+                    return op;
+                }
+            }
+
+            throw new JsonException("unknown value for the operationName of the JSON patch
operation: " + operationName);
+        }
+    }
+
+
+    /**
+     * Applies the {@link JsonPatch} to the given {@code target}. If the
+     * given {@code target} is {@code null} a {@link NullPointerException}
+     * will be thrown.
+     *
      * @param target - the target to apply the {@link JsonPatch}
+     *
      * @return 'patched' {@link JsonStructure}
+     *
      * @throws NullPointerException if {@code target} is {@code null}
      */
     <T extends JsonStructure> T apply(T target);



Mime
View raw message