/*
* 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();
}