- Single universal type - everything is a
Json, no type casting
- Single factory method, no new operators, just call
- Fast, hand-coded parsing
- Designed as a general purpose data structure for use in Java
- Parent pointers and
upmethod to traverse the JSON structure
- Concise methods to read (
Json.at), modify (
Json.add), duplicate (
Json.dup), merge (
- Methods for type-check (e.g.
Json.isString()) and access to underlying Java value (e.g.
- Method chaining
- Pluggable factory to build your own support for arbitrary Java<->Json mapping
- 1 Java file is the whole library with no external dependencies
Get in touch if you want to help!
- Traversal API, with pattern-matching
- JSON Schema supports for validation and template generation
It is in Maven central, so add this to your pom.xml if you are using Maven:
<groupId>org.sharegov</groupId> <artifactId>mjson</artifactId> <version>1.2</version>
You can also simply get the Json.java from the GitHub project and include it in your project. Or download a jar build from:Direct link to mjson-1.2.jar at Maven Central
This will walk you through all API methods by functional areas: A Tour of the API Wiki
To start using this library, you only need to glance at the example and method description on the Javadoc:
The library is called mjson for "minimal JSON". The source code is a single Java file (also included in the distribution jar). Some of it was ripped off from other projects and credit and licensing notices are included in the appropriate places. The license is Apache 2.0.
The goal of this library is to offer a simple API to work with JSON structures, directly, minimizing the burdens of Java's static typing and minimizing the programmer's typing (pun intended).
To do that, we emulate dynamic typing by unifying all the different JSON entities into a single type called Json. Different kinds of Json entities (primitives, arrays, objects, null) are implemented as sub-classes (privately nested) of Json, but they all share the exact same set of declared operations and to the outside world, there's only one type. Most mutating operations return this which allows for a method chaining. Constructing the correct concrete entities is done by factory methods, one of them called make which is a "do it all" constructor that takes any Java object and converts it into a Json. Warning: only primitives, arrays, collections and maps are supported by default. Handling Java bean mappings can be done by customizing the factory methods - there's an interface for that called
As a result of this strategy, coding involves no type casts, much fewer intermediary variables, much simpler navigation through a JSON structure, no new operator every time you want to add an element to a structure, no dealing with a multitude of concrete types. Overall, it makes life easier in the current era of JSON-based REST services, when implemented in Java that is.
In a sense, we are flipping the argument from the blog Dynamic Languages Are Static Languages and making use of the universal type idea in a static language. Java already has a universal type called Object, but it doesn't have many useful operations. Because the number of possible JSON concrete types is small and well-defined, taking the union of all their interfaces works well here. Whenever an operation doesn't make sense, it will throw an UnsupportedOperationException. But this is fine. We are dynamic, we can guarantee we are calling the right operation for the right concrete type. Otherwise, the tests would fail!
import mjson.Json; Json x = Json.object().set("name", "mjson") .set("version", "1.0") .set("cost", 0.0) .set("alias", Json.array("json", "minimal json")); x.at("name").asString(); // return mjson as a Java String x.at("alias").at(1); // returns "minimal json" as a Json instance x.at("alias").up().at("cost").asDouble(); // returns 0.0 String s = x.toString(); // get string representation x.equals(Json.read(s)); // parse back and compare => true
For more, read the Javadoc at the link above. No point in repeating it here.
We are at an official release of version 1.2 with 1.3 being in the works. Suggestions for further enhancements are welcome! Besides some simple nice-to-haves, such as pretty printing or the ability to stream to an OutputStream, pre-packaged Java bean mappings might turn out to be justified after all. Also, jQuery style selectors and a richer set of manipulation operations. Lambdas in Java 8 certainly open interesting API possibilities. For now, we are keeping it simple. The main use case is if you don't have a Java object model for the structured data you want to work with, you don't want such a model, or you don't want it to be mapped exactly and faithfully as a JSON structure.