javax.json.JsonPatch Maven / Gradle / Ivy
/*
* 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;
/**
*
* JsonPatch is a format for expressing a sequence of operations to apply on
* a target JSON document.
*
*
* A JsonPatch is an array of 'operations' in the form e.g.
*
*
* [
* { "op": "add", "path": "/foo/-", "value": ["abc", "def"] }
* { "path": "/a/b/c", "op": "add", "value": "foo" }
* ]
*
*
* The 'operations' are performed in the order they are in the JsonPatch and applied
* to the 'result' JSON document from the previous operation.
*
*
* @see Operation
*
* @since 1.1
*/
public interface JsonPatch {
/**
*
* An enumeration of available operations for {@link JsonPatch}.
*
* 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 RFC-6902
*
* @since 1.1
*/
enum Operation {
/**
*
* required members are:
*
* - "op": "add"
* - "path": "path/to/add"
* - "value": "{@link JsonValue}ToAdd"
*
*
* if the "path/to" does not exist, this operation will result in an error.
* if the "path/to/add" already exists, the value will be replaced
*
* 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"),
/**
*
* required members are:
*
* - "op": "remove"
* - "path": "path/to/remove"
*
*
* if the "path/to/remove" does not exist, the operation will fail.
*
* for {@link JsonArray}s the values after the removed value are shifted to the left
*/
REMOVE("remove"),
/**
*
* required members are:
*
* - "op": "replace"
* - "path": "path/to/replace"
* - "value": "the new {@link JsonValue}"
*
*
* this operation is identical to {@link #REMOVE} followed by {@link #ADD}
*/
REPLACE("replace"),
/**
*
* required members are:
*
* - "op": "move"
* - "from": "path/to/move/from"
* - "path": "path/to/move/to"
*
*
* the operation will fail it the "path/to/move/from" does not exist
*
* NOTICE: a location can not be moved into one of it's children. (from /a/b/c to /a/b/c/d)
*
* this operation is identical to {@link #REMOVE} from "from" and {@link #ADD} to the "path"
*/
MOVE("move"),
/**
*
* required members are:
*
* - "op": "copy"
* - "from": "path/to/copy/from"
* - "path": "path/to/add"
*
*
* the operation will result in an error if the "from" location does not exist
*
* this operation is identical to {@link #ADD} with the "from" value
*/
COPY("copy"),
/**
*
* required members are:
*
* - "op": "test"
* - "path": "/path/to/test"
* - "value": "{@link JsonValue} to test"
*
*
* this operation fails, if the value is NOT equal with the /path/to/test
*
* 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 apply(T target);
/**
* @return the JsonPatch as {@link JsonArray}
*/
JsonArray toJsonArray();
}