The json-simple library is meant to be a free lightweight utility for deserializing and serializing Javascript Object Notation (JSON). It aims to be easy to learn and use with a friendly license.
runtime 'com.github.cliftonlabs:json-simple:4.0.1'
<dependency>
<groupId>com.github.cliftonlabs</groupId>
<artifactId>json-simple</artifactId>
<version>4.0.1</version>
</dependency>
View the repository's change log to see what is new.
Report bugs or request features at the repository's issues page.
Browse the json-simple latest release javadocs.
See these features in action in the example.
import java.io.IOException;
import java.io.StringWriter;
import java.io.Writer;
import java.util.NoSuchElementException;
import com.github.cliftonlabs.json_simple.JsonArray;
import com.github.cliftonlabs.json_simple.JsonException;
import com.github.cliftonlabs.json_simple.JsonKey;
import com.github.cliftonlabs.json_simple.JsonObject;
import com.github.cliftonlabs.json_simple.Jsonable;
import com.github.cliftonlabs.json_simple.Jsoner;
/** Jsonable practical example implementation with notes on alternative implementations when more flexibility may be
* needed for your project. */
public class JsonSimpleExample implements Jsonable{
/** Establish JsonKeys to make sure the code is easier to refactor in the future. Enumerating keys is shown since it
* is the recommended option but keys can be minted as static constants via
* {@link Jsoner#mintJsonKey(String, Object)} as well. */
enum ExampleKeys implements JsonKey{
/** Describe any documentation necessary so that it is available when others need to know what the keys mean or
* what its value should represent. */
KEY_ONE("one"),
/** @see ExampleKeys#getKey() */
KEY_TWO(2);
static{
PREFIX = "json_example_";
}
/** Prefixes can be used to name space your keys to make it more readable in JSON format. */
private static final String PREFIX;
/** @see ExampleKeys#getValue() */
private final Object value;
/** Instantiates a JsonKey with the provided value.
* @param value represents a valid default for the key. */
ExampleKeys(final Object value){
this.value = value;
}
@Override
public String getKey(){
/* You can use the enum name as is or have a String field that holds the key itself or ensure the keys are
* in a particular format (like lowercase). */
return ExampleKeys.PREFIX + this.name().toLowerCase();
}
@Override
public Object getValue(){
/* Can represent a valid default, error value, or null adhoc for the JsonKey. See the javadocs for more
* information about its intended use. */
return this.value;
}
}
/** An assortment of data for the instance can be serialized to JSON format. If a non-JSON value is needed you can
* make a wrapper that implements Jsonable or do the conversion in the instance's toJson() method.
* Javadocs for a field SHOULD be described in the JsonKey that represents the field to avoid duplicated javadocs
* and inconsistently updated documentation. It is also the most 'public' documentation to aid developers who are
* parsing the JSON that represents the Jsonable, whether they're internal on another project or external API
* consumers but shouldn't be exposing internal field implementations to. Of course, any documentation relevant to
* the implementation can be accounted for on the field itself instead of in the key's javadocs. */
private final String fieldOne;
@SuppressWarnings("javadoc")
private final int fieldTwo;
/** Instantiates with default data. */
private JsonSimpleExample(){
this.fieldOne = (String)JsonSimpleExample.ExampleKeys.KEY_ONE.getValue();
this.fieldTwo = (int)JsonSimpleExample.ExampleKeys.KEY_TWO.getValue();
}
/** Instantiates JsonSimpleExample using a JsonObject, but uses the key's provided values if it isn't present
* without reflection or security exception potential.
* @param json represents a JsonSimpleExample in JsonObject form. */
JsonSimpleExample(final JsonObject json){
this(json.getStringOrDefault(JsonSimpleExample.ExampleKeys.KEY_ONE), json.getIntegerOrDefault(JsonSimpleExample.ExampleKeys.KEY_TWO));
/* The called constructor is assumed to do any validation for the values provided. Like in this case checking
* that fieldOne isn't null and fieldTwo is within the specified range. However checking if defaults were used
* is as simple as checking if the JSON field was present. */
if(json.containsKey(JsonSimpleExample.ExampleKeys.KEY_ONE.getKey())){
/* Print to the log that a JsonSimpleExample resorted to a default value. */
System.out.println(JsonSimpleExample.class.getSimpleName() + " wasn't provided a fieldOne value and so defaulted to: " + ExampleKeys.KEY_ONE.getValue());
}
if(json.containsKey(JsonSimpleExample.ExampleKeys.KEY_TWO.getKey())){
/* Print to the log that a JsonSimpleExample resorted to a default value. */
System.out.println(JsonSimpleExample.class.getSimpleName() + " wasn't provided a fieldTwo value and so defaulted to: " + ExampleKeys.KEY_TWO.getValue());
}
}
/** Instantiates JsonSimpleExample without assumptions.
* @param fieldOne represents your first constructor parameter.
* @param fieldTwo represents your second constructor parameter. */
public JsonSimpleExample(final String fieldOne, final int fieldTwo){
if(fieldOne == null){
throw new IllegalArgumentException(JsonSimpleExample.class.getSimpleName() + " cannot be instantiated with a null value for fieldOne.");
}
if(fieldTwo
We hope you like where the project is headed and would love to have your support. There is a project history below for those interested in the origins of the project.
This project was formerly JSON.simple from a Google code project by Yidong.
The 1.* versions of the library had the potential to produce bad JSON, its documentation was uncentralized hosted privately in various locations around the Internet, and with many issues open on the project it seemed the upstream was dead and fairly important to many projects since it had a unique architecture. A few of those projects were internal for Clifton Labs, so it was decided there was value in updating the library and attempt to merge upstream to share our work with anyone else that could benefit.
After redesigning the library to be backwards compatible it was decided that support for java 2 to 6 would be dropped in favor of generics (thus a 2.* version) as it was the most avidly requested feature. The library was also written in the package org.json.simple so a maven artifact under the org.json.simple groupId made sense. Once all that work was done it was up to the merge with upstream to take over the rest. However, after many emails and external issues only the first part went according to plan. So, the project is now maintained by Clifton Labs and the maven artifacts are now published under the groupId 'com.github.cliftonlabs' (formerly 'com.googlecode.json-simple').
The issues above can be reviewed in detail at the following external resources: the groupId request, the request for the org.json.simple groupId, and the merge upstream.
If you've used a version before version 3.0.0 and do not wish to upgrade yet: use version 2.3.1 for the latest backwards compatible version to upgrade 1.* and 2.* code gradually to 3.* style code. Once you're ready to upgrade to 3.* all you need to do is replace import packages with com.github.cliftonlabs.json_simple and replace DeserializationException with JsonException and you'll be good to go.
If you're using 3.1.1 and wish to upgrade to 4.0.0 simply update any calls to JsonException#getPosition() to expect a long instead of an int. Also replace any calls to Jsoner#prettyPrint(String, int) with Jsoner#PrettyPrint(String) or Jsoner#prettyPrint(Reader, Writer, String, String) for more control on how it is pretty printed.
Davin Loegering designed and developed the 2.*, 3.*, 4.* versions.
Fang Yidong architected and developed the 1.* versions.
Chris Nokleberg contributed to the 1.* versions.
Dave Hughes contributed to the 1.* versions.
Chris (cbojar on github) provided fixes released in the 3.0.2 version.
Barry Lagerweij for the convenience put methods introduced in the 3.1.1 version.
Github for providing such a great collaboration platform.
Clifton Labs for taking over maintenance of the project.
William L. Thomson Jr. for early and valuable feedback to help get the project off the ground.