public class SimpleSequence extends WrappingTemplateModel implements TemplateSequenceModel, Serializable
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.
| Modifier and Type | Field and Description |
|---|---|
protected List |
list
The
List that stored the elements of this sequence. |
NOTHING| Constructor and Description |
|---|
SimpleSequence()
Deprecated.
Use
SimpleSequence(ObjectWrapper) instead. |
SimpleSequence(Collection collection)
Deprecated.
|
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.
|
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.
|
| 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() |
getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrapprotected final List list
List that stored the elements of this sequence. It migth contains both TemplateModel elements
and non-TemplateModel elements.public SimpleSequence()
SimpleSequence(ObjectWrapper) instead.WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper).public SimpleSequence(int capacity)
SimpleSequence(Collection, ObjectWrapper).WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper).public SimpleSequence(Collection collection)
SimpleSequence(Collection, ObjectWrapper).Collection and will use the the default
object wrapper set in
WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper).collection - the collection containing initial values. Note that a
copy of the collection is made for internal use.public SimpleSequence(TemplateCollectionModel tcm) throws TemplateModelException
add(Object), because the appropriate ObjectWrapper won't be available; use
SimpleSequence(Collection, ObjectWrapper) instead, if you need that.TemplateModelExceptionpublic SimpleSequence(ObjectWrapper wrapper)
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.public SimpleSequence(int capacity,
ObjectWrapper wrapper)
wrapper - See the similar parameter of SimpleSequence(ObjectWrapper).public SimpleSequence(Collection collection, ObjectWrapper wrapper)
Collection; consider
using DefaultListAdapter instead.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).public void add(Object obj)
TemplateModel interface, it will be wrapped into the appropriate TemplateModel interface when
it's first read (lazily).obj - The object to be added.public void add(boolean b)
add(Object) instead, as this bypasses the ObjectWrapper.TemplateBooleanModel.TRUE or TemplateBooleanModel.FALSE, without using the ObjectWrapper.b - The boolean value to be added.public List toList() throws TemplateModelException
TemplateModel-s. When called for the second time (or later), it just reuses the first result, unless the
sequence was modified since then.TemplateModelExceptionpublic TemplateModel get(int index) throws TemplateModelException
TemplateModel, it will wrap
it to one now, and writes it back into the backing list.get in interface TemplateSequenceModelnull 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.TemplateModelExceptionpublic int size()
size in interface TemplateSequenceModelpublic SimpleSequence synchronizedWrapper()