Skip to main content

JsonMap and JsonList

The JsonMap and JsonList classes are generic Java representations of JSON objects and arrays. These classes can be used to create "unstructured" models for serialization (as opposed to "structured" models consisting of beans).

If you want to quickly generate JSON/XML/HTML from generic maps/collections, or parse JSON/XML/HTML into generic maps/collections, these classes work well.

tip

In v10.0, JsonMap / JsonList were re-parented onto a new neutral base — MarshalledMap / MarshalledList — which carries all the marshaller-agnostic surface (typed accessors, fluent setters, getAt/putAt path navigation, bean integration, etc.) with no language coupling. JsonMap / JsonList are now strictly the strict-JSON flavor (toString() returns RFC 8259 JSON; the bare-string constructor defaults to JsonParser). The JSON5 flavor lives in the new sibling pair Json5Map / Json5List (toString() = JSON5; bare-string constructor defaults to Json5Parser). Most of the API on this page works the same on all three — they share the neutral base.

Class hierarchy​

These classes extend the following JCF / Juneau classes:

java.util.LinkedHashMaporg.apache.juneau.marshall.collections.MarshalledMaporg.apache.juneau.marshall.collections.JsonMapjava.util.LinkedListorg.apache.juneau.marshall.collections.MarshalledListorg.apache.juneau.marshall.collections.JsonList

The JsonMap and JsonList classes are very similar to the JSONObject and JSONArray classes found in other libraries. However, the names were chosen because the concepts of Maps and Lists are already familiar to Java programmers, and these classes can be used with any of the serializers or parsers.

Serializing​

These object can be serialized in one of three ways:

Parsing​

Any valid JSON can be parsed into an unstructured model consisting of generic JsonMap and JsonList objects. (Any valid XML can also be parsed into an unstructured model)

// Parse an arbitrary JSON document into an unstructered data model
// consisting of JsonMaps, JsonLists, and java primitive objects.
String json = "{a:{name:'John Smith',age:21},b:{name:'Joe Smith',age:42}}";
JsonMap map = Json.to(json, JsonMap.class);

// Use JsonMap API to extract data from the unstructured model.
int johnSmithAge = map.getMap("a").getInt("age");

// Convert it back into JSON.
json = Json.of(map);

// Or convert it to XML.
String xml = Xml.of(map);

// toString() / toJson() return strict RFC 8259 JSON.
String strict = map.toString();   // {"a":{"name":"John Smith","age":21}, ...}
String strict2 = map.toJson();    // synonym for toString().

// toJson5() returns the historical unquoted-key / single-quoted-string form.
String json5 = map.toJson5();     // {a:{name:'John Smith',age:21}, ...}

Working with the API​

The JsonMap and JsonList classes have many convenience features:

// Convert the map to a bean.
MyBean myBean = map.cast(MyBean.class);

// Find entries by multiple keys.
MyBean myBean = map.find(MyBean.class, "key1", "key2");

// Fluent-style appenders.
map.append("key1", "val1").append("key2", "val2");

// REST-like functions for manipulating nodes in the data structure using URL-like notation.
map.getAt("foo/bar/myBean", MyBean.class);
map.putAt("foo/bar/myBean", MyBean.class);
map.postAt("foo/bar/myListOfBeans", MyBean.class);
map.deleteAt("foo/bar/myBean");

// Copy with inclusion or exclusion.
JsonMap map2 = map.include("key1", "key2", "key3");
JsonMap map3 = map.exclude("key1", "key2", "key3");

// Serialize using another serializer.
String xml = XmlSerializer.DEFAULT.write(map);

// Nested maps.
map.inner(anotherMap);

Parser return types​

note

As a general rule, if you do not specify a target type during parsing, or if the target type cannot be determined through reflection, the parser generates a flavored map/list whose runtime type matches the parser:

Callers that need a specific runtime type — for example to keep an explicit (JsonMap) cast working — should pass an explicit target class to the parser, e.g. parser.read(text, JsonMap.class). The flavor hook is only consulted for unbound Object / Map<String,Object> / Collection<Object> targets; explicit target classes always win.