<commit_before>h1. Introduction

JsonJ is a framework for working with json in Java the "proper" way without mappings or model classes. This means a json array is represented as a java.util.List, a dictionary is represented as a java.util.Map, etc. 

Just think about it, the whole point of json is a straightforward serialization and deserialization of simple, native data structures consisting of primitives, lists and dictionaries that you will find in a lot of languages other than Java. In Java things are slightly more complicated because lists and dictionaries are mere classes rather than native types. This means for example that you have to deal with generics; you may want to pick alternate implementations of the Map interface or skip that altogether and instead use a completely different framework. For that reason, dealing with json in Java is a lot less straightforward than it would be in for example Ruby, Python, or Javascript.

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 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, I find them lacking in usability. JsonJ is my attempt to fix this and deliver a highly usable framework that enables you to write code that has a low amount of verbosity and that gets out of the way. 

h1. Features

The purpose of the JsonJ framework is to allow you to write code that has a low amount of verbosity. 

h2. Design overview

JsonJ provides a few classes that extend Java's Collections framework. Extending the Collections framework means using a familiar, and powerful API that most Java coders already know how to use. The following classes are provided:
* public class JsonObject implements Map<String,JsonElement>, JsonElement
* public class JsonArray extends LinkedList<JsonElement> implements JsonElement
* public class JsonPrimitive implements JsonElement

These three classes provide a type safe alternative to simply using generic maps/lists of Objects since everything implements JsonElement. Each of the classes provides useful implementations of toString, hash, and equals.

The JsonElement interface specifies methods that allow you to do easy type checks and to convert to Java native type (when needed).

JsonObject uses a LinkedHashMap internally and JsonArray extends LinkedList. This ensures that the order of the elements doesn't change arbitrarily.

To conserve memory, Stings and JsonObject keys are represented as utf8 byte arrays internally rather than the 16 bit characters Java uses for Strings. Especially when working with large amounts of json in memory, this can make a large difference of up to nearly 50% of memory (depending on the language).

h2. Parsing and serialization

* A thread safe JsonParser class is provided.
* You can serialize using JsonElement.toString(), JsonElement.prettyPrint(), or using the JsonSerializer class.

h2. JsonBuilder

To facilitate creation of json elements, a builder class is included that makes creation of nested json object structures as easy as it gets in Java. It is recommended to use static imports and to add this class as a favorite in eclipse to facilitate autocompletion.

The builder class also provides methods to facilitate converting from existing Maps, Lists, and other objects. The fromObject method takes any Java object and tries to do the right thing.

h2. JRuby integration

A small jruby script is provided that dynamically extends JsonObject, JsonArray, Hash, and Array with methods to convert between JsonElement and native ruby types. This makes working with jsonj a breeze and is useful when interacting with Java business logic that expects/returns jsonj objects from jruby.

h1. Changelog

* 1.3
** Promote asInt,asDouble,asBoolean from JsonPrimitive to JsonElement for convenience.
* 1.2 - Use utf8 byte arrays to conserve memory
** String values are now represented as UTF8 byte arrays rather than 16 bit characters
** EfficientString is used for JsonObject keys. 
** JsonElement now has a new serialize method that serializes straight to an OutputStream. JsonSerializer now has a new serialize method to utilize this.
** The String serialize(..) method now uses the new efficient serialization if pretty printing is turned off
* 1.1 - minor feature added
** Added first and last convenience methods to JsonAray 
* 1.0 - only one change relative to 0.9
** Fixed JsonArray.equals to be more strict
* 0.9 - big release with many new features that resulted from months of using jsonj in my own project
** fixes several serialization bugs; serialization and parsing is now very robust
** 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).
** added prettyPrint method to JsonElement that returns a pretty printed string representation of the element (uses JsonSerializer)
** added a fromObject method to the builder that handles nested maps and lists and converts those to json
** added methods to JsonArray to convert to native double, int, or string arrays
** added asString, asDouble, asInt methods to JsonElement so that you don't have to chain asPrimitive().asString() anymore.
** added a *jsonj.rb* script that integrates JsonJ into jruby and allows you to convert back and forth between JsonElement and jruby's Hash and Array native types.
* 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

h1. 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.


h1. FAQ

h2. For who is this framework intended

Anyone who plans to write a lot of business logic in Java that manipulates json data structures and who doesn't wish to write model classes in Java to hide the fact that json is being used. If you are like me, you feel somewhat stuck having to deal with awkward json frameworks while all the cool Ruby,Python, and Javascript kids get to use a serialization that is natively supported in their language. This framework is for you.

h2. Which version should I use?

The latest release or snapshot typically. Releases are tagged in git and I deploy artifacts to my own git repository. 
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. 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. Don't be afraid to ask me to create a new release if there are recent commits that you would like to see released.

h2. 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.

h2. How to build JsonJ

@mvn clean install@ should do the trick with maven 3.x (and probably 2.x as well). 

If you like to use pre-built jars, you can utilize my private maven repository as explained "here":http://www.jillesvangurp.com/2013/02/27/maven-and-my-github-projects/


h2. Where is the documentation?

Javadoc is generated during the build. After building you can find it in @./target/apidocs/index.html@

Additionally, look at the  tests. Particularly "*this one here*":https://github.com/jillesvangurp/JsonJ/blob/master/src/test/java/com/github/JsonJ/ShowOffTheFramework.java shows off most of the features this framework has.

h1. License

The license is the "MIT license":http://en.wikipedia.org/wiki/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).

h1. Acknowledgements

# 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.<commit_msg>release documentation<commit_after>h1. Introduction

JsonJ is a framework for working with json in Java the "proper" way without mappings or model classes. This means a json array is represented as a java.util.List, a dictionary is represented as a java.util.Map, etc. 

Just think about it, the whole point of json is a straightforward serialization and deserialization of simple, native data structures consisting of primitives, lists and dictionaries that you will find in a lot of languages other than Java. In Java things are slightly more complicated because lists and dictionaries are mere classes rather than native types. This means for example that you have to deal with generics; you may want to pick alternate implementations of the Map interface or skip that altogether and instead use a completely different framework. For that reason, dealing with json in Java is a lot less straightforward than it would be in for example Ruby, Python, or Javascript.

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 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, I find them lacking in usability. JsonJ is my attempt to fix this and deliver a highly usable framework that enables you to write code that has a low amount of verbosity and that gets out of the way. 

h1. Features

The purpose of the JsonJ framework is to allow you to write code that has a low amount of verbosity. 

h2. Design overview

JsonJ provides a few classes that extend Java's Collections framework. Extending the Collections framework means using a familiar, and powerful API that most Java coders already know how to use. The following classes are provided:
* public class JsonObject implements Map<String,JsonElement>, JsonElement
* public class JsonArray extends LinkedList<JsonElement> implements JsonElement
* public class JsonPrimitive implements JsonElement

These three classes provide a type safe alternative to simply using generic maps/lists of Objects since everything implements JsonElement. Each of the classes provides useful implementations of toString, hash, and equals.

The JsonElement interface specifies methods that allow you to do easy type checks and to convert to Java native type (when needed).

JsonObject uses a LinkedHashMap internally and JsonArray extends LinkedList. This ensures that the order of the elements doesn't change arbitrarily.

To conserve memory, Stings and JsonObject keys are represented as utf8 byte arrays internally rather than the 16 bit characters Java uses for Strings. Especially when working with large amounts of json in memory, this can make a large difference of up to nearly 50% of memory (depending on the language).

h2. Parsing and serialization

* A thread safe JsonParser class is provided.
* You can serialize using JsonElement.toString(), JsonElement.prettyPrint(), or using the JsonSerializer class.

h2. JsonBuilder

To facilitate creation of json elements, a builder class is included that makes creation of nested json object structures as easy as it gets in Java. It is recommended to use static imports and to add this class as a favorite in eclipse to facilitate autocompletion.

The builder class also provides methods to facilitate converting from existing Maps, Lists, and other objects. The fromObject method takes any Java object and tries to do the right thing.

h2. JRuby integration

A small jruby script is provided that dynamically extends JsonObject, JsonArray, Hash, and Array with methods to convert between JsonElement and native ruby types. This makes working with jsonj a breeze and is useful when interacting with Java business logic that expects/returns jsonj objects from jruby.

h1. Changelog

* 1.4
** Fix two bugs with the containsKey and serialization
* 1.3
** Promote asInt,asDouble,asBoolean from JsonPrimitive to JsonElement for convenience.
* 1.2 - Use utf8 byte arrays to conserve memory
** String values are now represented as UTF8 byte arrays rather than 16 bit characters
** EfficientString is used for JsonObject keys. 
** JsonElement now has a new serialize method that serializes straight to an OutputStream. JsonSerializer now has a new serialize method to utilize this.
** The String serialize(..) method now uses the new efficient serialization if pretty printing is turned off
* 1.1 - minor feature added
** Added first and last convenience methods to JsonAray 
* 1.0 - only one change relative to 0.9
** Fixed JsonArray.equals to be more strict
* 0.9 - big release with many new features that resulted from months of using jsonj in my own project
** fixes several serialization bugs; serialization and parsing is now very robust
** 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).
** added prettyPrint method to JsonElement that returns a pretty printed string representation of the element (uses JsonSerializer)
** added a fromObject method to the builder that handles nested maps and lists and converts those to json
** added methods to JsonArray to convert to native double, int, or string arrays
** added asString, asDouble, asInt methods to JsonElement so that you don't have to chain asPrimitive().asString() anymore.
** added a *jsonj.rb* script that integrates JsonJ into jruby and allows you to convert back and forth between JsonElement and jruby's Hash and Array native types.
* 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

h1. 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.


h1. FAQ

h2. For who is this framework intended

Anyone who plans to write a lot of business logic in Java that manipulates json data structures and who doesn't wish to write model classes in Java to hide the fact that json is being used. If you are like me, you feel somewhat stuck having to deal with awkward json frameworks while all the cool Ruby,Python, and Javascript kids get to use a serialization that is natively supported in their language. This framework is for you.

h2. Which version should I use?

The latest release or snapshot typically. Releases are tagged in git and I deploy artifacts to my own git repository. 
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. 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. Don't be afraid to ask me to create a new release if there are recent commits that you would like to see released.

h2. 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.

h2. How to build JsonJ

@mvn clean install@ should do the trick with maven 3.x (and probably 2.x as well). 

If you like to use pre-built jars, you can utilize my private maven repository as explained "here":http://www.jillesvangurp.com/2013/02/27/maven-and-my-github-projects/


h2. Where is the documentation?

Javadoc is generated during the build. After building you can find it in @./target/apidocs/index.html@

Additionally, look at the  tests. Particularly "*this one here*":https://github.com/jillesvangurp/JsonJ/blob/master/src/test/java/com/github/JsonJ/ShowOffTheFramework.java shows off most of the features this framework has.

h1. License

The license is the "MIT license":http://en.wikipedia.org/wiki/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).

h1. Acknowledgements

# 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.
{'fraction_non_alphanumeric': 0.03726949837006763, 'fraction_numerical': 0.006227801294214956, 'mean_word_length': 4.3975840336134455, 'pattern_counts': {'":': 6, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '452818', 'n_tokens_mistral': 4997, 'n_tokens_neox': 4735, 'n_words': 3253}