source: josm/trunk/src/javax/json/Json.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: 18.4 KB
Line 
1/*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright (c) 2011-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
43import java.io.InputStream;
44import java.io.OutputStream;
45import java.io.Reader;
46import java.io.Writer;
47import java.math.BigDecimal;
48import java.math.BigInteger;
49import java.util.Collection;
50import java.util.Map;
51import java.util.Optional;
52import javax.json.spi.JsonProvider;
53import javax.json.stream.JsonGenerator;
54import javax.json.stream.JsonGeneratorFactory;
55import javax.json.stream.JsonParser;
56import javax.json.stream.JsonParserFactory;
57
58/**
59 * Factory class for creating JSON processing objects.
60 * This class provides the most commonly used methods for creating these
61 * objects and their corresponding factories. The factory classes provide
62 * all the various ways to create these objects.
63 *
64 * <p>
65 * The methods in this class locate a provider instance using the method
66 * {@link JsonProvider#provider()}. This class uses the provider instance
67 * to create JSON processing objects.
68 *
69 * <p>
70 * The following example shows how to create a JSON parser to parse
71 * an empty array:
72 * <pre>
73 * <code>
74 * StringReader reader = new StringReader("[]");
75 * JsonParser parser = Json.createParser(reader);
76 * </code>
77 * </pre>
78 *
79 * <p>
80 * All the methods in this class are safe for use by multiple concurrent
81 * threads.
82 */
83public final class Json {
84
85 private Json() {
86 }
87
88 /**
89 * Creates a JSON parser from a character stream.
90 *
91 * @param reader i/o reader from which JSON is to be read
92 * @return a JSON parser
93 */
94 public static JsonParser createParser(Reader reader) {
95 return JsonProvider.provider().createParser(reader);
96 }
97
98 /**
99 * Creates a JSON parser from a byte stream.
100 * The character encoding of the stream is determined as specified in
101 * <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
102 *
103 * @param in i/o stream from which JSON is to be read
104 * @throws JsonException if encoding cannot be determined
105 * or i/o error (IOException would be cause of JsonException)
106 * @return a JSON parser
107 */
108 public static JsonParser createParser(InputStream in) {
109 return JsonProvider.provider().createParser(in);
110 }
111
112 /**
113 * Creates a JSON generator for writing JSON to a character stream.
114 *
115 * @param writer a i/o writer to which JSON is written
116 * @return a JSON generator
117 */
118 public static JsonGenerator createGenerator(Writer writer) {
119 return JsonProvider.provider().createGenerator(writer);
120 }
121
122 /**
123 * Creates a JSON generator for writing JSON to a byte stream.
124 *
125 * @param out i/o stream to which JSON is written
126 * @return a JSON generator
127 */
128 public static JsonGenerator createGenerator(OutputStream out) {
129 return JsonProvider.provider().createGenerator(out);
130 }
131
132 /**
133 * Creates a parser factory for creating {@link JsonParser} objects.
134 *
135 * @return JSON parser factory.
136 *
137 public static JsonParserFactory createParserFactory() {
138 return JsonProvider.provider().createParserFactory();
139 }
140 */
141
142 /**
143 * Creates a parser factory for creating {@link JsonParser} objects.
144 * The factory is configured with the specified map of provider specific
145 * configuration properties. Provider implementations should ignore any
146 * unsupported configuration properties specified in the map.
147 *
148 * @param config a map of provider specific properties to configure the
149 * JSON parsers. The map may be empty or null
150 * @return JSON parser factory
151 */
152 public static JsonParserFactory createParserFactory(Map<String, ?> config) {
153 return JsonProvider.provider().createParserFactory(config);
154 }
155
156 /**
157 * Creates a generator factory for creating {@link JsonGenerator} objects.
158 *
159 * @return JSON generator factory
160 *
161 public static JsonGeneratorFactory createGeneratorFactory() {
162 return JsonProvider.provider().createGeneratorFactory();
163 }
164 */
165
166 /**
167 * Creates a generator factory for creating {@link JsonGenerator} objects.
168 * The factory is configured with the specified map of provider specific
169 * configuration properties. Provider implementations should ignore any
170 * unsupported configuration properties specified in the map.
171 *
172 * @param config a map of provider specific properties to configure the
173 * JSON generators. The map may be empty or null
174 * @return JSON generator factory
175 */
176 public static JsonGeneratorFactory createGeneratorFactory(
177 Map<String, ?> config) {
178 return JsonProvider.provider().createGeneratorFactory(config);
179 }
180
181 /**
182 * Creates a JSON writer to write a
183 * JSON {@link JsonObject object} or {@link JsonArray array}
184 * structure to the specified character stream.
185 *
186 * @param writer to which JSON object or array is written
187 * @return a JSON writer
188 */
189 public static JsonWriter createWriter(Writer writer) {
190 return JsonProvider.provider().createWriter(writer);
191 }
192
193 /**
194 * Creates a JSON writer to write a
195 * JSON {@link JsonObject object} or {@link JsonArray array}
196 * structure to the specified byte stream. Characters written to
197 * the stream are encoded into bytes using UTF-8 encoding.
198 *
199 * @param out to which JSON object or array is written
200 * @return a JSON writer
201 */
202 public static JsonWriter createWriter(OutputStream out) {
203 return JsonProvider.provider().createWriter(out);
204 }
205
206 /**
207 * Creates a JSON reader from a character stream.
208 *
209 * @param reader a reader from which JSON is to be read
210 * @return a JSON reader
211 */
212 public static JsonReader createReader(Reader reader) {
213 return JsonProvider.provider().createReader(reader);
214 }
215
216 /**
217 * Creates a JSON reader from a byte stream. The character encoding of
218 * the stream is determined as described in
219 * <a href="http://tools.ietf.org/rfc/rfc7159.txt">RFC 7159</a>.
220 *
221 * @param in a byte stream from which JSON is to be read
222 * @return a JSON reader
223 */
224 public static JsonReader createReader(InputStream in) {
225 return JsonProvider.provider().createReader(in);
226 }
227
228 /**
229 * Creates a reader factory for creating {@link JsonReader} objects.
230 * The factory is configured with the specified map of provider specific
231 * configuration properties. Provider implementations should ignore any
232 * unsupported configuration properties specified in the map.
233 *
234 * @param config a map of provider specific properties to configure the
235 * JSON readers. The map may be empty or null
236 * @return a JSON reader factory
237 */
238 public static JsonReaderFactory createReaderFactory(Map<String, ?> config) {
239 return JsonProvider.provider().createReaderFactory(config);
240 }
241
242 /**
243 * Creates a writer factory for creating {@link JsonWriter} objects.
244 * The factory is configured with the specified map of provider specific
245 * configuration properties. Provider implementations should ignore any
246 * unsupported configuration properties specified in the map.
247 *
248 * @param config a map of provider specific properties to configure the
249 * JSON writers. The map may be empty or null
250 * @return a JSON writer factory
251 */
252 public static JsonWriterFactory createWriterFactory(Map<String, ?> config) {
253 return JsonProvider.provider().createWriterFactory(config);
254 }
255
256 /**
257 * Creates a JSON array builder
258 *
259 * @return a JSON array builder
260 */
261 public static JsonArrayBuilder createArrayBuilder() {
262 return JsonProvider.provider().createArrayBuilder();
263 }
264
265 /**
266 * Creates a JSON array builder, initialized with the specified array
267 *
268 * @param array the initial array in the builder
269 * @return a JSON array builder
270 *
271 * @since 1.1
272 */
273 public static JsonArrayBuilder createArrayBuilder(JsonArray array) {
274 return JsonProvider.provider().createArrayBuilder(array);
275 }
276
277 /**
278 * Creates a JSON array builder, initialized with the content of specified {@code collection}.
279 * If the @{code collection} contains {@link Optional}s then resulting JSON array builder
280 * contains the value from the {@code collection} only if the {@link Optional} is not empty.
281 *
282 * @param collection the initial data for the builder
283 * @return a JSON array builder
284 * @exception IllegalArgumentException if the value from the {@code collection} cannot be converted
285 * to the corresponding {@link JsonValue}
286 *
287 * @since 1.1
288 */
289 public static JsonArrayBuilder createArrayBuilder(Collection<?> collection) {
290 return JsonProvider.provider().createArrayBuilder(collection);
291 }
292
293 /**
294 * Creates a JSON object builder
295 *
296 * @return a JSON object builder
297 */
298 public static JsonObjectBuilder createObjectBuilder() {
299 return JsonProvider.provider().createObjectBuilder();
300 }
301
302 /**
303 * Creates a JSON object builder, initialized with the specified object.
304 *
305 * @param object the initial object in the builder
306 * @return a JSON object builder
307 *
308 * @since 1.1
309 */
310 public static JsonObjectBuilder createObjectBuilder(JsonObject object) {
311 return JsonProvider.provider().createObjectBuilder(object);
312 }
313
314 /**
315 * Creates a JSON object builder, initialized with the data from specified {@code map}.
316 * If the @{code map} contains {@link Optional}s then resulting JSON object builder
317 * contains the key from the {@code map} only if the {@link Optional} is not empty.
318 *
319 * @param map the initial object in the builder
320 * @return a JSON object builder
321 * @exception IllegalArgumentException if the value from the {@code map} cannot be converted
322 * to the corresponding {@link JsonValue}
323 *
324 * @since 1.1
325 */
326 public static JsonObjectBuilder createObjectBuilder(Map<String, Object> map) {
327 return JsonProvider.provider().createObjectBuilder(map);
328 }
329
330 /**
331 * Creates JSON Pointer (<a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>)
332 * from given {@code jsonPointer} string.
333 * <ul>
334 * <li>An empty {@code jsonPointer} string defines a reference to the target itself.</li>
335 * <li>If the {@code jsonPointer} string is non-empty, it must be a sequence of '{@code /}' prefixed tokens.</li>
336 * </ul>
337 *
338 * @param jsonPointer the valid escaped JSON Pointer string
339 * @throws NullPointerException if {@code jsonPointer} is {@code null}
340 * @throws JsonException if {@code jsonPointer} is not a valid JSON Pointer
341 * @return a JSON Pointer
342 *
343 * @since 1.1
344 */
345 public static JsonPointer createPointer(String jsonPointer) {
346 return JsonProvider.provider().createPointer(jsonPointer);
347 }
348
349 /**
350 * Creates a JSON Patch builder (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>).
351 *
352 * @return a JSON Patch builder
353 *
354 * @since 1.1
355 */
356 public static JsonPatchBuilder createPatchBuilder() {
357 return JsonProvider.provider().createPatchBuilder();
358 }
359
360 /**
361 * Creates a JSON Patch builder
362 * (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>),
363 * initialized with the specified operations.
364 *
365 * @param array the initial patch operations
366 * @return a JSON Patch builder
367 *
368 * @since 1.1
369 */
370 public static JsonPatchBuilder createPatchBuilder(JsonArray array) {
371 return JsonProvider.provider().createPatchBuilder(array);
372 }
373
374 /**
375 * Creates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
376 * from the specified operations.
377 *
378 * @param array patch operations
379 * @return a JSON Patch
380 *
381 * @since 1.1
382 */
383 public static JsonPatch createPatch(JsonArray array) {
384 return JsonProvider.provider().createPatch(array);
385 }
386
387 /**
388 * Generates a JSON Patch (<a href="http://tools.ietf.org/html/rfc6902">RFC 6902</a>)
389 * from the source and target {@code JsonStructure}.
390 * The generated JSON Patch need not be unique.
391 *
392 * @param source the source
393 * @param target the target, must be the same type as the source
394 * @return a JSON Patch which when applied to the source, yields the target
395 *
396 * @since 1.1
397 */
398 public static JsonPatch createDiff(JsonStructure source, JsonStructure target) {
399 return JsonProvider.provider().createDiff(source, target);
400 }
401
402 /**
403 * Creates JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
404 * from specified {@code JsonValue}.
405 *
406 * @param patch the patch
407 * @return a JSON Merge Patch
408 *
409 * @since 1.1
410 */
411 public static JsonMergePatch createMergePatch(JsonValue patch) {
412 return JsonProvider.provider().createMergePatch(patch);
413 }
414
415 /**
416 * Generates a JSON Merge Patch (<a href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>)
417 * from the source and target {@code JsonValue}s
418 * which when applied to the {@code source}, yields the {@code target}.
419 *
420 * @param source the source
421 * @param target the target
422 * @return a JSON Merge Patch
423 *
424 * @since 1.1
425 */
426 public static JsonMergePatch createMergeDiff(JsonValue source, JsonValue target) {
427 return JsonProvider.provider().createMergeDiff(source, target);
428 }
429
430 /**
431 * Creates a builder factory for creating {@link JsonArrayBuilder}
432 * and {@link JsonObjectBuilder} objects.
433 * The factory is configured with the specified map of provider specific
434 * configuration properties. Provider implementations should ignore any
435 * unsupported configuration properties specified in the map.
436 *
437 * @param config a map of provider specific properties to configure the
438 * JSON builders. The map may be empty or null
439 * @return a JSON builder factory
440 */
441 public static JsonBuilderFactory createBuilderFactory(
442 Map<String, ?> config) {
443 return JsonProvider.provider().createBuilderFactory(config);
444 }
445
446 /**
447 * Creates a JsonString.
448 *
449 * @param value a JSON string
450 * @return the JsonString for the string
451 *
452 * @since 1.1
453 */
454 public static JsonString createValue(String value) {
455 return JsonProvider.provider().createValue(value);
456 }
457
458 /**
459 * Creates a JsonNumber.
460 *
461 * @param value a JSON number
462 * @return the JsonNumber for the number
463 *
464 * @since 1.1
465 */
466 public static JsonNumber createValue(int value) {
467 return JsonProvider.provider().createValue(value);
468 }
469
470 /**
471 * Creates a JsonNumber.
472 *
473 * @param value a JSON number
474 * @return the JsonNumber for the number
475 *
476 * @since 1.1
477 */
478 public static JsonNumber createValue(long value) {
479 return JsonProvider.provider().createValue(value);
480 }
481
482 /**
483 * Creates a JsonNumber.
484 *
485 * @param value a JSON number
486 * @return the JsonNumber for the number
487 *
488 * @since 1.1
489 */
490 public static JsonNumber createValue(double value) {
491 return JsonProvider.provider().createValue(value);
492 }
493
494 /**
495 * Creates a JsonNumber.
496 *
497 * @param value a JSON number
498 * @return the JsonNumber for the number
499 *
500 * @since 1.1
501 */
502 public static JsonNumber createValue(BigDecimal value) {
503 return JsonProvider.provider().createValue(value);
504 }
505
506 /**
507 * Creates a JsonNumber.
508 *
509 * @param value a JSON number
510 * @return the JsonNumber for the number
511 *
512 * @since 1.1
513 */
514 public static JsonNumber createValue(BigInteger value) {
515 return JsonProvider.provider().createValue(value);
516 }
517
518 /**
519 * Encodes (escapes) a passed string as defined by <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>.
520 * This method doesn't validate the passed JSON-pointer string.
521 *
522 * @param pointer the JSON-pointer string to encode
523 * @return encoded JSON-pointer string
524 *
525 * @since 1.1
526 */
527 public static String encodePointer(String pointer) {
528 return pointer.replace("~", "~0").replace("/", "~1");
529 }
530
531 /**
532 * Decodes a passed JSON-pointer string as defined by <a href="http://tools.ietf.org/html/rfc6901">RFC 6901</a>.
533 * This method doesn't validate the passed JSON-pointer string.
534 *
535 * @param escaped the JSON-pointer string to decode
536 * @return decoded JSON-pointer string
537 *
538 * @since 1.1
539 */
540 public static String decodePointer(String escaped) {
541 return escaped.replace("~1", "/").replace("~0", "~");
542 }
543
544}
Note: See TracBrowser for help on using the repository browser.