Class JSON

java.lang.Object
org.eclipse.jetty.util.ajax.JSON
public class JSON extends Object

JSON parser and generator.

This class provides methods to convert POJOs to and from JSON notation.

The mapping from JSON to Java is:

  object --> Map<String, Object>
  array  --> Object[]
  number --> Double or Long
  string --> String
  null   --> null
  bool   --> Boolean

The Java to JSON mapping is:

  String --> string
  Number --> number
  Map    --> object
  List   --> array
  Array  --> array
  null   --> null
  Boolean--> boolean
  Object --> string (dubious!)

The interface JSON.Convertible may be implemented by classes that wish to externalize and initialize specific fields to and from JSON objects. Only directed acyclic graphs of objects are supported.

The interface JSON.Generator may be implemented by classes that know how to render themselves as JSON and the toJSON(Object) method will use JSON.Generator.addJSON(Appendable) to generate the JSON.

The class JSON.Literal may be used to hold pre-generated JSON object.

The interface JSON.Convertor may be implemented to provide converters for objects that may be registered with addConvertor(Class, Convertor). These converters are looked up by class, interface and super class by getConvertor(Class).

If a JSON object has a class field, then a Java class for that name is loaded and the method convertTo(Class, Map) is used to find a JSON.Convertor for that class.

If a JSON object has a x-class field then a direct lookup for a JSON.Convertor for that class name is done (without loading the class).

  • Constructor Details

    • JSON

      public JSON()

  • Method Details

    • getStringBufferSize

      public int getStringBufferSize()
      Returns:
      the initial stringBuffer size to use when creating JSON strings (default 1024)

    • setStringBufferSize

      public void setStringBufferSize(int stringBufferSize)
      Parameters:
      stringBufferSize - the initial stringBuffer size to use when creating JSON strings (default 1024)

    • escapeString

      public void escapeString(Appendable buffer, String input) throws IOException

      Escapes the characters of the given input string into the given buffer.

      Parameters:
      buffer - the buffer to escape the string into
      input - the string to escape
      Throws:
      IOException - if appending to the buffer fails
      See Also:

    • escapeUnicode

      protected void escapeUnicode(Appendable buffer, char c) throws IOException

      Per JSON specification, unicode characters are by default NOT escaped.

      Overriding this method allows for alternate behavior to escape those with your choice of encoding.

      protected void escapeUnicode(Appendable buffer, char c) throws IOException
{
    // Unicode is backslash-u escaped
    buffer.append(String.format("\\u%04x", (int)c));
}
      Throws:
      IOException

    • toJSON

      public String toJSON(Object object)

      Converts any object to JSON.

      Parameters:
      object - the object to convert
      Returns:
      the JSON string representation of the object
      See Also:

    • append

      public void append(Appendable buffer, Object object)

      Appends the given object as JSON to string buffer.

      This method tests the given object type and calls other appends methods for each object type, see for example appendMap(Appendable, Map).

      Parameters:
      buffer - the buffer to append to
      object - the object to convert to JSON

    • appendNull

      public void appendNull(Appendable buffer)

    • appendJSON

      public void appendJSON(Appendable buffer, JSON.Convertor convertor, Object object)

    • appendJSON

      public void appendJSON(Appendable buffer, JSON.Convertible converter)

    • appendJSON

      public void appendJSON(Appendable buffer, JSON.Generator generator)

    • appendMap

      public void appendMap(Appendable buffer, Map<?,?> map)

    • appendArray

      public void appendArray(Appendable buffer, Collection<?> collection)

    • appendArray

      public void appendArray(Appendable buffer, Object array)

    • appendBoolean

      public void appendBoolean(Appendable buffer, Boolean b)

    • appendNumber

      public void appendNumber(Appendable buffer, Number number)

    • appendString

      public void appendString(Appendable buffer, String string)

    • newMap

      protected Map<String,Object> newMap()

      Factory method that creates a Map when a JSON representation of {...} is parsed.

      Returns:
      a new Map representing the JSON object

    • newArray

      @Deprecated protected Object[] newArray(int size)
      Deprecated.
      use setArrayConverter(Function) instead.

      Factory method that creates an array when a JSON representation of [...] is parsed.

      Parameters:
      size - the size of the array
      Returns:
      a new array representing the JSON array

    • contextForArray

      protected JSON contextForArray()

      Every time a JSON array representation [...] is parsed, this method is called to (possibly) return a different JSON instance (for example configured with different converters) to parse the array items.

      Returns:
      a JSON instance to parse array items

    • contextFor

      protected JSON contextFor(String field)

      Every time a JSON object field representation {"name": value} is parsed, this method is called to (possibly) return a different JSON instance (for example configured with different converters) to parse the object field.

      Parameters:
      field - the field name
      Returns:
      a JSON instance to parse the object field

    • convertTo

      protected Object convertTo(Class<?> type, Map<String,Object> map)

    • addConvertor

      public void addConvertor(Class<?> forClass, JSON.Convertor convertor)

      Registers a JSON.Convertor for the given class.

      Parameters:
      forClass - the class the convertor applies to
      convertor - the convertor for the class

    • addConvertorFor

      public void addConvertorFor(String name, JSON.Convertor convertor)

      Registers a JSON.Convertor for a named class.

      Parameters:
      name - the name of the class the convertor applies to
      convertor - the convertor for the class

    • removeConvertor

      public JSON.Convertor removeConvertor(Class<?> forClass)

      Unregisters a JSON.Convertor for a class.

      Parameters:
      forClass - the class the convertor applies to
      Returns:
      the convertor for the class

    • removeConvertorFor

      public JSON.Convertor removeConvertorFor(String name)

      Unregisters a JSON.Convertor for a named class.

      Parameters:
      name - the name of the class the convertor applies to
      Returns:
      the convertor for the class

    • getConvertor

      protected JSON.Convertor getConvertor(Class<?> forClass)

      Looks up a convertor for a class.

      If no match is found for the class, then the interfaces for the class are tried. If still no match is found, then the super class and its interfaces are tried iteratively.

      Parameters:
      forClass - the class to look up the convertor
      Returns:
      a JSON.Convertor or null if none was found for the class

    • getConvertorFor

      public JSON.Convertor getConvertorFor(String name)

      Looks up a convertor for a class name.

      Parameters:
      name - name of the class to look up the convertor
      Returns:
      a JSON.Convertor or null if none were found.

    • getArrayConverter

      public Function<List<?>,Object> getArrayConverter()
      Returns:
      the function to customize the Java representation of JSON arrays
      See Also:

    • setArrayConverter

      public void setArrayConverter(Function<List<?>,Object> arrayConverter)

      Sets the function to convert JSON arrays from their default Java representation, a List<Object>, to another Java data structure such as an Object[].

      Parameters:
      arrayConverter - the function to customize the Java representation of JSON arrays
      See Also:

    • parse

      public Object parse(JSON.Source source, boolean stripOuterComment)

      Parses the given JSON source into an object.

      Although the JSON specification does not allow comments (of any kind) this method optionally strips out outer comments of this form:

      // An outer comment line.
/* Another outer comment, multiline.
// Yet another comment line.
{
    "name": "the real JSON"
}
*/ End of outer comment, multiline.
      Parameters:
      source - the JSON source to parse
      stripOuterComment - whether to strip outer comments
      Returns:
      the object constructed from the JSON string representation

    • fromJSON

      public Object fromJSON(CharSequence string)

      Parses the given JSON string into an object.

      Parameters:
      string - the JSON string to parse
      Returns:
      the object constructed from the JSON string representation

    • fromJSON

      public Object fromJSON(Reader reader)

      Parses the JSON from the given Reader into an object.

      Parameters:
      reader - the Reader to read the JSON from
      Returns:
      the object constructed from the JSON string representation

    • parse

      public Object parse(JSON.Source source)

      Parses the given JSON source into an object.

      Although the JSON specification does not allow comments (of any kind) this method strips out initial comments of this form:

      // An initial comment line.
/* An initial
   multiline comment */
{
    "name": "foo"
}

      This method detects the object type and calls other parse methods for each object type, see for example parseArray(Source).

      Parameters:
      source - the JSON source to parse
      Returns:
      the object constructed from the JSON string representation

    • handleUnknown

      protected Object handleUnknown(JSON.Source source, char c)

    • parseObject

      protected Object parseObject(JSON.Source source)

    • parseArray

      protected Object parseArray(JSON.Source source)

    • parseString

      protected String parseString(JSON.Source source)

    • parseNumber

      public Number parseNumber(JSON.Source source)

    • seekTo

      protected void seekTo(char seek, JSON.Source source)

    • seekTo

      protected char seekTo(String seek, JSON.Source source)

    • complete

      protected static void complete(String seek, JSON.Source source)