Package org.apache.juneau.marshall.collections

Class JsonList

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractList<E>
java.util.AbstractSequentialList<E>
java.util.LinkedList<Object>
org.apache.juneau.marshall.collections.MarshalledList
org.apache.juneau.marshall.collections.JsonList
All Implemented Interfaces:
Serializable, Cloneable, Iterable<Object>, Collection<Object>, Deque<Object>, List<Object>, Queue<Object>
Direct Known Subclasses:
DelegateList
public class JsonList extends MarshalledList
Java implementation of a JSON array.

This class is a subclass of MarshalledList that carries strict-JSON-specific surface, including strict-JSON toString() (via Json.of(Object)), JsonParser-defaulting CharSequence / Reader constructors, and convenience methods for serializing to the various JSON dialects (JSON5, JSON Lines, canonical JSON, HJSON).

v10.0 behavioral break: toString() now produces strict (RFC 8259) JSON (was JSON5), and the CharSequence / Reader constructors now default to JsonParser.DEFAULT (was Json5Parser.DEFAULT). For the previous JSON5 behavior use Json5List.

Note that the use of this class is optional for generating JSON. The serializers will accept any objects that implement the Collection interface. But this class provides some useful additional functionality when working with JSON models constructed from Java Collections Framework objects. For example, a constructor is provided for converting a JSON array string directly into a List. It also contains accessor methods for to avoid common typecasting when accessing elements in a list.

Example:

// Construct an empty List JsonList list = JsonList.of(); // Construct a list of objects using various methods list = JsonList.of().a("foo").a(123).a(true); list = JsonList.of().a("foo", 123, true); // Equivalent list = JsonList.of("foo", 123, true); // Equivalent // Construct a list of integers from JSON list = JsonList.ofString("[1,2,3]"); // Construct a list of generic JsonMap objects from JSON list = JsonList.ofString("[{foo:'bar'},{baz:'bing'}]"); // Construct JSON from JsonList list = JsonList.ofString("[{foo:'bar'},{baz:'bing'}]"); String json = list.toString(); // Produces "[{foo:'bar'},{baz:'bing'}]" json = list.toString(JsonSerializer.DEFAULT); // Equivalent json = JsonSerializer.DEFAULT.write(list); // Equivalent // Get one of the entries in the list as an Integer list = JsonList.ofString("[1,2,3]"); Integer integer = list.getInt(1); integer = list.get(Integer.class, 1); // Equivalent // Iterate over a list of beans using the elements() method list = JsonList.ofString("[{name:'John Smith',age:45}]"); for (Person person : list.elements(Person.class) { // Do something with p }

Notes:
  • This class is not thread safe.

  • Field Details

  • Constructor Details

    • JsonList

      public JsonList()
      Construct an empty list.

    • JsonList

      public JsonList(MarshallingSession session)
      Construct an empty list with the specified bean context.
      Parameters:
      session - The bean session to use for creating beans.

    • JsonList

      public JsonList(CharSequence json) throws ParseException
      Construct a list initialized with the specified JSON.
      Parameters:
      json - The JSON text to parse.
      Must be strict (RFC 8259) JSON; for JSON5 input use Json5List or pass Json5Parser.DEFAULT explicitly.
      Throws:
      ParseException - Malformed input encountered.

    • JsonList

      public JsonList(CharSequence in, Parser p) throws ParseException
      Construct a list initialized with the specified string.
      Parameters:
      in - The input being parsed.
      Can be null or empty (results in an empty list; no parsing occurs).
      p - The parser to use to parse the input.
      If null, uses JsonParser.
      Throws:
      ParseException - Malformed input encountered.

    • JsonList

      public JsonList(Collection<?> copyFrom)
      Construct a list initialized with the specified list.
      Parameters:
      copyFrom - The list to copy.
      Can be null (results in an empty list).

    • JsonList

      public JsonList(Object... entries)
      Construct a list initialized with the contents.
      Parameters:
      entries - The entries to add to this list.

    • JsonList

      public JsonList(Reader json) throws ParseException
      Construct a list initialized with the specified reader containing JSON.
      Parameters:
      json - The reader containing JSON text to parse.
      Must be strict (RFC 8259) JSON; for JSON5 input use Json5List or pass Json5Parser.DEFAULT explicitly.
      Throws:
      ParseException - Malformed input encountered.

    • JsonList

      public JsonList(Reader in, Parser p) throws ParseException
      Construct a list initialized with the specified string.
      Parameters:
      in - The reader containing the input being parsed.
      Must be strict (RFC 8259) JSON.
      p - The parser to use to parse the input.
      If null, uses JsonParser.
      Throws:
      ParseException - Malformed input encountered.

  • Method Details

    • create

      public static JsonList create()
      Construct an empty list.
      Returns:
      An empty list.

    • of

      public static JsonList of(Collection<?> values)
      Construct a list initialized with the specified list.
      Parameters:
      values - The list to copy.
      Can be null (returns null).
      Returns:
      A new list or null if the list was null.

    • of

      public static JsonList of(Object... values)
      Construct a list initialized with the specified values.
      Parameters:
      values - The values to add to this list.
      Returns:
      A new list, never null.

    • ofArrays

      public static JsonList ofArrays(Object[]... values)
      Convenience method for creating a list of array objects.
      Parameters:
      values - The initial values.
      Returns:
      A new list.

    • ofCollections

      public static JsonList ofCollections(Collection<?>... values)
      Convenience method for creating a list of collection objects.
      Parameters:
      values - The initial values.
      Returns:
      A new list.

    • ofString

      public static JsonList ofString(CharSequence json) throws ParseException
      Construct a list initialized with the specified JSON string.
      Parameters:
      json - The JSON text to parse.
      Can be normal or simplified JSON.
      Returns:
      A new list (empty if the input was null), never null.
      Throws:
      ParseException - Malformed input encountered.

    • ofString

      public static JsonList ofString(Reader json) throws ParseException
      Construct a list initialized with the specified reader containing JSON.
      Parameters:
      json - The reader containing JSON text to parse.
      Can contain normal or simplified JSON.
      Returns:
      A new list (empty if the input was null), never null.
      Throws:
      ParseException - Malformed input encountered.

    • ofJsonOrCdl

      public static JsonList ofJsonOrCdl(String s) throws ParseException
      Parses a string that can consist of either a JSON array or comma-delimited list.

      The type of string is auto-detected.

      Parameters:
      s - The string to parse.
      Returns:
      A new list (empty if the input was null or empty), never null.
      Throws:
      ParseException - Malformed input encountered.

    • ofString

      public static JsonList ofString(CharSequence in, Parser p) throws ParseException
      Construct a list initialized with the specified string.
      Parameters:
      in - The input being parsed.
      p - The parser to use to parse the input.
      If null, uses JsonParser.
      Returns:
      A new list (empty if the input was null), never null.
      Throws:
      ParseException - Malformed input encountered.

    • ofString

      public static JsonList ofString(Reader in, Parser p) throws ParseException
      Construct a list initialized with the specified string.
      Parameters:
      in - The reader containing the input being parsed.
      Can contain normal or simplified JSON.
      p - The parser to use to parse the input.
      If null, uses JsonParser.
      Returns:
      A new list (empty if the input was null), never null.
      Throws:
      ParseException - Malformed input encountered.

    • append

      public JsonList append(Collection<?> values)
      Description copied from class: MarshalledList
      Adds all the values in the specified collection to this list.
      Overrides:
      append in class MarshalledList
      Parameters:
      values - The values to add to this list.
      Returns:
      This object.

    • append

      public JsonList append(Object value)
      Description copied from class: MarshalledList
      Adds the value to this list.
      Overrides:
      append in class MarshalledList
      Parameters:
      value - The value to add to this list.
      Returns:
      This object.

    • append

      public JsonList append(Object... values)
      Description copied from class: MarshalledList
      Adds all the values in the specified array to this list.
      Overrides:
      append in class MarshalledList
      Parameters:
      values - The values to add to this list.
      Returns:
      This object.

    • appendIf

      public JsonList appendIf(boolean flag, Object value)
      Description copied from class: MarshalledList
      Adds an entry to this list if the boolean flag is true.
      Overrides:
      appendIf in class MarshalledList
      Parameters:
      flag - The boolean flag.
      value - The value to add.
      Returns:
      This object.

    • appendIf

      public <T> JsonList appendIf(Predicate<T> test, T value)
      Description copied from class: MarshalledList
      Add if predicate matches.
      Overrides:
      appendIf in class MarshalledList
      Type Parameters:
      T - The type being tested.
      Parameters:
      test - The predicate to match against.
      value - The value to add if the predicate matches.
      Returns:
      This object.

    • appendReverse

      public JsonList appendReverse(List<?> values)
      Description copied from class: MarshalledList
      Adds all the entries in the specified collection to this list in reverse order.
      Overrides:
      appendReverse in class MarshalledList
      Parameters:
      values - The collection to add to this list.
      Returns:
      This object.

    • appendReverse

      public JsonList appendReverse(Object... values)
      Description copied from class: MarshalledList
      Adds the contents of the array to the list in reverse order.

      i.e. add values from the array from end-to-start order to the end of the list.

      Overrides:
      appendReverse in class MarshalledList
      Parameters:
      values - The collection to add to this list.
      Returns:
      This object.

    • toJson

      public String toJson()
      Serializes this list to a standard JSON string.
      Returns:
      This object as a standard JSON string.

    • toJson5

      public String toJson5()
      Serializes this list to a JSON5 string.

      A synonym for toString().

      Returns:
      This object as a JSON5 string.

    • toJsonl

      public String toJsonl()
      Serializes this list to a JSON Lines string.
      Returns:
      This object as a JSON Lines string.

    • toJcs

      public String toJcs()
      Serializes this list to a canonical JSON string (RFC 8785).
      Returns:
      This object as a canonical JSON string.

    • toHjson

      public String toHjson()
      Serializes this list to an HJSON string.
      Returns:
      This object as an HJSON string.

    • cast

      public Object cast(ClassMeta<?> cm)
      Converts this object into the specified class type.

      This method performs a round-trip serialization and deserialization to convert the list into the target type.

      Notes:
      • The current implementation uses a serialization round-trip which may be inefficient for frequent conversions of large objects. Consider caching results or using direct object conversion where possible.
      Parameters:
      cm - The class type to convert this object to.
      Returns:
      A converted object.

    • getList

      public JsonList getList(int index)
      Description copied from class: MarshalledList
      Shortcut for calling get(index, MarshalledList.class).
      Overrides:
      getList in class MarshalledList
      Parameters:
      index - The index.
      Returns:
      The converted value.

    • getMap

      public JsonMap getMap(int index)
      Description copied from class: MarshalledList
      Shortcut for calling get(index, MarshalledMap.class).
      Overrides:
      getMap in class MarshalledList
      Parameters:
      index - The index.
      Returns:
      The converted value.

    • modifiable

      public JsonList modifiable()
      Description copied from class: MarshalledList
      Returns a modifiable copy of this list if it's unmodifiable.
      Overrides:
      modifiable in class MarshalledList
      Returns:
      A modifiable copy of this list if it's unmodifiable, or this list if it is already modifiable.

    • session

      public JsonList session(MarshallingSession session)
      Description copied from class: MarshalledList
      Override the default bean session used for converting POJOs.

      Default is MarshallingContext.DEFAULT, which is sufficient in most cases.

      Useful if you're serializing/parsing beans with transforms defined.

      Overrides:
      session in class MarshalledList
      Parameters:
      session - The new bean session.
      Returns:
      This object.

    • setBeanSession

      public JsonList setBeanSession(MarshallingSession value)
      Description copied from class: MarshalledList
      Sets the MarshallingSession currently associated with this list.
      Overrides:
      setBeanSession in class MarshalledList
      Parameters:
      value - The MarshallingSession currently associated with this list.
      Returns:
      This object.

    • toString

      public String toString()
      Overrides:
      toString in class AbstractCollection<Object>

    • unmodifiable

      public JsonList unmodifiable()
      Description copied from class: MarshalledList
      Returns an unmodifiable copy of this list if it's modifiable.
      Overrides:
      unmodifiable in class MarshalledList
      Returns:
      An unmodifiable copy of this list if it's modifiable, or this list if it is already unmodifiable.

    • writeTo

      public JsonList writeTo(Writer w) throws IOException, SerializeException
      Convenience method for serializing this JsonList to the specified Writer using the Json.DEFAULT marshaller.
      Parameters:
      w - The writer to send the serialized contents of this object.
      Returns:
      This object.
      Throws:
      IOException - If a problem occurred trying to write to the writer.
      SerializeException - If a problem occurred trying to convert the output.