Class SimpleSequence
- java.lang.Object
-
- freemarker.template.WrappingTemplateModel
-
- freemarker.template.SimpleSequence
-
- All Implemented Interfaces:
TemplateModel
,TemplateSequenceModel
,java.io.Serializable
- Direct Known Subclasses:
SimpleList
public class SimpleSequence extends WrappingTemplateModel implements TemplateSequenceModel, java.io.Serializable
A simple implementation of theTemplateSequenceModel
interface, using its own underlyingList
for storing the list items. If you are wrapping an already existingList
orarray
, you should certainly useDefaultMapAdapter
orDefaultArrayAdapter
(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
VSDefaultListAdapter
/DefaultArrayAdapter
- Which to use when?For a
List
orarray
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 withadd(Object)
is usually the way to go, as the resulting sequence is significantly faster to read from templates than aDefaultListAdapter
(though it's somewhat slower to read from a plain Java method to which it had to be passed adapted to aList
).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) thenDefaultMapAdapter
will be faster. Before choosing based on performance though, pay attention to the behavioral differences;SimpleSequence
will shallow-copy the originalList
at construction time, so it won't reflectList
content changes after theSimpleSequence
construction, alsoSimpleSequence
can't be unwrapped to the original wrapped instance.
-
-
Field Summary
Fields Modifier and Type Field Description protected java.util.List
list
TheList
that stored the elements of this sequence.-
Fields inherited from interface freemarker.template.TemplateModel
NOTHING
-
-
Constructor Summary
Constructors Constructor Description SimpleSequence()
Deprecated.UseSimpleSequence(ObjectWrapper)
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.SimpleSequence(java.util.Collection collection)
Deprecated.SimpleSequence(java.util.Collection collection, ObjectWrapper wrapper)
Constructs a simple sequence that will contain the elements from the specifiedCollection
; consider usingDefaultListAdapter
instead.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
add(boolean b)
Deprecated.Useadd(Object)
instead, as this bypasses theObjectWrapper
.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()
-
Methods inherited from class freemarker.template.WrappingTemplateModel
getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrap
-
-
-
-
Field Detail
-
list
protected final java.util.List list
TheList
that stored the elements of this sequence. It migth contains bothTemplateModel
elements and non-TemplateModel
elements.
-
-
Constructor Detail
-
SimpleSequence
@Deprecated public SimpleSequence()
Deprecated.UseSimpleSequence(ObjectWrapper)
instead.Constructs an empty simple sequence that will use the the default object wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
.
-
SimpleSequence
@Deprecated public SimpleSequence(int capacity)
Deprecated.Constructs an empty simple sequence with preallocated capacity and using the default object wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
.
-
SimpleSequence
@Deprecated public SimpleSequence(java.util.Collection collection)
Deprecated.Constructs a simple sequence that will contain the elements from the specifiedCollection
and will use the the default object wrapper set inWrappingTemplateModel.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 withadd(Object)
, because the appropriateObjectWrapper
won't be available; useSimpleSequence(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 intoTemplateModel
instances.null
is allowed, but deprecated, and will cause the deprecated default object wrapper (set inWrappingTemplateModel.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 ofSimpleSequence(ObjectWrapper)
.- Since:
- 2.3.21
-
SimpleSequence
public SimpleSequence(java.util.Collection collection, ObjectWrapper wrapper)
Constructs a simple sequence that will contain the elements from the specifiedCollection
; consider usingDefaultListAdapter
instead.- Parameters:
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 theObjectWrapper
lazily, when first needed.wrapper
- See the similar parameter ofSimpleSequence(ObjectWrapper)
.
-
-
Method Detail
-
add
public void add(java.lang.Object obj)
Adds an arbitrary object to the end of this sequence. If the newly added object does not implement theTemplateModel
interface, it will be wrapped into the appropriateTemplateModel
interface when it's first read (lazily).- Parameters:
obj
- The object to be added.
-
add
@Deprecated public void add(boolean b)
Deprecated.Useadd(Object)
instead, as this bypasses theObjectWrapper
.Adds a boolean value to the end of this sequence. The newly added boolean will be immediately converted intoTemplateBooleanModel.TRUE
orTemplateBooleanModel.FALSE
, without using theObjectWrapper
.- Parameters:
b
- The boolean value to be added.
-
toList
@Deprecated public java.util.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 toTemplateModel
-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 anTemplateModel
, it will wrap it to one now, and writes it back into the backing list.- Specified by:
get
in interfaceTemplateSequenceModel
- Returns:
- the item at the specified index, or
null
if the index is out of bounds. Note that anull
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 interfaceTemplateSequenceModel
- Returns:
- the number of items in the list.
-
synchronizedWrapper
public SimpleSequence synchronizedWrapper()
- Returns:
- a synchronized wrapper for list.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-