java-json

Java 7+/Android JSON parser/generator, MIT (c) 2020-2025 @miktim

Release notes:

Java SE 7+/Android RFC 8259 compliant package (see: https://datatracker.ietf.org/doc/rfc8259/?include_text=1 ).
- no external dependencies;
- JSON literals and arrays of mixed type are allowed.

The jar ./dist/java-json-... file was generated with debugging info using JDK 8 for target JRE 7.

Further in the text:
- “JSON” means text in JSON format;
- “Json” means the Java representation of a JSON object.

package org.miktim.json

 Overview:

The class JSON contains static methods for parsing/generating text in JSON format. Parser converts JSON to package native objects: Json ( the Java representation of a JSON object ), String, Number, Boolean, null, Object[ ] - an array of the listed types. The JSON generator accepts any Java object, all Java primitives and their arrays.

Instances of Java classes can be converted to Json objects (usually empty) using Json.converter.

The JsonObject abstract class and JsonConvertible interface use the JavaScript-like replacer/reviver tool to convert object instance to or from Json object.

Class JSON

This class contains static parsing/generating methods.
Parser converts JSON to package native objects. When the names within an JSON object are not unique, the parser stores last value only.
The JSON generator accept any Java object, all Java primitives and their arrays. JSON text exchanged between systems MUST be encoded using UTF-8 (default charset).

 Methods:

static Object fromJSON ( String jsonText ) throws IOException, ParseException
Parse JSON text to a native objects.

static Object fromJSON ( InputStream in, String charsetName ) throws IOException, ParseException
Parse JSON text from an input stream with the specified encoding

static String toJSON ( Object obj ) throws IOException;
Serializes a Java object instance as a single-line text in JSON format

static String toJSON ( Object obj, int space ) throws IOException
Generate a Java object as JSON text with the specified number of spaces in the line indentation.

static <T>T toJSON ( T obj, OutputStream out, int space ) throws IOException
Serializes a Java object as JSON text into a UTF-8 stream with the specified indentation. Returns obj.

static <T>T toJSON ( T obj, OutputStream out, int space, String charsetName ) throws IOException
Serializes a Java object as JSON text into a stream with the specified indentation and encoding. Returns obj.

Methods for converting or copying Java objects. Notes:
- the sample object must be initialized;
- arrays must have the same dimension;
- casting numbers may involve rounding or truncation;
- casting null to primitive returns empty array or initial value;
- casting to null returns null.

static <T> T cast ( T sample, Object obj ) throws ClassCastException
Casting a Java Object to the sample Class

static <T> T cast ( Class <T> cls, Object obj ) throws ClassCastException
Casting a Java object to the cls Class

 Example:

Class Json extends HashMap <String, Object>

This class is a Java representation of a JSON object. Json member types: Json, String, Number, Boolean, null, Object[ ] - an array of the listed types.

Put, set notes:
- Json object setters accept any Java object, all Java primitives and their arrays;
- RFC 8259 does not recommend using Java BigDecimal and BigInteger as JSON values;
- AVOID RECURSION ! ;
- the put, set methods cast Java primitives into corresponding objects: Number, Boolean or String for chars;
- Java arrays are stored as:
int[ ][ ] as Object[ ] { Object[ ] { Number, ... }, Object[ ] { Number, ... } }, String[ ] as Object[ ] { String, ... }

 Constructors:

Json ( )
Default constructor.

Json ( Object... members ) throws IndexOutOfBoundsException
Members is a name,value pairs

Json ( String jsonText ) throws IOException, ParseException
Create Json object from String

Json ( InputStream inStream ) throws IOException, ParseException
Create Json object from UTF-8 encoded stream.

 Example:

 Methods:

String[ ] listNames ( )
Returns a list of member names of this Json object.

boolean exists ( String memberName, int... indices )
Returns true if there is a member or an element of the member array

Object put ( String memberName, Object value );
Overriden. Create or replace Json member.

Json set ( String memberName, Object value );
Create or replace Json member. Returns this.

Object get( String memberName );
Inherited. Get Json member value or null.

Object remove ( String memberName );
Inherited

Getters returns null if the Json memeber does not exist.

Object get ( String memberName, int... indices ) throws IndexOutOfBoundsException
Returns null, the value of the Json member, or an array element

Json getJson ( String memberName, int... indices ) throws ClassCastException, IndexOutOfBoundsException
Returns a nested Json object.

String getString ( String memberName, int... indices ) throws ClassCastException, IndexOutOfBoundsException
Casts member or array element to String

Number getNumber ( String memberName, int... indices ) throws ClassCastException, IndexOutOfBoundsException
Casts member or array element to Number

Boolean getBoolean ( String memberName, int... indices ) throws ClassCastException, IndexOutOfBoundsException
Casts member or array element to Boolean

Object[ ] getArray ( String memberName, int... indices ) throws ClassCastException, IndexOutOfBoundsException
Casts member to array of Objects

<T> T castMember ( T sample, String memberName, int... indices ) throws ClassCastException, IndexOutOfBoundsException
Converts the value of a Json member or an array element to the sample class. See notes for a JSON.cast methods.

<T> T castMember ( Class <T> cls, String memberName, int... indices ) throws ClassCastException, IndexOutOfBoundsException
Converts the value of a Json member or an array element to the specified class. See notes for a JSON.cast methods.

String toString ( )
Overridden. Returns JSON text as single line

String toJSON ( )
Stringify Json object as single line

String toJSON ( String memberName, int... indices )
Stringify member value or array element as single line

Json toJSON ( OutputStream outStream ) throws IOException
Output UTF-8 encoded single line JSON text to outStream. Returns this.

 Example:

Static Json.converter

Used to convert existing instances of Java objects to/from a Json object.
Only the visible fields are converted. The converter ignores the final and transient fields.

 Methods:

Json toJson ( Object targetObj ) throws ClassCastException
Returns a Json object from the target object

<T> T fromJson ( T targetObj, Json jsonObj ) throws ClassCastException
Loads Json to target object. Returns target object.

 Example:

Interface JsonConvertible

The JsonConvertible interface provides JavaScript-like methods for converting Java object into or from Json object. Notes:
- visibility of object fields as from the object constructor (including the privates);
- Java transient and final fields are ignored;
- it is strongly recommended to initialize the convertible fields;
- requires a public default constructor.

 Constants:

static final Object IGNORE
Returned from the replacer/reviver methods to disable conversion by default.

 Methods:

Object replacer ( String name, Object value );
Called for each field when uploading to a Json object:
- name is object field class and name delimited with colon ( : ), value is object field value;
- the first call with the class name of this object and this object as the value;
- returns the parameter value for default conversion, Json-supported object or IGNORE.

Object reviver ( String name, Object value );
Сalled for each field when loading from a Json object:
- name is object field class and name delimited with colon ( : ), value is Json-supported object;
- the first call with the class name of this object and the Json object as the value;
- returns the parameter value for default conversion, field-compatible object or IGNORE.

 Example:

Abstract class JsonObject implements JsonConvertible

The JsonObject abstract class provides JavaScript-like methods for converting Java object into or from Json object. Notes:
- visibility of object fields as from the object constructor (including the privates);
- Java transient and final fields are ignored;
- it is strongly recommended to initialize the convertible fields;
- requires a public default constructor.

 Constants:

static final Object IGNORE
Returned from the replacer/reviver methods to disable conversion by defailt.

 Methods:

Object replacer ( String name, Object value );
Object reviver ( String name, Object value );
See JsonConvertible interface.

Json toJson ( );
Returns a Json object from this object

<T> T fromJson ( Json jsonObj );
Loads Json to this object. Returns this object.

String toString ( );
Overridden. Generate JSON text as a single line

 Example:

See also:
https://www.baeldung.com/java-json
https://www.json.org/json-en.html