001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2015-2017 Oracle and/or its affiliates. All rights reserved. 005 * 006 * The contents of this file are subject to the terms of either the GNU 007 * General Public License Version 2 only ("GPL") or the Common Development 008 * and Distribution License("CDDL") (collectively, the "License"). You 009 * may not use this file except in compliance with the License. You can 010 * obtain a copy of the License at 011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1 012 * or LICENSE.txt. See the License for the specific 013 * language governing permissions and limitations under the License. 014 * 015 * When distributing the software, include this License Header Notice in each 016 * file and include the License file at LICENSE.txt. 017 * 018 * GPL Classpath Exception: 019 * Oracle designates this particular file as subject to the "Classpath" 020 * exception as provided by Oracle in the GPL Version 2 section of the License 021 * file that accompanied this code. 022 * 023 * Modifications: 024 * If applicable, add the following below the License Header, with the fields 025 * enclosed by brackets [] replaced by your own identifying information: 026 * "Portions Copyright [year] [name of copyright owner]" 027 * 028 * Contributor(s): 029 * If you wish your version of this file to be governed by only the CDDL or 030 * only the GPL Version 2, indicate your decision by adding "[Contributor] 031 * elects to include this software in this distribution under the [CDDL or GPL 032 * Version 2] license." If you don't indicate a single choice of license, a 033 * recipient has the option to distribute your version of this file under 034 * either the CDDL, the GPL Version 2 or to extend the choice of license to 035 * its licensees as provided above. However, if you add GPL Version 2 code 036 * and therefore, elected the GPL Version 2 license, then the option applies 037 * only if the new code is made subject to such option by the copyright 038 * holder. 039 */ 040 041package javax.json; 042 043/** 044 * A builder for constructing a JSON Patch as defined by 045 * <a target=_blank href="http://tools.ietf.org/html/rfc6902">RFC 6902</a> by adding 046 * JSON Patch operations incrementally. 047 * 048 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonPatchBuilder> 049 * 050 * <BR /><BR />The following illustrates the approach. 051 * 052 * <BR /><DIV CLASS=SNIP>{@code 053 * JsonPatchBuilder builder = Json.createPatchBuilder(); 054 * 055 * JsonPatch patch = builder 056 * .add("/John/phones/office", "1234-567") 057 * .remove("/Amy/age") 058 * .build(); 059 * }</DIV> 060 * 061 * <BR /><BR />The result is equivalent to the following JSON Patch: 062 * 063 * <BR /><BR /><DIV STYLE='border: solid lightgray; border-width: 0.1em 0.1em 0.1em 0.8em; 064 * border-radius: 0.75em; background: black; color: lightgray; 065 * padding: 0.5em 1em; white-space: pre;'>{@code 066 * [ 067 * {"op" = "add", "path" = "/John/phones/office", "value" = "1234-567"}, 068 * {"op" = "remove", "path" = "/Amy/age"} 069 * ] 070 * }</DIV> 071 * 072 * @see <a target=_blank href="http://tools.ietf.org/html/rfc6902">RFC 6902</a> 073 * 074 * @since 1.1 075 */ 076public interface JsonPatchBuilder { 077 078 /** 079 * Adds an "add" JSON Patch operation. 080 * 081 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. 082 * @param value the "value" member of the operation 083 * @return this JsonPatchBuilder 084 */ 085 JsonPatchBuilder add(String path, JsonValue value); 086 087 /** 088 * Adds an "add" JSON Patch operation. 089 * 090 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. 091 * @param value the "value" member of the operation 092 * @return this JsonPatchBuilder 093 */ 094 JsonPatchBuilder add(String path, String value); 095 096 /** 097 * Adds an "add" JSON Patch operation. 098 * 099 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. 100 * @param value the "value" member of the operation 101 * @return this JsonPatchBuilder 102 */ 103 JsonPatchBuilder add(String path, int value); 104 105 /** 106 * Adds an "add" JSON Patch operation. 107 * 108 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. 109 * @param value the "value" member of the operation 110 * @return this JsonPatchBuilder 111 */ 112 JsonPatchBuilder add(String path, boolean value); 113 114 /** 115 * Adds a "remove" JSON Patch operation. 116 * 117 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. 118 * @return this JsonPatchBuilder 119 */ 120 JsonPatchBuilder remove(String path); 121 122 /** 123 * Adds a "replace" JSON Patch operation. 124 * 125 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer. 126 * @param value the "value" member of the operation 127 * @return this JsonPatchBuilder 128 */ 129 JsonPatchBuilder replace(String path, JsonValue value); 130 131 /** 132 * Adds a "replace" JSON Patch operation. 133 * 134 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 135 * @param value the "value" member of the operation 136 * @return this JsonPatchBuilder 137 */ 138 JsonPatchBuilder replace(String path, String value); 139 140 /** 141 * Adds a "replace" JSON Patch operation. 142 * 143 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 144 * @param value the "value" member of the operation 145 * @return this JsonPatchBuilder 146 */ 147 JsonPatchBuilder replace(String path, int value); 148 149 /** 150 * Adds a "replace" JSON Patch operation. 151 * 152 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 153 * @param value the "value" member of the operation 154 * @return this JsonPatchBuilder 155 */ 156 JsonPatchBuilder replace(String path, boolean value); 157 158 /** 159 * Adds a "move" JSON Patch operation. 160 * 161 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 162 * @param from the "from" member of the operation 163 * @return this JsonPatchBuilder 164 */ 165 JsonPatchBuilder move(String path, String from); 166 167 /** 168 * Adds a "copy" JSON Patch operation. 169 * 170 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 171 * @param from the "from" member of the operation 172 * @return this JsonPatchBuilder 173 */ 174 JsonPatchBuilder copy(String path, String from); 175 176 /** 177 * Adds a "test" JSON Patch operation. 178 * 179 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 180 * @param value the "value" member of the operation 181 * @return this JsonPatchBuilder 182 */ 183 JsonPatchBuilder test(String path, JsonValue value); 184 185 /** 186 * Adds a "test" JSON Patch operation. 187 * 188 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 189 * @param value the "value" member of the operation 190 * @return this JsonPatchBuilder 191 */ 192 JsonPatchBuilder test(String path, String value); 193 194 /** 195 * Adds a "test" JSON Patch operation. 196 * 197 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 198 * @param value the "value" member of the operation 199 * @return this JsonPatchBuilder 200 */ 201 JsonPatchBuilder test(String path, int value); 202 203 /** 204 * Adds a "test" JSON Patch operation. 205 * 206 * @param path the "path" member of the operation. Must be a valid escaped JSON-Pointer string. 207 * @param value the "value" member of the operation 208 * @return this JsonPatchBuilder 209 */ 210 JsonPatchBuilder test(String path, boolean value); 211 212 213 /** 214 * Returns the JSON Patch. 215 * 216 * @return a JSON Patch 217 */ 218 JsonPatch build(); 219 220}