README.md

jsonwriter

A Java library to write JSON with or without pretty printing. The library has no runtime dependencies on any JSON processing package.

Usage

The library is available from Maven Central using the following Maven dependency:

<dependency>
  <groupId>org.cthing</groupId>
  <artifactId>jsonwriter</artifactId>
  <version>2.0.0</version>
</dependency>

or the following Gradle dependency:

implementation("org.cthing:jsonwriter:2.0.0")

Getting Started

To begin writing JSON, create an instance of a JsonWriter. The instance is not thread safe. Naming of the methods follows that used in IETF RFC-8259: The JavaScript Object Notation (JSON) Data Interchange Format.

Writing an Object

The following are examples of writing a JSON object. Note the use of the fluent API.

Simple object showing two ways to create a member:

final JsonWriter writer = new JsonWriter();
writer.setPrettyPrint(true);
writer.startObject()
      .member("foo", "bar")    // Key and value in one call
      .member("joe", 12)
      .member("abc")           // Key
      .value(true)             // Value
      .endObject();

JSON written:

{
    "foo": "bar",
    "joe": 12,
    "abc": true
}

Two ways to create nested objects:

final JsonWriter writer = new JsonWriter();
writer.setPrettyPrint(true);
writer.startObject()
      .member("abc")                // Key for the object
      .startObject()                // Start object for "abc"
      .member("def", "hello")
      .endObject()
      .memberStartObject("xyz")     // Start object with key
      .member("hij", 23)
      .endObject()
      .endObject();

JSON written:

{
    "abc": {
        "def": "hello"
    },
    "xyz": {
        "hij": 23
    }
}

Writing an Array

The following are examples of writing a JSON array.

Simple array:

final JsonWriter writer = new JsonWriter();
writer.setPrettyPrint(true);
writer.startArray()
      .value("bar")
      .value(12)
      .value(true)
      .endArray();

JSON written:

[
    "bar",
    12,
    true
]

Array with nested array and object:

final JsonWriter writer = new JsonWriter();
writer.setPrettyPrint(true);
writer.startArray()
      .startObject()
      .member("def", "hello")
      .endObject()
      .startArray()
      .value(23)
      .endArray()
      .endArray();

JSON written:

[
    {
        "def": "hello"
    },
    [
        23
    ]
]

Detailed Usage

See the Javadoc in the JsonWriter class for detailed usage and configuration information.

Building

The library is compiled for Java 17. If a Java 17 toolchain is not available, one will be downloaded.

Gradle is used to build the library:

./gradlew build

The Javadoc for the library can be generated by running:

./gradlew javadoc

Releasing

This project is released on the Maven Central repository. Perform the following steps to create a release.

• Commit all changes for the release
• In the build.gradle.kts file, edit the ProjectVersion object
  • Set the version for the release. The project follows semantic versioning.
  • Set the build type to BuildType.release
• Commit the changes
• Wait until CI builds the release candidate
• Run the command mkrelease jsonwriter <version>
• In a browser go to the Maven Central Repository Manager
• Log in
• Use the Staging Upload to upload the generated artifact bundle jsonwriter-bundle-<version>.jar
• Click on Staging Repositories
• Once it is enabled, press Release to release the artifacts to Maven Central
• Log out
• Wait for the new release to be available on Maven Central
• In a browser, go to the project on GitHub
• Generate a release with the tag <version>
• In the build.gradle.kts file, edit the ProjectVersion object
  • Increment the version patch number
  • Set the build type to BuildType.snapshot
• Update the CHANGELOG.md with the changes in the release and prepare for next release changes
• Update the Usage section in the README.md with the latest artifact release version
• Commit these changes