Package rife.json

Class Json

java.lang.Object

rife.json.Json

public final class Json
extends Object

The Json class provides JSON parsing, generation and bean conversion.

Parsing is strict according to RFC 8259 and produces plain Java values: JsonObject, JsonArray, String, Long, Double, Boolean and null. Integral numbers that don't fit into a Long become Double values, which means that they can lose precision. When an object contains the same member name multiple times, the last value wins.

For instance:

 var config = Json.parseObject("""
     {"name": "my-app", "port": 8080}""");
 var port = config.getInt("port", 80);
 

Beans are converted in both directions with from(java.lang.Object) and toBean(rife.json.JsonObject, java.lang.Class<T>), relying on the same property conventions as the rest of RIFE2. Records are converted through their components in the same fashion.

Since:

1.10

See Also:

• JsonObject
• JsonArray

Method Summary

Modifier and Type	Method	Description
static JsonObject	from(Object bean)	Creates a JSON object from the properties of a bean.
static JsonArray	from(Collection<?> elements)	Creates a JSON array from the elements of a collection.
static JsonObject	fromExcluded(Object bean, String... excludedProperties)	Creates a JSON object from the properties of a bean, excluding particular properties.
static Object	parse(Reader reader)	Parses a JSON document from a reader.
static Object	parse(String json)	Parses a JSON document.
static JsonArray	parseArray(Reader reader)	Parses a JSON document from a reader that is expected to be a JSON array.
static JsonArray	parseArray(String json)	Parses a JSON document that is expected to be a JSON array.
static JsonObject	parseObject(Reader reader)	Parses a JSON document from a reader that is expected to be a JSON object.
static JsonObject	parseObject(String json)	Parses a JSON document that is expected to be a JSON object.
static <T> T	toBean(JsonObject json, Class<T> beanClass)	Fills a new bean instance with the members of a JSON object.
static <T> List<T>	toBeanList(JsonArray json, Class<T> beanClass)	Fills a list of new bean instances with the members of the JSON objects in a JSON array.
static String	toPrettyString(Object value)	Serializes any JSON value into its multi-line indented string representation.
static String	toString(Object value)	Serializes any JSON value into its compact string representation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

parse

public static Object parse(String json)

Parses a JSON document.

This method will parse any JSON document and hand you back whichever value sits at the top level of it.

Parameters:

json - the JSON document to parse

Returns:

the parsed value: a JsonObject, JsonArray, String, Long, Double, Boolean or null

Throws:

JsonParseException - when the document couldn't be parsed

Since:

1.10

See Also:

• parse(Reader)
• parseObject(String)
• parseArray(String)

parse

public static Object parse(Reader reader)
                    throws IOException

Parses a JSON document from a reader.

The reader will be read out entirely before the parsing starts.

Parameters:

reader - the reader to parse the JSON document from

Returns:

the parsed value

Throws:

JsonParseException - when the document couldn't be parsed

IOException - when an error occurred while reading

Since:

1.10

See Also:

• parse(String)
• parseObject(Reader)
• parseArray(Reader)

parseObject

public static JsonObject parseObject(String json)

Parses a JSON document that is expected to be a JSON object.

This method will refuse any document whose top-level value isn't a JSON object, so that you don't have to check the type of the result yourself.

Parameters:

json - the JSON document to parse

Returns:

the parsed JsonObject

Throws:

JsonParseException - when the document couldn't be parsed or isn't a JSON object

Since:

1.10

See Also:

• parse(String)
• parseObject(Reader)
• parseArray(String)

parseObject

public static JsonObject parseObject(Reader reader)
                              throws IOException

Parses a JSON document from a reader that is expected to be a JSON object.

The reader will be read out entirely before the parsing starts.

Parameters:

reader - the reader to parse the JSON document from

Returns:

the parsed JsonObject

Throws:

JsonParseException - when the document couldn't be parsed or isn't a JSON object

IOException - when an error occurred while reading

Since:

1.10

See Also:

• parse(Reader)
• parseObject(String)
• parseArray(Reader)

parseArray

public static JsonArray parseArray(String json)

Parses a JSON document that is expected to be a JSON array.

This method will refuse any document whose top-level value isn't a JSON array, so that you don't have to check the type of the result yourself.

Parameters:

json - the JSON document to parse

Returns:

the parsed JsonArray

Throws:

JsonParseException - when the document couldn't be parsed or isn't a JSON array

Since:

1.10

See Also:

• parse(String)
• parseArray(Reader)
• parseObject(String)

parseArray

public static JsonArray parseArray(Reader reader)
                            throws IOException

Parses a JSON document from a reader that is expected to be a JSON array.

The reader will be read out entirely before the parsing starts.

Parameters:

reader - the reader to parse the JSON document from

Returns:

the parsed JsonArray

Throws:

JsonParseException - when the document couldn't be parsed or isn't a JSON array

IOException - when an error occurred while reading

Since:

1.10

See Also:

• parse(Reader)
• parseArray(String)
• parseObject(Reader)

from

public static JsonObject from(Object bean)

Creates a JSON object from the properties of a bean.

Properties that are constrained as not serialized are not included. Records are converted through their components instead of through their properties.

Parameters:

bean - the bean to convert

Returns:

the JSON object with the bean's properties as members

Since:

1.10

See Also:

• fromExcluded(Object, String...)
• from(Collection)
• toBean(JsonObject, Class)

fromExcluded

public static JsonObject fromExcluded(Object bean,
 String... excludedProperties)

Creates a JSON object from the properties of a bean, excluding particular properties.

This method behaves exactly like from(Object), apart from the properties whose names you provide, which are left out of the resulting JSON object.

Parameters:

bean - the bean to convert

excludedProperties - the names of the properties to exclude

Returns:

the JSON object with the bean's properties as members

Since:

1.10

See Also:

• from(Object)

from

public static JsonArray from(Collection<?> elements)

Creates a JSON array from the elements of a collection.

The beans and records that are amongst the elements are converted to JSON objects, just like from(Object) does.

Parameters:

elements - the collection to convert

Returns:

the JSON array with the converted elements

Since:

1.10

See Also:

• from(Object)
• toBeanList(JsonArray, Class)

toString

public static String toString(Object value)

Serializes any JSON value into its compact string representation.

This method accepts strings, numbers, booleans, null, maps, collections, arrays, dates, temporals, enums, JsonObject, JsonArray, and beans or records, including the beans that are nested inside maps, collections and arrays, since those are automatically converted with from(java.lang.Object).

Parameters:

value - the value to serialize

Returns:

the JSON string

Since:

1.10

See Also:

• toPrettyString(Object)

toPrettyString

public static String toPrettyString(Object value)

Serializes any JSON value into its multi-line indented string representation.

This method accepts the same values as toString(Object).

Parameters:

value - the value to serialize

Returns:

the pretty-printed JSON string

Since:

1.10

See Also:

• toString(Object)

toBean

public static <T> T toBean(JsonObject json,
 Class<T> beanClass)

Fills a new bean instance with the members of a JSON object.

Members without a matching bean property are ignored, while nested JSON objects are converted to the types of their matching bean properties. The elements of arrays, collections and maps are converted to the component and generic types that the property setters declare.

Properties that are constrained as not serialized or not editable are never filled in.

Records are instantiated through their canonical constructor with the members that match their components, while members that are absent become null or the primitive default values.

Parameters:

json - the JSON object with the values to fill in

beanClass - the class of the bean to fill

Returns:

the filled bean instance

Since:

1.10

See Also:

• toBeanList(JsonArray, Class)
• from(Object)

toBeanList

public static <T> List<T> toBeanList(JsonArray json,
 Class<T> beanClass)

Fills a list of new bean instances with the members of the JSON objects in a JSON array.

Each element is converted with the same rules as toBean(rife.json.JsonObject, java.lang.Class<T>), while elements that are null stay null.

Parameters:

json - the JSON array with the JSON objects to convert

beanClass - the class of the beans to fill

Returns:

the list with a bean instance for each element

Since:

1.10

See Also:

• toBean(JsonObject, Class)
• from(Collection)