Interface JSONBuilder

All Known Implementing Classes:

JSONBuilderImpl

@ClassVersion(sourceVersion="$Id: JSONBuilder.java 1258 2026-06-04 18:33:06Z tquadrat $")
@API(status=STABLE,
     since="0.25.0")
public sealed interface JSONBuilder
permits JSONBuilderImpl

This sealed interface is the main API for the Foundation JSON Builder Library.

getInstance() returns an instance of an implementation for the interface.

Basically, the instances of JSONBuilder are stateless, and therefore they can be treated as thread-safe. Only the indentation that is used for pretty-printing the resulting JSON values may cause issues when different threads are using different values.

The different implementations of JSONValue – particularly JSONObject and JSONArray are not thread-safe.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: JSONBuilder.java 1258 2026-06-04 18:33:06Z tquadrat $

Since:

0.25.0

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.jsonbuilder.JSONBuilder"

⁠

Field Summary

Fields

Modifier and Type	Field	Description
static final int	DEFAULT_INDENTATION	The indentation that is used when a JSONValue is formatted: 2.
static final String	JSONField_Unit	The name of the JSON String that holds the unit for the dimension from a DimensionedValue: "Unit".
static final String	JSONField_Value	The name of the JSON Number that holds the value from a DimensionedValue: "Value".

Method Summary

Modifier and Type	Method	Description
default JSONArray	copyArray(JSONArray source)	Returns a deep copy of the given JSON array.
default JSONObject	copyObject(JSONObject source)	Returns a deep copy of the given JSON object.
JSONArray	createArray()	Returns a new empty instance of JSONArray.
default JSONArray	createArray(double[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(float[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(int elementCount)	Returns a new instance of JSONArray with the given number of elements, all set to JSONLiteral.NULL.
default JSONArray	createArray(int[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(long[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(Double[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(Float[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(Integer[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(Long[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(String... values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(BigDecimal[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(BigInteger[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
default JSONArray	createArray(Supplier<JSONValue[]> supplier)	Returns a new instance of JSONArray that is populated with the return value from the given Supplier<JSONValue []>.
default JSONArray	createArray(JSONValue[] values)	Returns a new instance of JSONArray that is populated with the values from the given array.
JSONObject	createObject()	Returns a new empty instance of JSONObject.
default JSONObject	createObject(Collection<String> names, Function<String, JSONValue> provider)	Returns a new instance of JSONObject that is populated with the values returned by the given Function.
int	getIndentation()	Returns the indentation that is used when a JSONValue is formatted.
static JSONBuilder	getInstance()	Creates an instance of JSONBuilder.
void	setIndentation(int value)	Sets the indentation that is used when a JSONValue is formatted for pretty-printing.
default JSONLiteral	valueOf(boolean value)	Returns a JSONValue instance that represents the given boolean value.
JSONNumber	valueOf(double value)	Returns a JSONValue instance that represents the given double value.
JSONNumber	valueOf(float value)	Returns a JSONValue instance that represents the given float value.
JSONNumber	valueOf(int value)	Returns a JSONValue instance that represents the given int value.
JSONNumber	valueOf(long value)	Returns a JSONValue instance that represents the given long value.
JSONNumber	valueOf(Double value)	Returns a JSONValue instance that represents the given Double value.
JSONNumber	valueOf(Float value)	Returns a JSONValue instance that represents the given Float value.
JSONNumber	valueOf(Integer value)	Returns a JSONValue instance that represents the given Integer value.
JSONNumber	valueOf(Long value)	Returns a JSONValue instance that represents the given Long value.
JSONString	valueOf(String value)	Returns a JSONValue instance that represents the given String value.
JSONNumber	valueOf(BigDecimal value)	Returns a JSONValue instance that represents the given BigDecimal value.
JSONNumber	valueOf(BigInteger value)	Returns a JSONValue instance that represents the given BigInteger value.
default <T extends Dimension> JSONObject	valueOf(DimensionedValue<T> value, T targetUnit)	Returns a JSONValue instance (more precisely, an instance of JSONObject) that represents the given DimensionedValue instance.
default JSONLiteral	valueOfNull()	Returns a JSONValue instance that represents the null value.

Field Details

DEFAULT_INDENTATION

static final int DEFAULT_INDENTATION

The indentation that is used when a JSONValue is formatted: 2.

See Also:

• JSONValue.formatTo(Formatter,int,int,int)
• Constant Field Values

JSONField_Unit

static final String JSONField_Unit

The name of the JSON String that holds the unit for the dimension from a DimensionedValue: "Unit".

See Also:

• valueOf(DimensionedValue,Dimension)
• Constant Field Values

JSONField_Value

static final String JSONField_Value

The name of the JSON Number that holds the value from a DimensionedValue: "Value".

See Also:

• valueOf(DimensionedValue,Dimension)
• Constant Field Values

Method Details

copyArray

default JSONArray copyArray(JSONArray source)

Returns a deep copy of the given JSON array.

Parameters:

source - The array to copy.

Returns:

The deep copy.

copyObject

default JSONObject copyObject(JSONObject source)

Returns a deep copy of the given JSON object.

Parameters:

source - The object to copy.

Returns:

The deep copy.

createArray

JSONArray createArray()

Returns a new empty instance of JSONArray.

Returns:

The new array.

createArray

default JSONArray createArray(int elementCount)

Returns a new instance of JSONArray with the given number of elements, all set to JSONLiteral.NULL.

Parameters:

elementCount - The number of elements for the new array.

Returns:

The new array.

createArray

default JSONArray createArray(BigDecimal[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(BigInteger[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(double[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(Double[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(float[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(Float[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(int[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(Integer[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(JSONValue[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(long[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(Long[] values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createArray

default JSONArray createArray(Supplier<JSONValue[]> supplier)

Returns a new instance of JSONArray that is populated with the return value from the given Supplier<JSONValue []>.

Parameters:

supplier - The supplier for the array.

Returns:

The new array.

createArray

default JSONArray createArray(String... values)

Returns a new instance of JSONArray that is populated with the values from the given array.

Parameters:

values - The values.

Returns:

The new array.

createObject

JSONObject createObject()

Returns a new empty instance of JSONObject.

Returns:

The new object.

createObject

default JSONObject createObject(Collection<String> names,
 Function<String, JSONValue> provider)

Returns a new instance of JSONObject that is populated with the values returned by the given Function.

The function's argument is the name of the new member, provided by the names argument to this method.

Parameters:

names - The member names for the new object.

provider - The function that returns the value for the member with the given name.

Returns:

The new object.

getIndentation

int getIndentation()

Returns the indentation that is used when a JSONValue is formatted. If not set explicitly through a call to setIndentation(int), the default value (2) will be returned.

Returns:

The indentation.

See Also:

• DEFAULT_INDENTATION
• JSONValue.formatTo(Formatter,int,int,int)

setIndentation

void setIndentation(int value)

Sets the indentation that is used when a JSONValue is formatted for pretty-printing.

Parameters:

value - The indentation.

See Also:

• JSONValue.formatTo(Formatter,int,int,int)

getInstance

static JSONBuilder getInstance()

Creates an instance of JSONBuilder.

Each call to this method will return a new instance of JSONBuilder.

Returns:

A new instance of JSONBuilder.

valueOf

JSONNumber valueOf(BigDecimal value)

Returns a JSONValue instance that represents the given BigDecimal value.

Parameters:

value - The value.

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(BigInteger value)

Returns a JSONValue instance that represents the given BigInteger value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

default JSONLiteral valueOf(boolean value)

Returns a JSONValue instance that represents the given boolean value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

default <T extends Dimension> JSONObject valueOf(DimensionedValue<T> value,
 T targetUnit)

Returns a JSONValue instance (more precisely, an instance of JSONObject) that represents the given DimensionedValue instance.

The member names are "Unit" for the dimension, and "Value" for the numerical value.

Type Parameters:

T - The type of the dimension for the value.

Parameters:

value - The value.

targetUnit - The dimension for the output.

Returns:

The resulting JSON object.

valueOf

JSONNumber valueOf(double value)

Returns a JSONValue instance that represents the given double value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(Double value)

Returns a JSONValue instance that represents the given Double value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(float value)

Returns a JSONValue instance that represents the given float value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(Float value)

Returns a JSONValue instance that represents the given Float value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(int value)

Returns a JSONValue instance that represents the given int value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(Integer value)

Returns a JSONValue instance that represents the given Integer value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(long value)

Returns a JSONValue instance that represents the given long value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONNumber valueOf(Long value)

Returns a JSONValue instance that represents the given Long value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOf

JSONString valueOf(String value)

Returns a JSONValue instance that represents the given String value.

Parameters:

value - The value

Returns:

The JSON value that represents the given value.

valueOfNull

default JSONLiteral valueOfNull()

Returns a JSONValue instance that represents the null value.

Returns:

The JSON value that represents null.