Package org.infinispan.commons.dataconversion.internal

Class Json

java.lang.Object
org.infinispan.commons.dataconversion.internal.Json
All Implemented Interfaces:
Serializable
public class Json extends Object implements Serializable

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);

Infinispan changes on top of 1.4.2:

Version:
1.4.2
Author:
Borislav Iordanov
See Also:

  • Field Details

    • defaultFactory

      public static final Json.Factory defaultFactory

  • Constructor Details

    • Json

      protected Json()

    • Json

      protected Json(Json enclosing)

  • Method Details

    • 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

    • escape

      public static void escape(CharSequence sequence, Appendable out) throws IOException
      Throws:
      IOException

    • 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:

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

    • location

      public Json location(int line, int column)

    • getLine

      public int getLine()

    • getColumn

      public int getColumn()

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

    • toPrettyString

      public String toPrettyString()

    • 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:
      property - 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.

    • replace

      public Json replace(Json oldJson, Json newJson)

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

    • isRaw

      public boolean isRaw()

    • 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)