- Download the latest release
- Read the Javadoc
- Check out the example code to get some idea of what this framework is about.
- Or add the maven dependency
<dependency> <groupId>com.github.jsonj</groupId> <artifactId>jsonj</artifactId> <version>0.8</version> </dependency>
JsonJ is a framework for working with json in Java the “proper” way. No mappings or model classes, it’s all just lovely json, but in Java.
JsonJ is optimized for working with json in a programmatic way rather than in a reflective/annotated domain object way. This means a json array is represented as a java.util.List, a dictionary is represented as a java.util.Map, etc.
The purpose of the JsonJ framework is to remove these barriers and allow you to write code that has a low amount of verbosity. I can’t change the language but I can bend the rules a little when it comes to maps and lists. The JsonJ framework simply extends LinkedHashMap and LinkedList to provide default implementations of json dictionaries and lists that implement APIs any java developer will be familiar with. Additionally, some convenience methods have been added to these classes to give you sensible hashcode and equals implementations, a deepClone method, as well as methods for manipulating the contents of the dictionary and list structures. Finally, a builder class is provided and of course the framework would not be complete without a good parser and pretty printing serializer.
- 0.9 fix several serialization bugs, array.addAll and the builder now play nice with collections, toString now serializes proper json (beware with using JsonPrimitive.toString() on json strings: they now include quotes!; use asString() instead).
- 0.8 fix escaping, npe fix John Goodwin merged, misc minor fixes
- 0.7 Add support for converting a json element to a dom tree so that things like xpath or xsl can be used on it
- 0.6 Support for deepCloning, object sorting added. Use String.intern() on object keys to optimize frequent operations on json objects.
- 0.5 Serializer and parser now properly escape and unescape string literals.
- 0.4 Bug fixes, changed groupid, documentation.
- 0.3 Several new methods added in JsonArray and JsonObject; fixed the parser bug where nested arrays and objects were not handled correctly.
- 0.2 Several bug fixes
- 0.1 First release
What’s with the name
It’s pronounced json-j, or jasonjay. It doesn’t mean anything in particular other than “json for java”, or something. Well, trying to come up with a name that is not already used is quite a challenge and I wanted to stuff the acronym json in there, keep it short, and not have the first hit on Google be something else than this. So, JsonJ it is.
Why another framework?
There are many frameworks for handling Json in java. So why create another one? From my point of view these frameworks are all flawed in one or more of the following ways:
- they assume the user has model classes that need to be serialized and deserialized to and from java
- they use an internal representation of the various json types that is not very friendly to work with if you want to manipulate them directly
- they don’t treat json as a first class entity and merely try to hide the fact that your data is stored as json
- they don’t use the Java collections framework
- they use final classes, so your options to work around any limitations are a bit limited.
Don’t get me wrong, some of these frameworks are excellent. And some of these frameworks are quite usable even if you do use them the way I want to use them.
However, from having used one of them extensively (GSon), I have learned that there is room for improvement. Since we’re talking the type of improvement that is likely backwards compatibility breaking (i.e. not very likely to be implemented in one of the existing frameworks), I went ahead and created my solution.
For who is this framework intended
Jsonj had a bit of a rocky start where especially the early versions had loads of bugs. I’ve basically ran into most of them and have been using it in a few projects. Most recent development has been about addressing very minor issues and adding new features. As of 0.8 it seems to work for most of what I do with it and I’m not aware of major open issues. I’ve processed many gigabytes of information with it and am fairly confident to have caught all major issues at this point. So, I might cut a 1.0 fairly soon.
Which version should I use?
The latest release or snapshot typically. Beyond the version number, there is not much difference between a release and a snapshot. I don’t bother with the ceremony for each commit. Seriously, the older versions have bugs that I know about and already fixed. Why take the risk? The head of the repository should be fine. If you prefer non snapshot releases, go for the latest tag. The release process I use is “release frequently and don’t keep working stuff unreleased”. My QA process is verifying I did not break any tests (in combination with good test coverage).
I found a bug, what should I do
File a bug on this github project, or just mail/im me directly. Either way, if I agree something is broken, I will fix it. Alternatively, feel free to clone & own. That’s what github is all about.
How to build JsonJ
mvn clean install should do the trick with maven 3.x (and probably 2.x as well). I’m not a big maven fan but this is a relatively trivial project and it’s just easier this way.
Where is the documentation?
The license is the MIT license, a.k.a. the expat license. The rationale for choosing this license is that I want to maximize your freedom to do whatever you want with the code while limiting my liability for the damage this code could potentially do. I do appreciate attribution but not enough to require it in the license (beyond the obligatory copyright notice).
- I’ve been greatly influenced by the classes representing the json primitives in the GSon framework. If only they implemented Map and List and weren’t final. But lovely framework and would use it again.
- I spend quite a bit of time figuring out a way of parsing Json that didn’t involve me generating a lot of source code with javacc, antlr or similar tools. Then I stumpled onto json-simple and wrote the parser for JsonJ in under two hours using a custom json-simple content handler. It seems to work and json-simple is pretty fast as well.
- This code is very loosely based on work I did at work with several colleagues. No code was copy pasted but I definitely took some ideas and improved on them. You know who you are. Thanks.