Perfect Groovy serialization to and from JSON format (available on Maven Central). To include in your project:
<dependency>
<groupId>com.cedarsoftware</groupId>
<artifactId>groovy-io</artifactId>
<version>1.1.3</version>
</dependency>
groovy-io consists of two main classes, a reader (GroovyJsonReader
) and a writer (GroovyJsonWriter
). groovy-io eliminates the need for using ObjectInputStream / ObjectOutputStream
to serialize objects and instead uses the JSON format. There is a 3rd optional class (JsonObject
) see 'Non-typed Usage' below.
groovy-io does not require that classes implement Serializable
or Externalizable
to be serialized, unlike ObjectInputStream
/ ObjectOutputStream
. It will serialize any object graph into JSON and retain complete graph semantics / shape and object types. This includes supporting private fields, private inner classes (static or non-static), of any depth. It also includes handling cyclic references. Objects do not need to have public constructors to be serialized. The output JSON will not include transient
fields, identical to the ObjectOutputStream behavior. This can be overidden if needed.
The GroovyJsonReader / GroovyJsonWriter
code does not depend on any native or 3rd party libraries.
For useful and powerful Java utilities, check out java-util at http://github.com/jdereg/java-util
groovy-io uses proper JSON format. As little type information is included in the JSON format to keep it compact as possible. When an object's class can be inferred from a field type or array type, the object's type information is left out of the stream. For example, a String[]
looks like ["abc", "xyz"]
.
When an object's type must be emitted, it is emitted as a meta-object field "@type":"package.class"
in the object. When read, this tells the GroovyJsonReader what class to instantiate. On the Javascript side, this can be ignored.
If an object is referenced more than once, or references an object that has not yet been defined, (say A points to B, and B points to C, and C points to A), it emits a "@ref":n
where 'n' is the object's integer identity (with a corresponding meta entry "@id":n
defined on the referenced object). Only referenced objects have IDs in the JSON output, reducing the JSON String length.
groovy-io was written with performance in mind. As the tests run, a log is written of the time it takes to serialize / deserialize and compares it to ObjectInputStream / ObjectOutputStream
.
groovy-io can be used directly on JSON Strings or with Groovy's Streams.
Example 1: String to Groovy object
Object obj = GroovyJsonReader.jsonToGroovy('["Hello, World"]')
This will convert the JSON String to a Groovy Object graph. In this case, it would consist of an Object[]
of one String
element.
Example 2: Groovy object to JSON String
Employee emp
// Emp fetched from database
String json = GroovyJsonWriter.objectToJson(emp)
This example will convert the Employee
instance to a JSON String. If the GroovyJsonReader
were used on this String
, it would reconstitute a Groovy Employee
instance.
Example 3: InputStream
to Groovy object
GroovyJsonReader jr = new GroovyJsonReader(inputStream)
Employee emp = (Employee) jr.readObject()
In this example, an InputStream
(could be from a File, the Network, etc.) is supplying an unknown amount of JSON. The GroovyJsonReader
is used to wrap the stream to parse it, and return the Groovy object graph it represents.
Example 4: Groovy Object to OutputStream
Employee emp
// emp obtained from database
GroovyJsonWriter jw = new GroovyJsonWriter(outputStream)
jw.write(emp)
jw.close()
In this example, a Groovy object is written to an output stream in JSON format.
groovy-io provides the choice to use the generic "Map of Maps" representation of an object graph, akin to a Javascript associative array. When reading from a JSON String or InputStream
of JSON, the GroovyJsonReader
can be constructed like this:
Map graph = GroovyJsonReader.jsonToMaps(String json)
-- or --
GroovyJsonReader jr = new GroovyJsonReader(InputStream, true)
Map map = (Map) jr.readObject()
This will return an untyped object representation of the JSON String as a Map
of Maps, where the fields are the Map
keys (Strings), and the field values are the associated Map's values. In this representation the Map
instance returned is actually a JsonObject
instance (from groovy-io). This JsonObject
implements the Map
interface permitting access to the entire object. Cast to a JsonObject
, you can see the type information, position within the JSON stream, and other information.
This 'Maps' representation can be re-written to a JSON String or Stream and the output JSON will be equivalent to the original input JSON stream. This permits a JVM receiving JSON strings / streams that contain class references which do not exist in the JVM that is parsing the JSON, to completely read / write the stream. Additionally, the Maps can be modified before being written, and the entire graph can be re-written in one collective write. Any object model can be read, modified, and then re-written by a JVM that does not contain any of the classes in the JSON data!
Both the GroovyJsonWriter
and GroovyJsonReader
allow you to pass in an optional arguments Map<String, Object>
. This Map
has well known keys (constants from GroovyJsonWriter
/ GroovyJsonWriter
). To enable the respective feature, first create a Map
. Then place the well known key in the Map
and associate the appropriate setting as the value. Below is a complete list of features and some example usages. Shown in Groovy for brevity.
Map args = [
(GroovyJsonWriter.SHORT_META_KEYS):true,
(GroovyJsonWriter.TYPE_NAME_MAP):[
'java.util.ArrayList':'alist',
'java.util.LinkedHashMap':'lmap',
(TestObject.class.getName()):'testO'
]
]
String json = GroovyJsonWriter.objectToJson(list, args)
In this example, we create an 'args' Map
, set the key GroovyJsonWriter.SHORT_META_KEYS
to true
and set the GroovyJsonWriter.TYPE_NAME_MAP
to a Map
that will be used to substitute class names for short-hand names.
All of the values below are public constants from GroovyJsonWriter
, used by placing them as keys in the arguments map.
DATE_FORMAT // Set this format string to control the format dates are
// written. Example: "yyyy/MM/dd HH:mm". Can also be a
// DateFormat instance. Can also be the constant
// JsonWriter.ISO_DATE_FORMAT or
// JsonWriter.ISO_DATE_TIME_FORMAT
TYPE // Set to boolean true to force all data types to be
// output, even where they could have been omitted.
PRETTY_PRINT // Force nicely formatted JSON output
// (See http://jsoneditoronline.org for example format)
FIELD_SPECIFIERS // Set to a Map<Class, List<String>> which is used to
// control which fields of a class are output.
ENUM_PUBLIC_ONLY // If set, indicates that private variables of ENUMs are not
// serialized.
WRITE_LONGS_AS_STRINGS // If set, longs are written in quotes (Javascript safe).
// JsonReader will automatically convert Strings back
// to longs. Any Number can be set from a String.
TYPE_NAME_MAP // If set, this map will be used when writing @type values.
// Allows short-hand abbreviations for type names.
SHORT_META_KEYS // If set, then @type => @t, @keys => @k, @items => @e,
// @ref => @r, and @id => @i
All of the values below are public constants from GroovyJsonReader
, used by placing them as keys in the arguments map.
USE_MAPS // If set to boolean true, the read-in JSON will be
// turned into a Map of Maps (JsonObject) representation. Note
// that calling the JsonWriter on this root Map will indeed
// write the equivalent JSON stream as was read.
TYPE_NAME_MAP // If set, this map will be used when writing @type values.
// Allows short-hand abbreviations of type names.
UNKNOWN_TYPE // Set to null (or leave out), unknown objects are returned as Maps.
// Set to String class name, and unknown objects will be created
// as with this class name, and the fields will be set on it.
// Set to false, and an exception will be thrown when an unknown
// object type is encountered. The location in the JSON will
// be given.
New APIs have been added to allow you to associate a custom reader / writer class to a particular class if you want it to be read / written specially in the JSON output. This approach allows you to customize the JSON format for classes for which you do not have the source code.
Example (in Groovy). Note the Person has a List of pets, and in this case, it re-uses
GroovyJsonWriter to write that part of the class out (not need to customize it):
static class CustomPersonWriter implements JsonTypeWriterEx
{
void write(Object o, boolean showType, Writer output, Map<String, Object> args)
{
Person p = (Person) o
output.write('"first":"')
output.write(p.getFirstName())
output.write('","last":"')
output.write(p.getLastName())
GroovyJsonWriter writer = Support.getWriter(args)
writer.writeImpl(p.getPets(), true)
}
}
Included is a small Javascript utility that will take a JSON output stream created by the JSON writer and substitute all @ref's
for the actual pointed to object. It's a one-line call - resolveRefs(json)
. This will substitute @ref
tags in the JSON for the actual pointed-to object. In addition, the @keys
/ @items
will also be converted into Javascript Maps and Arrays. Finally, there is a Javascript API that will convert a full Javascript object graph to JSON, (even if it has cycles within the graph). This will maintain the proper graph-shape when sending it from the client back to the server.
Even though groovy-io is perfect for Groovy / Javascript serialization, there are other great uses for it:
Many projects use GroovyJsonWriter
to write an object to JSON, then use the GroovyJsonReader
to read it in, perfectly cloning the original object graph:
Employee emp
// emp obtained from database
Employee deepCopy = (Employee) cloneObject(emp)
public Object cloneObject(Object root)
{
return GroovyJsonReader.jsonToGroovy(GroovyJsonWriter.objectToJson(root))
}
Instead of doing println
debugging, call GroovyJsonWriter.objectToJson(obj)
and print that String out. It will reveal the object graph in all it's glory.
Use GroovyJsonWriter.formatJson()
API to format a passed in JSON string to a nice, human readable format. Also, when writing JSON data, use the GroovyJsonWriter.objectToJson(o, args)
API, where args is a Map
with a key of GroovyJsonWriter.PRETTY_PRINT
and a value of 'true' (boolean
or String
). When run this way, the JSON written by the GroovyJsonWriter
will be formatted in a nice, human readable format.
groovy-io can be used as the fundamental data transfer method between a Javascript / JQuery / Ajax client and a web server in a RESTful fashion. Used this way, you can create more active sites like Google's GMail, MyOtherDrive online backup, etc.
See https://github.com/jdereg/json-command-servlet for a light-weight servlet that processes Ajax / XHR calls.
Featured on http://json.org.
- 1.1.3
- Cache Map's for custom reader's updated to be
ConcurrentMap
instead ofMap
. - 1.1.2
JsonTypeReaderEx
added, which passes the 'args'Map
through to the custom reader.- Both
JsonTypeReaderEx
andJsonTypeWriterEx
have aMap
as the last argument in their single method that is implemented by the custom reader / writer. ThisMap
is the same as the 'args'Ma
passed into to theGroovyJsonReader
/GroovyJsonWriter
, with the addedJSON_READER
orJSON_WRITER
key and associated value of the callingGroovyJsonReader
/GroovyJsonWriter
instance. - 1.1.1
- Changed
GroovyJsonWriter.writeImpl()
from protected to public to permit access from CustomWriters. - Created
JsonTypeWriterEx
which passes GroovyJsonWriter to the custom writer so that it can re-use the writeImpl() API on the groovyJsonWriter. It inherits fromJsonTypeWriterBase
.
- Changed
- 1.1.0
GroovyJsonReader.UNKNOWN_OBJECT
added as an option to indicate what to do when an unknown object is encountered in the JSON. Default is aMap
will be created. However, you can set this argument to aString
class name to instantiate, or set it to false to force an exception to be thrown.- New Feature: Short class names to reduce the size of the output JSON. This allows you to, for example, substitute
java.util.HashMap
withhmap
so that it will appear in the JSON as"@type":"hmap"
. Pass the substitution map to theGroovyJsonWriter
(or reader) as an entry in the argsMap
with the key ofGroovyJsonWriter.TYPE_NAME_MAP
and the value as aMap
instance with String class names as the keys and short-names as the values. The same map can be passed to theGroovyJsonReader
and it will properly read the substituted types. - New Feature: Short meta-key names to reduce the size of the output JSON. The
@type
key name will be shortened to@t
,@id
=>@i
,@ref
=>@r
,@keys
=>@k
,@items
=>@e
. Put a key in theargs
Map
asGroovyJsonWriter.SHORT_META_KEYS
with the valuetrue
. - Performance improvement: No longer using .classForName() inside JsonObject to determine isMap() or isCollection(). Reading JSON into Map of Maps mode significantly faster.
- 1.0.7
- Bug fix: Using a CustomReader in a Collection with at least two identical elements causes an exception (submitted by @KaiHufenbach).
- 1.0.6
- Added new flag
GroovyJsonWriter.WRITE_LONGS_AS_STRINGS
which forces long/Long's to be written as Strings. When sending JSON data to a Javascript, longs can lose precision because Javascript only maintains 53-bits of info (Javascript uses IEEE 754double
for numbers). The precision is lost due to some of the bits used for maintaining an exponent. With this flag set, longs will be sent as Strings, however, on return back to a Java server, json-io allows Strings to be set right back into long (fields, array elements, collections, etc.) - 1.0.5
- Performance improvement: caching the custom reader / writers associated to given classes.
- Ease of use:
groovy-io
throws aJsonIoException
(unchecked) instead of checked exceptionIOException
. This allows more flexibility in terms of error handling for the user. - Code cleanup: Moved reflection related code from
GroovyJsonReader
into separateMetaUtils
class. - Code cleanup: Moved
FastPushbackReader
fromGroovyJsonReader
into separate class. - Code cleanup: Moved JSON parsing code from
GroovyJsonReader
into separateJsonParser
class. - Code cleanup: Moved built-in readers from
GroovyJsonReader
to separateReaders
class. - Code cleanup: Moved resolver code (code that marshals map of maps to Java instances) into separate
Resolver
classes.
- 1.0.4
GroovyJsonReader.newInstance()
API made public- Bumped version of junit from 4.11 to 4.12
- Added additional tests to ensure that null and "" can be properly assigned to primitive values (matching behavior of java-util's
Converter.convert()
API).
- 1.0.3
- More simplifications to source code using more of Groovy's capabilities.
- 1.0.2
- Initial release
by John DeRegnaucourt