Source code

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