Package jakarta.json
Class Json
- java.lang.Object
-
- jakarta.json.Json
-
public final class Json extends Object
Factory class for creating JSON processing objects. This class provides the most commonly used methods for creating these objects and their corresponding factories. The factory classes provide all the various ways to create these objects.The methods in this class locate a provider instance using the method
JsonProvider.provider()
. This class uses the provider instance to create JSON processing objects.The following example shows how to create a JSON parser to parse an empty array:
StringReader reader = new StringReader("[]"); JsonParser parser = Json.createParser(reader);
All the methods in this class are safe for use by multiple concurrent threads.
-
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static JsonArrayBuilder
createArrayBuilder()
Creates a JSON array builderstatic JsonArrayBuilder
createArrayBuilder(JsonArray array)
Creates a JSON array builder, initialized with the specified arraystatic JsonArrayBuilder
createArrayBuilder(Collection<?> collection)
Creates a JSON array builder, initialized with the content of specifiedcollection
.static JsonBuilderFactory
createBuilderFactory(Map<String,?> config)
Creates a builder factory for creatingJsonArrayBuilder
andJsonObjectBuilder
objects.static JsonPatch
createDiff(JsonStructure source, JsonStructure target)
Generates a JSON Patch (RFC 6902) from the source and targetJsonStructure
.static JsonGenerator
createGenerator(OutputStream out)
Creates a JSON generator for writing JSON to a byte stream.static JsonGenerator
createGenerator(Writer writer)
Creates a JSON generator for writing JSON to a character stream.static JsonGeneratorFactory
createGeneratorFactory(Map<String,?> config)
Creates a generator factory for creatingJsonGenerator
objects.static JsonMergePatch
createMergeDiff(JsonValue source, JsonValue target)
Generates a JSON Merge Patch (RFC 7396) from the source and targetJsonValue
s which when applied to thesource
, yields thetarget
.static JsonMergePatch
createMergePatch(JsonValue patch)
Creates JSON Merge Patch (RFC 7396) from specifiedJsonValue
.static JsonObjectBuilder
createObjectBuilder()
Creates a JSON object builderstatic JsonObjectBuilder
createObjectBuilder(JsonObject object)
Creates a JSON object builder, initialized with the specified object.static JsonObjectBuilder
createObjectBuilder(Map<String,?> map)
Creates a JSON object builder, initialized with the data from specifiedmap
.static JsonParser
createParser(InputStream in)
Creates a JSON parser from a byte stream.static JsonParser
createParser(Reader reader)
Creates a JSON parser from a character stream.static JsonParserFactory
createParserFactory(Map<String,?> config)
Creates a parser factory for creatingJsonParser
objects.static JsonPatch
createPatch(JsonArray array)
Creates a JSON Patch (RFC 6902) from the specified operations.static JsonPatchBuilder
createPatchBuilder()
Creates a JSON Patch builder (RFC 6902).static JsonPatchBuilder
createPatchBuilder(JsonArray array)
Creates a JSON Patch builder (RFC 6902), initialized with the specified operations.static JsonPointer
createPointer(String jsonPointer)
Creates JSON Pointer (RFC 6901) from givenjsonPointer
string.static JsonReader
createReader(InputStream in)
Creates a JSON reader from a byte stream.static JsonReader
createReader(Reader reader)
Creates a JSON reader from a character stream.static JsonReaderFactory
createReaderFactory(Map<String,?> config)
Creates a reader factory for creatingJsonReader
objects.static JsonNumber
createValue(double value)
Creates a JsonNumber.static JsonNumber
createValue(int value)
Creates a JsonNumber.static JsonNumber
createValue(long value)
Creates a JsonNumber.static JsonNumber
createValue(Number value)
Creates a JsonNumber.static JsonString
createValue(String value)
Creates a JsonString.static JsonNumber
createValue(BigDecimal value)
Creates a JsonNumber.static JsonNumber
createValue(BigInteger value)
Creates a JsonNumber.static JsonWriter
createWriter(OutputStream out)
static JsonWriter
createWriter(Writer writer)
static JsonWriterFactory
createWriterFactory(Map<String,?> config)
Creates a writer factory for creatingJsonWriter
objects.static String
decodePointer(String escaped)
Decodes a passed JSON-pointer string as defined by RFC 6901.static String
encodePointer(String pointer)
Encodes (escapes) a passed string as defined by RFC 6901.
-
-
-
Method Detail
-
createParser
public static JsonParser createParser(Reader reader)
Creates a JSON parser from a character stream.- Parameters:
reader
- i/o reader from which JSON is to be read- Returns:
- a JSON parser
-
createParser
public static JsonParser createParser(InputStream in)
Creates a JSON parser from a byte stream. The character encoding of the stream is determined as specified in RFC 7159.- Parameters:
in
- i/o stream from which JSON is to be read- Returns:
- a JSON parser
- Throws:
JsonException
- if encoding cannot be determined or i/o error (IOException would be cause of JsonException)
-
createGenerator
public static JsonGenerator createGenerator(Writer writer)
Creates a JSON generator for writing JSON to a character stream.- Parameters:
writer
- a i/o writer to which JSON is written- Returns:
- a JSON generator
-
createGenerator
public static JsonGenerator createGenerator(OutputStream out)
Creates a JSON generator for writing JSON to a byte stream.- Parameters:
out
- i/o stream to which JSON is written- Returns:
- a JSON generator
-
createParserFactory
public static JsonParserFactory createParserFactory(Map<String,?> config)
Creates a parser factory for creatingJsonParser
objects. The factory is configured with the specified map of provider specific configuration properties. Provider implementations should ignore any unsupported configuration properties specified in the map.- Parameters:
config
- a map of provider specific properties to configure the JSON parsers. The map may be empty or null- Returns:
- JSON parser factory
-
createGeneratorFactory
public static JsonGeneratorFactory createGeneratorFactory(Map<String,?> config)
Creates a generator factory for creatingJsonGenerator
objects. The factory is configured with the specified map of provider specific configuration properties. Provider implementations should ignore any unsupported configuration properties specified in the map.- Parameters:
config
- a map of provider specific properties to configure the JSON generators. The map may be empty or null- Returns:
- JSON generator factory
-
createWriter
public static JsonWriter createWriter(Writer writer)
- Parameters:
writer
- to which JSON object or array is written- Returns:
- a JSON writer
-
createWriter
public static JsonWriter createWriter(OutputStream out)
Creates a JSON writer to write a JSONobject
orarray
structure to the specified byte stream. Characters written to the stream are encoded into bytes using UTF-8 encoding.- Parameters:
out
- to which JSON object or array is written- Returns:
- a JSON writer
-
createReader
public static JsonReader createReader(Reader reader)
Creates a JSON reader from a character stream.- Parameters:
reader
- a reader from which JSON is to be read- Returns:
- a JSON reader
-
createReader
public static JsonReader createReader(InputStream in)
Creates a JSON reader from a byte stream. The character encoding of the stream is determined as described in RFC 7159.- Parameters:
in
- a byte stream from which JSON is to be read- Returns:
- a JSON reader
-
createReaderFactory
public static JsonReaderFactory createReaderFactory(Map<String,?> config)
Creates a reader factory for creatingJsonReader
objects. The factory is configured with the specified map of provider specific configuration properties. Provider implementations should ignore any unsupported configuration properties specified in the map.- Parameters:
config
- a map of provider specific properties to configure the JSON readers. The map may be empty or null- Returns:
- a JSON reader factory
-
createWriterFactory
public static JsonWriterFactory createWriterFactory(Map<String,?> config)
Creates a writer factory for creatingJsonWriter
objects. The factory is configured with the specified map of provider specific configuration properties. Provider implementations should ignore any unsupported configuration properties specified in the map.- Parameters:
config
- a map of provider specific properties to configure the JSON writers. The map may be empty or null- Returns:
- a JSON writer factory
-
createArrayBuilder
public static JsonArrayBuilder createArrayBuilder()
Creates a JSON array builder- Returns:
- a JSON array builder
-
createArrayBuilder
public static JsonArrayBuilder createArrayBuilder(JsonArray array)
Creates a JSON array builder, initialized with the specified array- Parameters:
array
- the initial array in the builder- Returns:
- a JSON array builder
- Since:
- 1.1
-
createArrayBuilder
public static JsonArrayBuilder createArrayBuilder(Collection<?> collection)
Creates a JSON array builder, initialized with the content of specifiedcollection
. If the @{code collection} containsOptional
s then resulting JSON array builder contains the value from thecollection
only if theOptional
is not empty.- Parameters:
collection
- the initial data for the builder- Returns:
- a JSON array builder
- Throws:
IllegalArgumentException
- if the value from thecollection
cannot be converted to the correspondingJsonValue
- Since:
- 1.1
-
createObjectBuilder
public static JsonObjectBuilder createObjectBuilder()
Creates a JSON object builder- Returns:
- a JSON object builder
-
createObjectBuilder
public static JsonObjectBuilder createObjectBuilder(JsonObject object)
Creates a JSON object builder, initialized with the specified object.- Parameters:
object
- the initial object in the builder- Returns:
- a JSON object builder
- Since:
- 1.1
-
createObjectBuilder
public static JsonObjectBuilder createObjectBuilder(Map<String,?> map)
Creates a JSON object builder, initialized with the data from specifiedmap
. If the @{code map} containsOptional
s then resulting JSON object builder contains the key from themap
only if theOptional
is not empty.- Parameters:
map
- the initial object in the builder- Returns:
- a JSON object builder
- Throws:
IllegalArgumentException
- if the value from themap
cannot be converted to the correspondingJsonValue
- Since:
- 1.1
-
createPointer
public static JsonPointer createPointer(String jsonPointer)
Creates JSON Pointer (RFC 6901) from givenjsonPointer
string.- An empty
jsonPointer
string defines a reference to the target itself. - If the
jsonPointer
string is non-empty, it must be a sequence of '/
' prefixed tokens.
- Parameters:
jsonPointer
- the valid escaped JSON Pointer string- Returns:
- a JSON Pointer
- Throws:
NullPointerException
- ifjsonPointer
isnull
JsonException
- ifjsonPointer
is not a valid JSON Pointer- Since:
- 1.1
- An empty
-
createPatchBuilder
public static JsonPatchBuilder createPatchBuilder()
Creates a JSON Patch builder (RFC 6902).- Returns:
- a JSON Patch builder
- Since:
- 1.1
-
createPatchBuilder
public static JsonPatchBuilder createPatchBuilder(JsonArray array)
Creates a JSON Patch builder (RFC 6902), initialized with the specified operations.- Parameters:
array
- the initial patch operations- Returns:
- a JSON Patch builder
- Since:
- 1.1
-
createPatch
public static JsonPatch createPatch(JsonArray array)
Creates a JSON Patch (RFC 6902) from the specified operations.- Parameters:
array
- patch operations- Returns:
- a JSON Patch
- Since:
- 1.1
-
createDiff
public static JsonPatch createDiff(JsonStructure source, JsonStructure target)
Generates a JSON Patch (RFC 6902) from the source and targetJsonStructure
. The generated JSON Patch need not be unique.- Parameters:
source
- the sourcetarget
- the target, must be the same type as the source- Returns:
- a JSON Patch which when applied to the source, yields the target
- Since:
- 1.1
-
createMergePatch
public static JsonMergePatch createMergePatch(JsonValue patch)
Creates JSON Merge Patch (RFC 7396) from specifiedJsonValue
.- Parameters:
patch
- the patch- Returns:
- a JSON Merge Patch
- Since:
- 1.1
-
createMergeDiff
public static JsonMergePatch createMergeDiff(JsonValue source, JsonValue target)
Generates a JSON Merge Patch (RFC 7396) from the source and targetJsonValue
s which when applied to thesource
, yields thetarget
.- Parameters:
source
- the sourcetarget
- the target- Returns:
- a JSON Merge Patch
- Since:
- 1.1
-
createBuilderFactory
public static JsonBuilderFactory createBuilderFactory(Map<String,?> config)
Creates a builder factory for creatingJsonArrayBuilder
andJsonObjectBuilder
objects. The factory is configured with the specified map of provider specific configuration properties. Provider implementations should ignore any unsupported configuration properties specified in the map.- Parameters:
config
- a map of provider specific properties to configure the JSON builders. The map may be empty or null- Returns:
- a JSON builder factory
-
createValue
public static JsonString createValue(String value)
Creates a JsonString.- Parameters:
value
- a JSON string- Returns:
- the JsonString for the string
- Since:
- 1.1
-
createValue
public static JsonNumber createValue(int value)
Creates a JsonNumber.- Parameters:
value
- a JSON number- Returns:
- the JsonNumber for the number
- Since:
- 1.1
-
createValue
public static JsonNumber createValue(long value)
Creates a JsonNumber.- Parameters:
value
- a JSON number- Returns:
- the JsonNumber for the number
- Since:
- 1.1
-
createValue
public static JsonNumber createValue(double value)
Creates a JsonNumber.- Parameters:
value
- a JSON number- Returns:
- the JsonNumber for the number
- Since:
- 1.1
-
createValue
public static JsonNumber createValue(BigDecimal value)
Creates a JsonNumber.- Parameters:
value
- a JSON number- Returns:
- the JsonNumber for the number
- Since:
- 1.1
-
createValue
public static JsonNumber createValue(BigInteger value)
Creates a JsonNumber.- Parameters:
value
- a JSON number- Returns:
- the JsonNumber for the number
- Since:
- 1.1
-
encodePointer
public static String encodePointer(String pointer)
Encodes (escapes) a passed string as defined by RFC 6901. This method doesn't validate the passed JSON-pointer string.- Parameters:
pointer
- the JSON-pointer string to encode- Returns:
- encoded JSON-pointer string
- Since:
- 1.1
-
decodePointer
public static String decodePointer(String escaped)
Decodes a passed JSON-pointer string as defined by RFC 6901. This method doesn't validate the passed JSON-pointer string.- Parameters:
escaped
- the JSON-pointer string to decode- Returns:
- decoded JSON-pointer string
- Since:
- 1.1
-
createValue
public static JsonNumber createValue(Number value)
Creates a JsonNumber.- Parameters:
value
- a JSON number- Returns:
- the JsonNumber for the number
- Since:
- 2.1
-
-