SimpleSequence (FreeMarker 2.3.23 API)
Date: 2015-07-05

freemarker.template

## Class SimpleSequence

- java.lang.Object
- - freemarker.template.WrappingTemplateModel
  - - freemarker.template.SimpleSequence

- All Implemented Interfaces:
    TemplateModel, TemplateSequenceModel, Serializable
  Direct Known Subclasses:
    SimpleList

      public class SimpleSequence
      extends WrappingTemplateModel
      implements TemplateSequenceModel, Serializable

  A simple implementation of the `TemplateSequenceModel` interface, using its own underlying `List` for storing the list items. If you are wrapping an already existing `List` or `array`, you should certainly use `DefaultMapAdapter` or `DefaultArrayAdapter` (see comparison below).

  This class is thread-safe if you don't call modifying methods (like `add(Object)`) after you have made the object available for multiple threads (assuming you have published it safely to the other threads; see JSR-133 Java Memory Model). These methods aren't called by FreeMarker, so it's usually not a concern.

  `SimpleSequence` VS `DefaultListAdapter`/`DefaultArrayAdapter` - Which to use when?

  For a `List` or `array` that exists regardless of FreeMarker, only you need to access it from templates, `DefaultMapAdapter` should be the default choice, as it can be unwrapped to the originally wrapped object (important when passing it to Java methods from the template). It also has more predictable performance (no spikes).

  For a sequence that's made specifically to be used from templates, creating an empty `SimpleSequence` then filling it with `add(Object)` is usually the way to go, as the resulting sequence is significantly faster to read from templates than a `DefaultListAdapter` (though it's somewhat slower to read from a plain Java method to which it had to be passed adapted to a `List`).

  If regardless of which of the above two cases stand, you just need to (or more convenient to) create the sequence from a `List` (via `DefaultListAdapter.adapt(List, freemarker.template.utility.RichObjectWrapper)` or `SimpleSequence(Collection)`), which will be the faster depends on how many times will the same `List` entry be read from the template(s) later, on average. If, on average, you read each entry for more than 4 times, `SimpleSequence` will be most certainly faster, but if for 2 times or less (and especially if not at all) then `DefaultMapAdapter` will be. Before choosing based on performance though, pay attention to the behavioral differences; `SimpleSequence` will shallow-copy the original `List` at construction time, so it won't reflect `List` content changes after the `SimpleSequence` construction, also `SimpleSequence` can't be unwrapped to the original wrapped instance.

  See Also:
    `DefaultListAdapter`, `DefaultArrayAdapter`, `TemplateSequenceModel`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected List` | `list` The `List` that stored the elements of this sequence.

    - ### Fields inherited from interface freemarker.template.TemplateModel

      `NOTHING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleSequence()` Deprecated. Use `SimpleSequence(ObjectWrapper)` instead.
    `SimpleSequence(Collection collection)` Deprecated. Use `SimpleSequence(Collection, ObjectWrapper)`.
    `SimpleSequence(Collection collection, ObjectWrapper wrapper)` Constructs a simple sequence that will contain the elements from the specified `Collection`; consider using `DefaultListAdapter` instead.
    `SimpleSequence(int capacity)` Deprecated. Use `SimpleSequence(Collection, ObjectWrapper)`.
    `SimpleSequence(int capacity, ObjectWrapper wrapper)` Constructs an empty simple sequence with preallocated capacity.
    `SimpleSequence(ObjectWrapper wrapper)` Constructs an empty sequence using the specified object wrapper.
    `SimpleSequence(TemplateCollectionModel tcm)` Constructs a simple sequence from the passed collection model, which shouldn't be added to later.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(boolean b)` Deprecated. Use `add(Object)` instead, as this bypasses the `ObjectWrapper`.
    `void` | `add(Object obj)` Adds an arbitrary object to the end of this sequence.
    `TemplateModel` | `get(int index)` Returns the item at the specified index of the list.
    `int` | `size()`
    `SimpleSequence` | `synchronizedWrapper()`
    `List` | `toList()` Deprecated. No replacement exists; not a reliable way of getting back the original list elemnts.
    `String` | `toString()`

    - ### Methods inherited from class freemarker.template.WrappingTemplateModel

      `getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrap`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### list

          protected final List list

      The `List` that stored the elements of this sequence. It migth contains both `TemplateModel` elements and non-`TemplateModel` elements.

  - ### Constructor Detail

    - #### SimpleSequence

          public SimpleSequence()

      Deprecated. Use `SimpleSequence(ObjectWrapper)` instead.
      Constructs an empty simple sequence that will use the the default object wrapper set in `WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)`.

    - #### SimpleSequence

          public SimpleSequence(int capacity)

      Deprecated. Use `SimpleSequence(Collection, ObjectWrapper)`.
      Constructs an empty simple sequence with preallocated capacity and using the default object wrapper set in `WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)`.

    - #### SimpleSequence

          public SimpleSequence(Collection collection)

      Deprecated. Use `SimpleSequence(Collection, ObjectWrapper)`.
      Constructs a simple sequence that will contain the elements from the specified `Collection` and will use the the default object wrapper set in `WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)`.
      Parameters:
        `collection` - the collection containing initial values. Note that a copy of the collection is made for internal use.

    - #### SimpleSequence

          public SimpleSequence(TemplateCollectionModel tcm)
                         throws TemplateModelException

      Constructs a simple sequence from the passed collection model, which shouldn't be added to later. The internal list will be build immediately (not lazily). The resulting sequence shouldn't be extended with `add(Object)`, because the appropriate `ObjectWrapper` won't be available; use `SimpleSequence(Collection, ObjectWrapper)` instead, if you need that.
      Throws:
        `TemplateModelException`

    - #### SimpleSequence

          public SimpleSequence(ObjectWrapper wrapper)

      Constructs an empty sequence using the specified object wrapper.
      Parameters:
        `wrapper` - The object wrapper to use to wrap the list items into `TemplateModel` instances. `null` is allowed, but deprecated, and will cause the deprecated default object wrapper (set in `WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)`) to be used.

    - #### SimpleSequence

          public SimpleSequence(int capacity,
                                ObjectWrapper wrapper)

      Constructs an empty simple sequence with preallocated capacity.
      Parameters:
        `wrapper` - See the similar parameter of `SimpleSequence(ObjectWrapper)`.
      Since:
        2.3.21

    - #### SimpleSequence

          public SimpleSequence(Collection collection,
                                ObjectWrapper wrapper)

      Constructs a simple sequence that will contain the elements from the specified `Collection`; consider using `DefaultListAdapter` instead.
      Parameters:
        `collection` - The collection containing the initial items of this sequence. A shalow copy of this collection is made immediately for internal use (thus, later modification on the parameter collection won't be visible in the resulting sequence). The items however, will be only wrapped with the `ObjectWrapper` lazily, when first needed.
        `wrapper` - See the similar parameter of `SimpleSequence(ObjectWrapper)`.

  - ### Method Detail

    - #### add

          public void add(Object obj)

      Adds an arbitrary object to the end of this sequence. If the newly added object does not implement the `TemplateModel` interface, it will be wrapped into the appropriate `TemplateModel` interface when it's first read (lazily).
      Parameters:
        `obj` - The object to be added.

    - #### add

          public void add(boolean b)

      Deprecated. Use `add(Object)` instead, as this bypasses the `ObjectWrapper`.
      Adds a boolean value to the end of this sequence. The newly added boolean will be immediately converted into `TemplateBooleanModel.TRUE` or `TemplateBooleanModel.FALSE`, without using the `ObjectWrapper`.
      Parameters:
        `b` - The boolean value to be added.

    - #### toList

          public List toList()
                      throws TemplateModelException

      Deprecated. No replacement exists; not a reliable way of getting back the original list elemnts.
      Builds a deep-copy of the underlying list, unwrapping any values that were already converted to `TemplateModel`-s. When called for the second time (or later), it just reuses the first result, unless the sequence was modified since then.
      Throws:
        `TemplateModelException`

    - #### get

          public TemplateModel get(int index)
                            throws TemplateModelException

      Returns the item at the specified index of the list. If the item isn't yet an `TemplateModel`, it will wrap it to one now, and writes it back into the backing list.
      Specified by:
        `get` in interface `TemplateSequenceModel`
      Returns:
        the item at the specified index, or `null` if the index is out of bounds. Note that a `null` value is interpreted by FreeMarker as "variable does not exist", and accessing a missing variables is usually considered as an error in the FreeMarker Template Language, so the usage of a bad index will not remain hidden, unless the default value for that case was also specified in the template.
      Throws:
        `TemplateModelException`

    - #### size

          public int size()

      Specified by:
        `size` in interface `TemplateSequenceModel`
      Returns:
        the number of items in the list.

    - #### synchronizedWrapper

          public SimpleSequence synchronizedWrapper()

      Returns:
        a synchronized wrapper for list.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`