public class SimpleSequence extends WrappingTemplateModel implements TemplateSequenceModel, java.io.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
).
It also matters if for 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 faster. 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 java.util.List |
list
The
List that stored the elements of this sequence. |
NOTHING
Constructor and Description |
---|
SimpleSequence()
Deprecated.
Use
SimpleSequence(ObjectWrapper) instead. |
SimpleSequence(java.util.Collection collection)
Deprecated.
|
SimpleSequence(java.util.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(java.lang.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() |
java.util.List |
toList()
Deprecated.
No replacement exists; not a reliable way of getting back the original list elemnts.
|
java.lang.String |
toString() |
getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrap
protected final java.util.List list
List
that stored the elements of this sequence. It migth contains both TemplateModel
elements
and non-TemplateModel
elements.@Deprecated public SimpleSequence()
SimpleSequence(ObjectWrapper)
instead.WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
.@Deprecated public SimpleSequence(int capacity)
SimpleSequence(int, ObjectWrapper)
.WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
.@Deprecated public SimpleSequence(java.util.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.TemplateModelException
public 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(java.util.Collection collection, ObjectWrapper wrapper)
Collection
; consider
using DefaultListAdapter
instead.collection
- The collection containing the initial items of the sequence. A shallow 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(java.lang.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.@Deprecated 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.@Deprecated public java.util.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.TemplateModelException
public 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 TemplateSequenceModel
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.TemplateModelException
public int size()
size
in interface TemplateSequenceModel
public SimpleSequence synchronizedWrapper()
public java.lang.String toString()
toString
in class java.lang.Object