{updated-8.2.0} OMap and OList

The {@link oaj.collections.OMap} and {@link oaj.collections.OList} 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.

These classes extend directly from the following JCF classes:

- {@link java.util.LinkedHashMap java.util.LinkedHashMap}
  - {@link oaj.collections.OMap org.apache.juneau.collections.OMap}
- {@link java.util.LinkedList java.util.LinkedList}
  - {@link oaj.collections.OList org.apache.juneau.collections.OList}

The OMap and OList 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.

These object can be serialized in one of two ways:

1. Using the provided {@link oaj.collections.OMap#serializeTo(java.io.Writer)} or {@link oaj.collections.OList#serializeTo(java.io.Writer)} methods.
2. Passing them to one of the {@link oaj.serializer.Serializer} serialize methods.
3. Simply calling the {@link oaj.collections.OMap#toString()} or {@link oaj.collections.OList#toString()} methods which will serialize it as Simplified JSON.

Any valid JSON can be parsed into an unstructured model consisting of generic {@link oaj.collections.OMap} and {@link oaj.collections.OList} objects. (In theory, any valid XML can also be parsed into an unstructured model, although this has not been officially 'tested')

// Parse an arbitrary JSON document into an unstructered data model // consisting of OMaps, OLists, and java primitive objects. Parser parser = JsonParser.DEFAULT; String json = "{a:{name:'John Smith',age:21},b:{name:'Joe Smith',age:42}}"; OMap omap = parser.parse(json, OMap.class); // Use OMap API to extract data from the unstructured model. int johnSmithAge = omap.getMap("a").getInt("age"); // Convert it back into JSON. json = JsonSerializer.DEFAULT.serialize(omap); // Or convert it to XML. String xml = XmlSerializer.DEFAULT.serialize(omap); // Or just use toString(). json = omap.toString();

The OMap and OList classes have many convenience features:

// Convert the map to a bean. MyBean myBean = omap.cast(MyBean.class); // Find entries by multiple keys. MyBean myBean = omap.find(MyBean.class, "key1", "key2"); // Fluent-style appenders. omap.append("key1", "val1").append("key2", "val2"); // REST-like functions for manipulating nodes in the data structure using URL-like notation. omap.getAt("foo/bar/myBean", MyBean.class); omap.putAt("foo/bar/myBean", MyBean.class); omap.postAt("foo/bar/myListOfBeans", MyBean.class); omap.deleteAt("foo/bar/myBean"); // Copy with inclusion or exclusion. OMap omap2 = omap.include("key1", "key2", "key3"); OMap omap3 = omap.exclude("key1", "key2", "key3"); // Serialize using another serializer. String xml = omap.serializeTo(XmlSerializer.DEFAULT); // Nested maps. omap.inner(omapInner);

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 parsers automatically generate OMaps and OLists.