source: josm/trunk/src/javax/json/JsonPatch.java@ 13611

Last change on this file since 13611 was 13231, checked in by Don-vip, 7 years ago

see #15682 - upgrade to JSR 374 (JSON Processing) API 1.1.2

File size: 5.6 KB
Line 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright (c) 2015-2017 Oracle and/or its affiliates. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can
10 * obtain a copy of the License at
11 * https://oss.oracle.com/licenses/CDDL+GPL-1.1
12 * or LICENSE.txt. See the License for the specific
13 * language governing permissions and limitations under the License.
14 *
15 * When distributing the software, include this License Header Notice in each
16 * file and include the License file at LICENSE.txt.
17 *
18 * GPL Classpath Exception:
19 * Oracle designates this particular file as subject to the "Classpath"
20 * exception as provided by Oracle in the GPL Version 2 section of the License
21 * file that accompanied this code.
22 *
23 * Modifications:
24 * If applicable, add the following below the License Header, with the fields
25 * enclosed by brackets [] replaced by your own identifying information:
26 * "Portions Copyright [year] [name of copyright owner]"
27 *
28 * Contributor(s):
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41package javax.json;
42
43/**
44 * <p>This interface represents an immutable implementation of a JSON Patch
45 * as defined by <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>.
46 * </p>
47 * <p>A {@code JsonPatch} can be instantiated with {@link Json#createPatch(JsonArray)}
48 * by specifying the patch operations in a JSON Patch. Alternately, it
49 * can also be constructed with a {@link JsonPatchBuilder}.
50 * </p>
51 * The following illustrates both approaches.
52 * <p>1. Construct a JsonPatch with a JSON Patch.
53 * <pre>{@code
54 * JsonArray contacts = ... // The target to be patched
55 * JsonArray patch = ... ; // JSON Patch
56 * JsonPatch jsonpatch = Json.createPatch(patch);
57 * JsonArray result = jsonpatch.apply(contacts);
58 * } </pre>
59 * 2. Construct a JsonPatch with JsonPatchBuilder.
60 * <pre>{@code
61 * JsonPatchBuilder builder = Json.createPatchBuilder();
62 * JsonArray result = builder.add("/John/phones/office", "1234-567")
63 * .remove("/Amy/age")
64 * .build()
65 * .apply(contacts);
66 * } </pre>
67 *
68 * @see <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>
69 *
70 * @since 1.1
71 */
72public interface JsonPatch {
73
74 /**
75 * This enum represents the list of valid JSON Patch operations
76 * as defined by <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>.
77 *
78 * @see <a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>
79 */
80 enum Operation {
81
82 /**
83 * "add" operation.
84 */
85 ADD("add"),
86
87 /**
88 * "remove" operation.
89 */
90 REMOVE("remove"),
91
92 /**
93 * "remove" operation.
94 */
95 REPLACE("replace"),
96
97 /**
98 * "move" operation.
99 */
100 MOVE("move"),
101
102 /**
103 * "copy" operation.
104 */
105 COPY("copy"),
106
107 /**
108 * "test" operation.
109 */
110 TEST("test");
111
112 private final String operationName;
113
114 private Operation(String operationName) {
115 this.operationName = operationName;
116 }
117
118 /**
119 * Returns enum constant name as lower case string.
120 *
121 * @return lower case name of the enum constant
122 */
123 public String operationName() {
124 return operationName;
125 }
126
127 /**
128 * Returns the enum constant with the specified name.
129 *
130 * @param operationName {@code operationName} to convert to the enum constant.
131 * @return the enum constant for given {@code operationName}
132 * @throws JsonException if given {@code operationName} is not recognized
133 */
134 public static Operation fromOperationName(String operationName) {
135 for (Operation op : values()) {
136 if (op.operationName().equalsIgnoreCase(operationName)) {
137 return op;
138 }
139 }
140 throw new JsonException("Illegal value for the operationName of the JSON patch operation: " + operationName);
141 }
142 }
143
144 /**
145 * Applies the patch operations to the specified {@code target}.
146 * The target is not modified by the patch.
147 *
148 * @param <T> the target type, must be a subtype of {@link JsonStructure}
149 * @param target the target to apply the patch operations
150 * @return the transformed target after the patch
151 * @throws JsonException if the supplied JSON Patch is malformed or if
152 * it contains references to non-existing members
153 */
154 <T extends JsonStructure> T apply(T target);
155
156 /**
157 * Returns the {@code JsonPatch} as {@code JsonArray}.
158 *
159 * @return this {@code JsonPatch} as {@code JsonArray}
160 */
161 JsonArray toJsonArray();
162
163}
Note: See TracBrowser for help on using the repository browser.