Class SimpleSequence
- All Implemented Interfaces:
TemplateModel,TemplateSequenceModel,Serializable
- Direct Known Subclasses:
SimpleList
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.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected ListTheListthat stored the elements of this sequence.Fields inherited from interface freemarker.template.TemplateModel
NOTHING -
Constructor Summary
ConstructorsConstructorDescriptionDeprecated.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.Constructs a simple sequence from the passed collection model, which shouldn't be added to later.SimpleSequence(Collection collection)Deprecated.SimpleSequence(Collection collection, ObjectWrapper wrapper)Constructs a simple sequence that will contain the elements from the specifiedCollection; consider usingDefaultListAdapterinstead. -
Method Summary
Modifier and TypeMethodDescriptionvoidadd(boolean b)Deprecated.Useadd(Object)instead, as this bypasses theObjectWrapper.voidAdds an arbitrary object to the end of this sequence.get(int index)Returns the item at the specified index of the list.intsize()toList()Deprecated.No replacement exists; not a reliable way of getting back the original list elemnts.toString()Methods inherited from class freemarker.template.WrappingTemplateModel
getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrap
-
Field Details
-
list
TheListthat stored the elements of this sequence. It migth contains bothTemplateModelelements and non-TemplateModelelements.
-
-
Constructor Details
-
SimpleSequence
Deprecated.UseSimpleSequence(ObjectWrapper)instead.Constructs an empty simple sequence that will use the the default object wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper). -
SimpleSequence
Deprecated.Constructs an empty simple sequence with preallocated capacity and using the default object wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper). -
SimpleSequence
Deprecated.Constructs a simple sequence that will contain the elements from the specifiedCollectionand 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
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 appropriateObjectWrapperwon't be available; useSimpleSequence(Collection, ObjectWrapper)instead, if you need that.- Throws:
TemplateModelException
-
SimpleSequence
Constructs an empty sequence using the specified object wrapper.- Parameters:
wrapper- The object wrapper to use to wrap the list items intoTemplateModelinstances.nullis allowed, but deprecated, and will cause the deprecated default object wrapper (set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)) to be used.
-
SimpleSequence
Constructs an empty simple sequence with preallocated capacity.- Parameters:
wrapper- See the similar parameter ofSimpleSequence(ObjectWrapper).- Since:
- 2.3.21
-
SimpleSequence
Constructs a simple sequence that will contain the elements from the specifiedCollection; consider usingDefaultListAdapterinstead.- 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 theObjectWrapperlazily, when first needed.wrapper- See the similar parameter ofSimpleSequence(ObjectWrapper).
-
-
Method Details
-
add
Adds an arbitrary object to the end of this sequence. If the newly added object does not implement theTemplateModelinterface, it will be wrapped into the appropriateTemplateModelinterface when it's first read (lazily).- Parameters:
obj- The object to be added.
-
add
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.TRUEorTemplateBooleanModel.FALSE, without using theObjectWrapper.- Parameters:
b- The boolean value to be added.
-
toList
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
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:
getin interfaceTemplateSequenceModel- Returns:
- the item at the specified index, or
nullif the index is out of bounds. Note that anullvalue 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:
sizein interfaceTemplateSequenceModel- Returns:
- the number of items in the list.
-
synchronizedWrapper
- Returns:
- a synchronized wrapper for list.
-
toString
-
SimpleSequence(ObjectWrapper)instead.