Class Json

java.lang.Object

com.codename1.backend.Json

public final class Json
extends Object

JSON for server-side binaries: the core's strict reader and a streaming writer.

Reading is com.codename1.io.JSONParser#parseStrict, the same code the device runs (JSONParser is shared with the backend). This class once carried a parser of its own because JSONParser reached com.codename1.processing.Result and, through it, the XML DOM; that dependency is gone. Writing stays here because it streams into a ByteSink and honours Writable and Encoder, which the core writer has no notion of.

Values map as: object to LinkedHashMap (insertion-ordered so a round trip is stable), array to ArrayList, string to String, number to Double or Long, true/false to Boolean, null to null. Anything malformed -- trailing content, a raw control character in a string, a number outside the JSON grammar or a long, nesting deeper than 512 -- throws IOException.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Json.Encoder	Writes values of one type as JSON, shared by every request that answers with that type.
static interface	Json.Writable	A value that knows how to write itself as JSON.

Method Summary

Modifier and Type	Method	Description
static <T> T	convert(Object tree, Class<T> type)	Reads a document already parsed by parse(String) -- or a member of one -- into type, as Jackson's convertValue does.
static Object	parse(String json)	Parses any JSON value.
static Map	parseObject(String json)	Parses a JSON object.
static <T> T	read(String json, Class<T> type)	Reads a JSON document into type, as Jackson's readValue does.
static <T> List<T>	readList(String json, Class<T> element)	Reads a JSON array of element, as Jackson's readValue(json, new TypeReference<List<T>>() {}) does.
static String	write(Object value)
static void	write(Object value, ByteSink out)	Writes JSON as UTF-8 bytes straight into a reusable buffer.
static void	writeString(String value, ByteSink out)	One JSON string, escaped, straight into out.
static void	writeValue(Object value, ByteSink out)	One JSON value of unknown type, for the cases a generated codec cannot resolve statically (an unmodelled java.* type, a heterogeneous collection).

Methods inherited from class Object

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

Method Details

parseObject

public static Map parseObject(String json)
                       throws IOException

Parses a JSON object. Throws IOException on anything malformed.

Throws:

IOException

parse

public static Object parse(String json)
                    throws IOException

Parses any JSON value. Throws IOException on anything malformed.

Throws:

IOException

read

public static <T> T read(String json,
 Class<T> type)
                  throws IOException

Reads a JSON document into type, as Jackson's readValue does.

Release release = Json.read(body, Release.class);

An application class is read by the codec the build generated for it -- the one a route taking it as a @RequestBody uses, so @JsonProperty, @JsonIgnore and the rest mean the same thing here. The build writes a codec for every class literal passed to this method, readList(String, Class) and convert(Object, Class) in the application's code, so name the class literally: a Class that arrives in a variable is read only if some other use made the build write its codec, and is refused with IllegalStateException otherwise.

String, the boxed numbers, Boolean, Map, List and Object need no codec.

Parameters:

json - the document

type - what to read it into

Returns:

the value, or null for a JSON null

Throws:

IOException - when json is not JSON

IllegalArgumentException - when the document does not fit type; the message names where, as $.items[2].due

readList

public static <T> List<T> readList(String json,
 Class<T> element)
                            throws IOException

Reads a JSON array of element, as Jackson's readValue(json, new TypeReference<List<T>>() {}) does.

Parameters:

json - the document, an array

element - what each element is read into; see read(String, Class)

Returns:

the elements, in order

Throws:

IOException - when json is not JSON

IllegalArgumentException - when it is not an array, or an element does not fit element

convert

public static <T> T convert(Object tree,
 Class<T> type)

Reads a document already parsed by parse(String) -- or a member of one -- into type, as Jackson's convertValue does. See read(String, Class).

Parameters:

tree - what parse(String) returned, or part of it

type - what to read it into

Returns:

the value, or null for null

Throws:

IllegalArgumentException - when tree does not fit type

write

public static String write(Object value)

write

public static void write(Object value,
 ByteSink out)

Writes JSON as UTF-8 bytes straight into a reusable buffer.

The String-returning form above builds a StringBuilder, grows its char[] several times, copies it into a String and then encodes that to bytes -- four allocations for a document the server is about to write to a socket and discard. Measured on a small JSON response, that chain was most of the per-request allocation once the response head had been dealt with, and it kept the collector's run-ahead cap firing.

Same output as write(Object), byte for byte.

writeString

public static void writeString(String value,
 ByteSink out)

One JSON string, escaped, straight into out.

Public because generated code calls it. A codec that knows its field types at build time emits a direct call here instead of putting the value in a Map and letting write(Object) rediscover its type at run time.

writeValue

public static void writeValue(Object value,
 ByteSink out)

One JSON value of unknown type, for the cases a generated codec cannot resolve statically (an unmodelled java.* type, a heterogeneous collection). The generated code uses the typed calls wherever it can and falls back here only where it must.