mjson

Class Json

java.lang.Object

mjson.Json

All Implemented Interfaces:

Serializable, Iterable<Json>

public class Json
extends Object
implements Serializable, Iterable<Json>

Represents a JSON (JavaScript Object Notation) entity. For more information about JSON, please see http://www.json.org.

A JSON entity can be one of several things: an object (set of name/Json entity pairs), an array (a list of other JSON entities), a string, a number, a boolean or null. All of those are represented as Json instances. Each of the different types of entities supports a different set of operations. However, this class unifies all operations into a single interface so in Java one is always dealing with a single object type: this class. The approach effectively amounts to dynamic typing where using an unsupported operation won't be detected at compile time, but will throw a runtime UnsupportedOperationException. It simplifies working with JSON structures considerably and it leads to shorter at cleaner Java code. It makes much easier to work with JSON structure without the need to convert to "proper" Java representation in the form of POJOs and the like. When traversing a JSON, there's no need to type-cast at each step because there's only one type: Json.

One can examine the concrete type of a Json with one of the isXXX methods: isObject(), isArray(),isNumber(),isBoolean(),isString(), isNull().

The underlying representation of a given Json instance can be obtained by calling the generic getValue() method or one of the asXXX methods such as asBoolean() or asString() etc. JSON objects are represented as Java Maps while JSON arrays are represented as Java Lists. Because those are mutable aggregate structures, there are two versions of the corresponding asXXX methods: asMap() which performs a deep copy of the underlying map, unwrapping every nested Json entity to its Java representation and asJsonMap() which simply return the map reference. Similarly there are asList() and asJsonList().

Constructing and Modifying JSON Structures

There are several static factory methods in this class that allow you to create new Json instances:

read(String)	Parse a JSON string and return the resulting Json instance. The syntax recognized is as defined in http://www.json.org.
make(Object)	Creates a Json instance based on the concrete type of the parameter. The types recognized are null, numbers, primitives, String, Map, Collection, Java arrays and Json itself.
nil()	Return a Json instance representing JSON null.
object()	Create and return an empty JSON object.
object(Object...)	Create and return a JSON object populated with the key/value pairs passed as an argument sequence. Each even parameter becomes a key (via toString) and each odd parameter is converted to a Json value.
array()	Create and return an empty JSON array.
array(Object...)	Create and return a JSON array from the list of arguments.

To customize how Json elements are represented and to provide your own version of the make(Object) method, you create an implementation of the Json.Factory interface and configure it either globally with the setGlobalFactory(Factory) method or on a per-thread basis with the attachFactory(Factory)/detachFactory() methods.

If a Json instance is an object, you can set its properties by calling the set(String, Object) method which will add a new property or replace an existing one. Adding elements to an array Json is done with the add(Object) method. Removing elements by their index (or key) is done with the delAt(int) (or delAt(String)) method. You can also remove an element from an array without knowing its index with the remove(Object) method. All these methods return the Json instance being manipulated so that method calls can be chained. If you want to remove an element from an object or array and return the removed element as a result of the operation, call atDel(int) or atDel(String) instead.

If you want to add properties to an object in bulk or append a sequence of elements to array, use the #with(Json, Json...opts) method. When used on an object, this method expects another object as its argument and it will copy all properties of that argument into itself. Similarly, when called on array, the method expects another array and it will append all elements of its argument to itself.

To make a clone of a Json object, use the dup() method. This method will create a new object even for the immutable primitive Json types. Objects and arrays are cloned (i.e. duplicated) recursively.

Navigating JSON Structures

The at(int) method returns the array element at the specified index and the at(String) method does the same for a property of an object instance. You can use the at(String, Object) version to create an object property with a default value if it doesn't exist already.

To test just whether a Json object has a given property, use the has(String) method. To test whether a given object property or an array elements is equal to a particular value, use the is(String, Object) and is(int, Object) methods respectively. Those methods return true if the given named property (or indexed element) is equal to the passed in Object as the second parameter. They return false if an object doesn't have the specified property or an index array is out of bounds. For example is(name, value) is equivalent to 'has(name) && at(name).equals(make(value))'.

To help in navigating JSON structures, instances of this class contain a reference to the enclosing JSON entity (object or array) if any. The enclosing entity can be accessed with up() method.

The combination of method chaining when modifying Json instances and the ability to navigate "inside" a structure and then go back to the enclosing element lets one accomplish a lot in a single Java statement, without the need of intermediary variables. Here for example how the following JSON structure can be created in one statement using chained calls:

 {"menu": {
 "id": "file",
 "value": "File",
 "popup": {
   "menuitem": [
     {"value": "New", "onclick": "CreateNewDoc()"},
     {"value": "Open", "onclick": "OpenDoc()"},
     {"value": "Close", "onclick": "CloseDoc()"}
   ]
 }
 "position": 0
 }}
 

 import mjson.Json;
 import static mjson.Json.*;
 ...
 Json j = object()
  .at("menu", object())
    .set("id", "file")
    .set("value", "File")
    .at("popup", object())
      .at("menuitem", array())
        .add(object("value", "New", "onclick", "CreateNewDoc()"))
        .add(object("value", "Open", "onclick", "OpenDoc()"))
        .add(object("value", "Close", "onclick", "CloseDoc()"))
        .up()
      .up()
    .set("position", 0)
  .up();
 ...
 

If there's no danger of naming conflicts, a static import of the factory methods ( import static json.Json.*;) would reduce typing even further and make the code more readable.

Converting to String

To get a compact string representation, simply use the Object.toString() method. If you want to wrap it in a JavaScript callback (for JSON with padding), use the pad(String) method.

Validating with JSON Schema

Since version 1.3, mJson supports JSON Schema, draft 4. A schema is represented by the internal class Json.Schema. To perform a validation, you have a instantiate a Json.Schema using the factory method Json.Schema and then call its validate method on a JSON instance:

 import mjson.Json;
 import static mjson.Json.*;
 ...
 Json inputJson = Json.read(inputString);
 Json schema = Json.schema(new URI("http://mycompany.com/schemas/model"));
 Json errors = schema.validate(inputJson);
 for (Json error : errors.asJsonList())
           System.out.println("Validation error " + err);
 

Version:

2.0.0

Author:

Borislav Iordanov

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Json.DefaultFactory
static interface	Json.Factory This interface defines how Json instances are constructed.
static interface	Json.Function<T,R>
static class	Json.help Exposes some internal methods that are useful for org.sharegov.mjson.Json.Factory implementations or other extension/layers of the library.
static class	Json.MalformedJsonException
static interface	Json.Schema Represents JSON schema - a specific data format that a JSON entity must follow.

Field Summary

Fields

Modifier and Type	Field and Description
static Json.Factory	defaultFactory

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Json()
protected	Json(Json enclosing)

Method Summary

Modifier and Type	Method and Description
Json	add(Json el) Add the specified Json element to this array.
Json	add(Object anything) Add an arbitrary Java object to this Json array.
static Json	array()
static Json	array(Object... args) Return a new JSON array filled up with the list of arguments.
boolean	asBoolean()
byte	asByte()
char	asChar()
double	asDouble()
float	asFloat()
int	asInteger()
List<Json>	asJsonList()
Map<String,Json>	asJsonMap()
List<Object>	asList()
long	asLong()
Map<String,Object>	asMap()
short	asShort()
String	asString()
Json	at(int index) Return the Json element at the specified index of this Json array.
Json	at(String property) Return the specified property of a Json object or null if there's no such property.
Json	at(String property, Json def) Return the specified property of a Json object if it exists.
Json	at(String property, Object def) Return the specified property of a Json object if it exists.
Json	atDel(int index) Remove the element at the specified index from a Json array and return that element.
Json	atDel(String property) Remove the specified property from a Json object and return that property.
static void	attachFactory(Json.Factory factory) Attach a thread-local Json Json.Factory to be used specifically by this thread.
void	attachTo(Json enclosing) Explicitly set the parent of this element.
protected Json	collectWithOptions(Json... options) Return an object representing the complete configuration of a merge.
Json	delAt(int index) Remove the element at the specified index from a Json array.
Json	delAt(String property) Delete the specified property from a Json object.
static void	detachFactory() Clear the thread-local factory previously attached to this thread via the attachFactory(Factory) method.
Json	dup()
static Json.Factory	factory() Return the Json.Factory currently in effect.
Object	getValue()
boolean	has(String property) Return true if this Json object has the specified property and false otherwise.
boolean	is(int index, Object value) Return true if and only if this Json array has an element with the specified value at the specified index.
boolean	is(String property, Object value) Return true if and only if this Json object has a property with the specified value.
boolean	isArray()
boolean	isBoolean()
boolean	isNull()
boolean	isNumber()
boolean	isObject()
boolean	isPrimitive()
boolean	isString()
Iterator<Json>	iterator()
static void	main(String[] argv)
static Json	make(Object anything) Convert an arbitrary Java instance to a Json instance.
static Json	nil()
static Json	object()
static Json	object(Object... args) Return a new JSON object initialized from the passed list of name/value pairs.
String	pad(String callback) Json-pad this object as an argument to a callback function.
static Json	read(CharacterIterator it) Parse a JSON entity from a CharacterIterator.
static Json	read(String jsonAsString) Parse a JSON entity from its string representation.
static Json	read(URL location) Parse a JSON entity from a URL.
Json	remove(Json el) Remove the specified element from a Json array.
Json	remove(Object anything) Remove the specified Java object (converted to a Json instance) from a Json array.
static Json.Schema	schema(Json S)
static Json.Schema	schema(Json S, URI uri)
static Json.Schema	schema(URI uri)
static Json.Schema	schema(URI uri, Json.Function<URI,Json> relativeReferenceResolver)
Json	set(int index, Object value) Change the value of a JSON array element.
Json	set(String property, Json value) Set a Json objects's property.
Json	set(String property, Object value) Set a Json objects's property.
static void	setGlobalFactory(Json.Factory factory) Specify a global Json Json.Factory to be used by all threads that don't have a specific thread-local factory attached to them.
String	toString(int maxCharacters) Return a string representation of this that does not exceed a certain maximum length.
Json	up()
Json	with(Json object, Json[] options) Combine this object or array with the passed in object or array.
Json	with(Json object, Object... options) Same as {}@link #with(Json,Json...options)} with each option argument converted to Json first.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

defaultFactory

public static final Json.Factory defaultFactory

Constructor Detail

Json

protected Json()

Json

protected Json(Json enclosing)

Method Detail

iterator

public Iterator<Json> iterator()

Specified by:

iterator in interface Iterable<Json>

schema

public static Json.Schema schema(Json S)

schema

public static Json.Schema schema(URI uri)

schema

public static Json.Schema schema(URI uri,
                                 Json.Function<URI,Json> relativeReferenceResolver)

schema

public static Json.Schema schema(Json S,
                                 URI uri)

factory

public static Json.Factory factory()

Return the Json.Factory currently in effect. This is the factory that the make(Object) method will dispatch on upon determining the type of its argument. If you already know the type of element to construct, you can avoid the type introspection implicit to the make method and call the factory directly. This will result in an optimization.

Returns:

the factory

setGlobalFactory

public static void setGlobalFactory(Json.Factory factory)

Specify a global Json Json.Factory to be used by all threads that don't have a specific thread-local factory attached to them.

Parameters:

factory - The new global factory

attachFactory

public static void attachFactory(Json.Factory factory)

Attach a thread-local Json Json.Factory to be used specifically by this thread. Thread-local Json factories are the only means to have different Json.Factory implementations used simultaneously in the same application (well, more accurately, the same ClassLoader).

Parameters:

factory - the new thread local factory

detachFactory

public static void detachFactory()

Clear the thread-local factory previously attached to this thread via the attachFactory(Factory) method. The global factory takes effect after a call to this method.

read

public static Json read(String jsonAsString)

Parse a JSON entity from its string representation.

Parameters:

jsonAsString - A valid JSON representation as per the json.org grammar. Cannot be null.

Returns:

The JSON entity parsed: an object, array, string, number or boolean, or null. Note that this method will never return the actual Java null.

read

public static Json read(URL location)

Parse a JSON entity from a URL.

Parameters:

location - A valid URL where to load a JSON document from. Cannot be null.

Returns:

The JSON entity parsed: an object, array, string, number or boolean, or null. Note that this method will never return the actual Java null.

read

public static Json read(CharacterIterator it)

Parse a JSON entity from a CharacterIterator.

Parameters:

it - A character iterator.

Returns:

the parsed JSON element

See Also:

read(String)

nil

public static Json nil()

Returns:

the null Json instance.

object

public static Json object()

Returns:

a newly constructed, empty JSON object.

object

public static Json object(Object... args)

Return a new JSON object initialized from the passed list of name/value pairs. The number of arguments must be even. Each argument at an even position is taken to be a name for the following value. The name arguments are normally of type Java String, but they can be of any other type having an appropriate toString method. Each value is first converted to a Json instance using the make(Object) method.

Parameters:

args - A sequence of name value pairs.

Returns:

the new JSON object.

array

public static Json array()

Returns:

a new constructed, empty JSON array.

array

public static Json array(Object... args)

Return a new JSON array filled up with the list of arguments.

Parameters:

args - The initial content of the array.

Returns:

the new JSON array

make

public static Json make(Object anything)

Convert an arbitrary Java instance to a Json instance.

Maps, Collections and arrays are recursively copied where each of their elements concerted into Json instances as well. The keys of a Map parameter are normally strings, but anything with a meaningful toString implementation will work as well.

Parameters:

anything - Any Java object that the current JSON factory in effect is capable of handling.

Returns:

The Json. This method will never return null. It will throw an IllegalArgumentException if it doesn't know how to convert the argument to a Json instance.

Throws:

IllegalArgumentException - when the concrete type of the parameter is unknown.

toString

public String toString(int maxCharacters)

Return a string representation of this that does not exceed a certain maximum length. This is useful in constructing error messages or any other place where only a "preview" of the JSON element should be displayed. Some JSON structures can get very large and this method will help avoid string serializing the whole of them.

Parameters:

maxCharacters - The maximum number of characters for the string representation.

Returns:

The string representation of this object.

attachTo

public void attachTo(Json enclosing)

Explicitly set the parent of this element. The parent is presumably an array or an object. Normally, there's no need to call this method as the parent is automatically set by the framework. You may need to call it however, if you implement your own Json.Factory with your own implementations of the Json types.

Parameters:

enclosing - The parent element.

up

public final Json up()

Returns:

the Json entity, if any, enclosing this Json. The returned value can be null or a Json object or list, but not one of the primitive types.

dup

public Json dup()

Returns:

a clone (a duplicate) of this Json entity. Note that cloning is deep if array and objects. Primitives are also cloned, even though their values are immutable because the new enclosing entity (the result of the up() method) may be different. since they are immutable.

at

public Json at(int index)

Return the Json element at the specified index of this Json array. This method applies only to Json arrays.

Parameters:

index - The index of the desired element.

Returns:

The JSON element at the specified index in this array.

at

public Json at(String property)

Return the specified property of a Json object or null if there's no such property. This method applies only to Json objects.

Parameters:

The - property name.

Returns:

The JSON element that is the value of that property.

at

public final Json at(String property,
                     Json def)

Return the specified property of a Json object if it exists. If it doesn't, then create a new property with value the def parameter and return that parameter.

Parameters:

property - The property to return.

def - The default value to set and return in case the property doesn't exist.

at

public final Json at(String property,
                     Object def)

Return the specified property of a Json object if it exists. If it doesn't, then create a new property with value the def parameter and return that parameter.

Parameters:

property - The property to return.

def - The default value to set and return in case the property doesn't exist.

has

public boolean has(String property)

Return true if this Json object has the specified property and false otherwise.

Parameters:

property - The name of the property.

is

public boolean is(String property,
                  Object value)

Return true if and only if this Json object has a property with the specified value. In particular, if the object has no such property false is returned.

Parameters:

property - The property name.

value - The value to compare with. Comparison is done via the equals method. If the value is not an instance of Json, it is first converted to such an instance.

Returns:

is

public boolean is(int index,
                  Object value)

Return true if and only if this Json array has an element with the specified value at the specified index. In particular, if the array has no element at this index, false is returned.

Parameters:

index - The 0-based index of the element in a JSON array.

value - The value to compare with. Comparison is done via the equals method. If the value is not an instance of Json, it is first converted to such an instance.

Returns:

add

public Json add(Json el)

Add the specified Json element to this array.

Returns:

this

add

public final Json add(Object anything)

Add an arbitrary Java object to this Json array. The object is first converted to a Json instance by calling the static make(java.lang.Object) method.

Parameters:

anything - Any Java object that can be converted to a Json instance.

Returns:

this

atDel

public Json atDel(String property)

Remove the specified property from a Json object and return that property.

Parameters:

property - The property to be removed.

Returns:

The property value or null if the object didn't have such a property to begin with.

atDel

public Json atDel(int index)

Remove the element at the specified index from a Json array and return that element.

Parameters:

index - The index of the element to delete.

Returns:

The element value.

delAt

public Json delAt(String property)

Delete the specified property from a Json object.

Parameters:

property - The property to be removed.

Returns:

this

delAt

public Json delAt(int index)

Remove the element at the specified index from a Json array.

Parameters:

index - The index of the element to delete.

Returns:

this

remove

public Json remove(Json el)

Remove the specified element from a Json array.

Parameters:

el - The element to delete.

Returns:

this

remove

public final Json remove(Object anything)

Remove the specified Java object (converted to a Json instance) from a Json array. This is equivalent to remove(make(Object)).

Parameters:

anything - The object to delete.

Returns:

this

set

public Json set(String property,
                Json value)

Set a Json objects's property.

Parameters:

property - The property name.

value - The value of the property.

Returns:

this

set

public final Json set(String property,
                      Object value)

Set a Json objects's property.

Parameters:

property - The property name.

value - The value of the property, converted to a Json representation with make(java.lang.Object).

Returns:

this

set

public Json set(int index,
                Object value)

Change the value of a JSON array element. This must be an array.

Parameters:

index - 0-based index of the element in the array.

value - the new value of the element

Returns:

this

with

public Json with(Json object,
                 Json[] options)

Combine this object or array with the passed in object or array. The types of this and the object argument must match. If both are Json objects, all properties of the parameter are added to this. If both are arrays, all elements of the parameter are appended to this

Parameters:

object - The object or array whose properties or elements must be added to this Json object or array.

options - A sequence of options that governs the merging process.

Returns:

this

with

public Json with(Json object,
                 Object... options)

Same as {}@link #with(Json,Json...options)} with each option argument converted to Json first.

getValue

public Object getValue()

Returns:

the underlying value of this Json entity. The actual value will be a Java Boolean, String, Number, Map, List or null. For complex entities (objects or arrays), the method will perform a deep copy and extra underlying values recursively for all nested elements.

asBoolean

public boolean asBoolean()

Returns:

the boolean value of a boolean Json instance. Call isBoolean() first if you're not sure this instance is indeed a boolean.

asString

public String asString()

Returns:

the string value of a string Json instance. Call isString() first if you're not sure this instance is indeed a string.

asInteger

public int asInteger()

Returns:

the integer value of a number Json instance. Call isNumber() first if you're not sure this instance is indeed a number.

asFloat

public float asFloat()

Returns:

the float value of a float Json instance. Call isNumber() first if you're not sure this instance is indeed a number.

asDouble

public double asDouble()

Returns:

the double value of a number Json instance. Call isNumber() first if you're not sure this instance is indeed a number.

asLong

public long asLong()

Returns:

the long value of a number Json instance. Call isNumber() first if you're not sure this instance is indeed a number.

asShort

public short asShort()

Returns:

the short value of a number Json instance. Call isNumber() first if you're not sure this instance is indeed a number.

asByte

public byte asByte()

Returns:

the byte value of a number Json instance. Call isNumber() first if you're not sure this instance is indeed a number.

asChar

public char asChar()

Returns:

the first character of a string Json instance. Call isString() first if you're not sure this instance is indeed a string.

asMap

public Map<String,Object> asMap()

Returns:

a map of the properties of an object Json instance. The map is a clone of the object and can be modified safely without affecting it. Call isObject() first if you're not sure this instance is indeed a Json object.

asJsonMap

public Map<String,Json> asJsonMap()

Returns:

the underlying map of properties of a Json object. The returned map is the actual object representation so any modifications to it are modifications of the Json object itself. Call isObject() first if you're not sure this instance is indeed a Json object.

asList

public List<Object> asList()

Returns:

a list of the elements of a Json array. The list is a clone of the array and can be modified safely without affecting it. Call isArray() first if you're not sure this instance is indeed a Json array.

asJsonList

public List<Json> asJsonList()

Returns:

the underlying List representation of a Json array. The returned list is the actual array representation so any modifications to it are modifications of the Json array itself. Call isArray() first if you're not sure this instance is indeed a Json array.

isNull

public boolean isNull()

Returns:

true if this is a Json null entity and false otherwise.

isString

public boolean isString()

Returns:

true if this is a Json string entity and false otherwise.

isNumber

public boolean isNumber()

Returns:

true if this is a Json number entity and false otherwise.

isBoolean

public boolean isBoolean()

Returns:

true if this is a Json boolean entity and false otherwise.

isArray

public boolean isArray()

Returns:

true if this is a Json array (i.e. list) entity and false otherwise.

isObject

public boolean isObject()

Returns:

true if this is a Json object entity and false otherwise.

isPrimitive

public boolean isPrimitive()

Returns:

true if this is a Json primitive entity (one of string, number or boolean) and false otherwise.

pad

public String pad(String callback)

Json-pad this object as an argument to a callback function.

Parameters:

callback - The name of the callback function. Can be null or empty, in which case no padding is done.

Returns:

The jsonpadded, stringified version of this object if the callback is not null or empty, or just the stringified version of the object.

collectWithOptions

protected Json collectWithOptions(Json... options)

Return an object representing the complete configuration of a merge. The properties of the object represent paths of the JSON structure being merged and the values represent the set of options that apply to each path.

Parameters:

options - the configuration options

Returns:

the configuration object

main

public static void main(String[] argv)