io microsphere json JSONStringer

JSONStringer

Type: Class | Module: microsphere-java-core | Package: io.microsphere.json

Source: microsphere-java-core/src/main/java/io/microsphere/json/JSONStringer.java

Overview

Implements JSONObject#toString and JSONArray#toString. Most application developers should use those methods directly and disregard this API.

Example Usage

`JSONObject object = ...
String json = object.toString();
`

Stringers only encode well-formed JSON strings. In particular:

• The stringer must have exactly one top-level array or object.
• Lexical scopes must be balanced: every call to #array must have a matching call to #endArray and every call to #object must have a matching call to #endObject.
• Arrays may not contain keys (property names).
• Objects must alternate keys (property names) and values.
• Values are inserted with either literal #value(Object) value calls, or by nesting arrays or objects.

Calls that would result in a malformed JSON string will fail with a JSONException.

This class provides no facility for pretty-printing (ie. indenting) output. To encode indented output, use JSONObject#toString(int) or JSONArray#toString(int).

Some implementations of the API support at most 20 levels of nesting. Attempts to create more than 20 levels of nesting may fail with a JSONException.

Each stringer may be used to encode a single top level value. Instances of this class are not thread safe. Although this class is nonfinal, it was not designed for inheritance and should not be subclassed. In particular, self-use by overrideable methods is not specified. See Effective Java Item 17, "Design and Document or inheritance or else prohibit it" for further information.

Declaration

public class JSONStringer

Version Information

• Introduced in: 0.1.10-SNAPSHOT (current)
• Current Project Version: 0.1.10-SNAPSHOT

Version Compatibility

This component is tested and compatible with the following Java versions:

Java Version	Status
Java 8	✅ Compatible
Java 11	✅ Compatible
Java 17	✅ Compatible
Java 21	✅ Compatible
Java 25	✅ Compatible

Examples

JSONObject object = ...
String json = object.toString();

Usage

Maven Dependency

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.microsphere-projects</groupId>
    <artifactId>microsphere-java-core</artifactId>
    <version>${microsphere-java.version}</version>
</dependency>

Tip: Use the BOM (microsphere-java-dependencies) for consistent version management. See the Getting Started guide.

Import

import io.microsphere.json.JSONStringer;

API Reference

Public Methods

Method	Description
array	The output data, containing at most one top-level array or object.
endArray	Ends encoding the current array.
object	Begins encoding a new object. Each call to this method must be paired with a call
endObject	Ends encoding the current object.
value	Enters a new scope by appending any necessary whitespace and the given bracket.
value	Encodes value to this stringer.
value	Encodes value to this stringer.
value	Encodes value to this stringer.
key	Encodes the key (property name) to this stringer.

Method Details

array

public JSONStringer array()

The output data, containing at most one top-level array or object. / final StringBuilder out = new StringBuilder();

/** Lexical scoping elements within this stringer, necessary to insert the appropriate separator characters (i.e. commas and colons) and to detect nesting errors. / enum Scope {

/** An array with no elements requires no separators or newlines before it is closed. / EMPTY_ARRAY,

/** An array with at least one value requires a comma and newline before the next element. / NONEMPTY_ARRAY,

/** An object with no keys or values requires no separators or newlines before it is closed. / EMPTY_OBJECT,

/** An object whose most recent element is a key. The next element must be a value. / DANGLING_KEY,

/** An object with at least one name/value pair requires a comma and newline before the next element. / NONEMPTY_OBJECT,

/** A special bracketless array needed by JSONStringer.join() and JSONObject.quote() only. Not used for JSON encoding. / NULL

}

/** Unlike the original implementation, this stack isn't limited to 20 levels of nesting. / private final List stack = new ArrayList<>();

/** A string containing a full set of spaces for a single level of indentation, or null for no pretty printing. / private final String indent;

public JSONStringer() { this(0); }

public JSONStringer(int indentSpaces) { if (indentSpaces > 0) { char[] indentChars = new char[indentSpaces]; fill(indentChars, ' '); this.indent = new String(indentChars); } else { this.indent = null; } }

/** Begins encoding a new array. Each call to this method must be paired with a call to #endArray.

object

public JSONStringer object()

Begins encoding a new object. Each call to this method must be paired with a call to #endObject.

value

public JSONStringer value(Object value)

Enters a new scope by appending any necessary whitespace and the given bracket.

---

This documentation was auto-generated from the source code of microsphere-java.