Package org.apache.juneau.marshall.collections

Class MarshalledList

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
All Implemented Interfaces:
Serializable, Cloneable, Iterable<Object>, Collection<Object>, Deque<Object>, List<Object>, Queue<Object>
Direct Known Subclasses:
Json5List, JsonList
public class MarshalledList extends LinkedList<Object>
Neutral, marshaller-agnostic list of objects.

This class is the base for JsonList and the per-marshaller XList variants. It carries all marshaller-neutral functionality such as typed accessors, fluent setters, bean integration, and PathTraversal-based path navigation. The default AbstractCollection.toString() comes from LinkedList; subclasses should override it to produce the appropriate marshalled form.

Note that the use of this class is optional. The serializers will accept any objects that implement the Collection interface. But this class provides useful additional functionality when working with data models constructed from Java Collections Framework objects.

Notes:
  • This class is not thread safe.

  • Field Details

  • Constructor Details

    • MarshalledList

      public MarshalledList()
      Construct an empty list.

    • MarshalledList

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

    • MarshalledList

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

    • MarshalledList

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

    • MarshalledList

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

    • MarshalledList

      public MarshalledList(Reader in, Parser p) throws ParseException
      Construct a list initialized by parsing the specified reader with the specified parser.
      Parameters:
      in - The reader containing the input being parsed.
      p - The parser to use to parse the input.
      Must not be null.
      Throws:
      ParseException - Malformed input encountered.

  • Method Details

    • create

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

    • of

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

    • of

      public static MarshalledList 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 MarshalledList ofArrays(Object[]... values)
      Convenience method for creating a list of array objects.
      Parameters:
      values - The initial values.
      Returns:
      A new list.

    • ofCollections

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

    • ofString

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

    • ofString

      public static MarshalledList ofString(Reader in, Parser p) throws ParseException
      Construct a list initialized by parsing the specified reader with the specified parser.
      Parameters:
      in - The reader containing the input being parsed.
      p - The parser to use to parse the input.
      Must not be null.
      Returns:
      A new list (empty if the input was null), never null.
      Throws:
      ParseException - Malformed input encountered.

    • append

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

    • append

      public MarshalledList append(Object value)
      Adds the value to this list.
      Parameters:
      value - The value to add to this list.
      Returns:
      This object.

    • append

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

    • appendIf

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

    • appendIf

      public <T> MarshalledList appendIf(Predicate<T> test, T value)
      Add if predicate matches.
      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 MarshalledList appendReverse(List<?> values)
      Adds all the entries in the specified collection to this list in reverse order.
      Parameters:
      values - The collection to add to this list.
      Returns:
      This object.

    • appendReverse

      public MarshalledList appendReverse(Object... values)
      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.

      Parameters:
      values - The collection to add to this list.
      Returns:
      This object.

    • at

      public MarshalledNode at(String pointer)
      Returns the node addressed by the specified RFC 6901 JSON Pointer relative to this list.

      Convenience for MarshalledNode.of(this).at(pointer). A read-miss returns null; an addressed JSON null value returns a null node.

      Beta — API subject to change: This method is part of the next-generation typed tree model layered over the Marshalled* collections and may change incompatibly in a future release.

      Parameters:
      pointer - The RFC 6901 JSON Pointer.
      Returns:
      A node wrapping the addressed value, or null if the addressed value is absent.

    • toString

      public String toString(WriterSerializer serializer)
      Serializes this list to a string using the specified serializer.
      Parameters:
      serializer - The serializer to use to convert this object to a string.
      Returns:
      This object as a serialized string.

    • deleteAt

      public Object deleteAt(String path)
      Similar to remove(int),but the key is a slash-delimited path used to traverse entries in this POJO.

      This method uses the PathTraversal class to perform the lookup, so the map can contain any of the various class types that the PathTraversal class supports (e.g. beans, collections, arrays).

      Parameters:
      path - The path to the entry.
      Returns:
      The previous value, or null if the entry doesn't exist.

    • elements

      public <E> Iterable<E> elements(Class<E> childType)
      Creates an Iterable with elements of the specified child type.

      Attempts to convert the child objects to the correct type if they aren't already the correct type.

      The next() method on the returned iterator may throw a InvalidDataConversionException if the next element cannot be converted to the specified type.

      See MarshallingSession.convertToType(Object, ClassMeta) for a description of valid conversions.

      Type Parameters:
      E - The child object type.
      Parameters:
      childType - The child object type.
      Returns:
      A new Iterable object over this list.

    • get

      public <T> T get(int index, Class<T> type)
      Get the entry at the specified index, converted to the specified type.

      See MarshallingSession.convertToType(Object, ClassMeta) for the list of valid data conversions.

      Type Parameters:
      T - The type of object to convert the entry to.
      Parameters:
      index - The index into this list.
      type - The type of object to convert the entry to.
      Returns:
      The converted entry.

    • get

      public <T> T get(int index, Type type, Type... args)
      Get the entry at the specified index, converted to the specified type.

      See MarshallingSession.convertToType(Object, ClassMeta) for the list of valid data conversions.

      Type Parameters:
      T - The type of object to convert the entry to.
      Parameters:
      index - The index into this list.
      type - The type of object to convert the entry to.
      args - The type arguments of the type to convert the entry to.
      Returns:
      The converted entry.

    • getAt

      public <T> T getAt(String path, Class<T> type)
      Same as get(int,Class), but the key is a slash-delimited path used to traverse entries in this POJO.
      Type Parameters:
      T - The class type.
      Parameters:
      path - The path to the entry.
      type - The class type.
      Returns:
      The value, or null if the entry doesn't exist.

    • getAt

      public <T> T getAt(String path, Type type, Type... args)
      Same as getAt(String,Class), but allows for conversion to complex maps and collections.
      Type Parameters:
      T - The class type.
      Parameters:
      path - The path to the entry.
      type - The class type.
      args - The class parameter types.
      Returns:
      The value, or null if the entry doesn't exist.

    • getBoolean

      public Boolean getBoolean(int index)
      Shortcut for calling get(index, Boolean.class).
      Parameters:
      index - The index.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getClassMeta

      public ClassMeta<?> getClassMeta(int index)
      Returns the ClassMeta of the class of the object at the specified index.
      Parameters:
      index - An index into this list, zero-based.
      Returns:
      The data type of the object at the specified index, or null if the value is null.

    • getInt

      public Integer getInt(int index)
      Shortcut for calling get(index, Integer.class).
      Parameters:
      index - The index.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getList

      public MarshalledList getList(int index)
      Shortcut for calling get(index, MarshalledList.class).
      Parameters:
      index - The index.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getList

      public <E> List<E> getList(int index, Class<E> elementType)
      Same as getList(int) except converts the elements to the specified types.
      Type Parameters:
      E - The element type.
      Parameters:
      index - The index.
      elementType - The element type class.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getLong

      public Long getLong(int index)
      Shortcut for calling get(index, Long.class).
      Parameters:
      index - The index.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getMap

      public MarshalledMap getMap(int index)
      Shortcut for calling get(index, MarshalledMap.class).
      Parameters:
      index - The index.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getMap

      public <K, V> Map<K,V> getMap(int index, Class<K> keyType, Class<V> valType)
      Same as getMap(int) except converts the keys and values to the specified types.
      Type Parameters:
      K - The key type class.
      V - The value type class.
      Parameters:
      index - The index.
      keyType - The key type class.
      valType - The value type class.
      Returns:
      The converted value.
      Throws:
      InvalidDataConversionException - If value cannot be converted.

    • getMarshallingSession

      public MarshallingSession getMarshallingSession()
      Returns the MarshallingSession currently associated with this list.
      Returns:
      The MarshallingSession currently associated with this list.

    • getString

      public String getString(int index)
      Shortcut for calling get(index, String.class).
      Parameters:
      index - The index.
      Returns:
      The converted value.

    • isUnmodifiable

      public boolean isUnmodifiable()
      Returns true if this list is unmodifiable.
      Returns:
      true if this list is unmodifiable.

    • modifiable

      public MarshalledList modifiable()
      Returns a modifiable copy of this list if it's unmodifiable.
      Returns:
      A modifiable copy of this list if it's unmodifiable, or this list if it is already modifiable.

    • postAt

      public Object postAt(String path, Object o)
      Similar to putAt(String,Object), but used to append to collections and arrays.

      This method uses the PathTraversal class to perform the lookup, so the map can contain any of the various class types that the PathTraversal class supports (e.g. beans, collections, arrays).

      Parameters:
      path - The path to the entry.
      o - The new value.
      Returns:
      The previous value, or null if the entry doesn't exist.

    • putAt

      public Object putAt(String path, Object o)
      Same as set(int,Object), but the key is a slash-delimited path used to traverse entries in this POJO.

      This method uses the PathTraversal class to perform the lookup, so the map can contain any of the various class types that the PathTraversal class supports (e.g. beans, collections, arrays).

      Parameters:
      path - The path to the entry.
      o - The new value.
      Returns:
      The previous value, or null if the entry doesn't exist.

    • session

      public MarshalledList session(MarshallingSession session)
      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.

      Parameters:
      session - The new bean session.
      Returns:
      This object.

    • setBeanSession

      public MarshalledList setBeanSession(MarshallingSession value)
      Sets the MarshallingSession currently associated with this list.
      Parameters:
      value - The MarshallingSession currently associated with this list.
      Returns:
      This object.

    • unmodifiable

      public MarshalledList unmodifiable()
      Returns an unmodifiable copy of this list if it's modifiable.
      Returns:
      An unmodifiable copy of this list if it's modifiable, or this list if it is already unmodifiable.

    • bs

      protected MarshallingSession bs()
      Returns the MarshallingSession associated with this list (lazily defaults to MarshallingContext.DEFAULT_SESSION).
      Returns:
      The MarshallingSession for this list.