| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package javax.json; |
| |
| /** |
| * <p> |
| * JsonPatch is a format for expressing a sequence of operations to apply on |
| * a target JSON document. |
| * </p> |
| * <p> |
| * A JsonPatch is an array of 'operations' in the form e.g. |
| * <p> |
| * <pre> |
| * [ |
| * { "op": "add", "path": "/foo/-", "value": ["abc", "def"] } |
| * { "path": "/a/b/c", "op": "add", "value": "foo" } |
| * ] |
| * </pre> |
| * <p> |
| * The 'operations' are performed in the order they are in the JsonPatch and applied |
| * to the 'result' JSON document from the previous operation. |
| * <p> |
| * |
| * @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; |
| |
| |
| 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); |
| |
| /** |
| * @return the JsonPatch as {@link JsonArray} |
| */ |
| JsonArray toJsonArray(); |
| } |
| |