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}