Data Models

List models are like Arrays or LinkedLists in Java. A TemplateListModel gives you an ordered list of elements, which can be iterated over, using foreach or list syntax, or can be indexed directly by number.

Lists have one other attribute, the size of the list.

To support all of these operations, the TemplateListModel interface is more complex, as we see below:

public TemplateModel get(int i)
                  throws TemplateModelException;

The above method is used by FreeMarker when a template wants to index directly into a list. If in practise, you templates only use the foreach or list syntax, this method can safely throw a TemplateModelException.

The following methods allow FreeMarker to iterate over a list:

public boolean hasNext()
                throws TemplateModelException;

public TemplateModel next()
                   throws TemplateModelException;

public boolean isRewound()
                  throws TemplateModelException;

public void rewind()
            throws TemplateModelException;

The hasNext() and next() methods are used to determine when we're at the end of a list, and to return the next element in the list respectively. These correspond to the same method names in the Java util.Iterator interface.

The isRewound() and rewind() methods are used when a template needs to return to the beginning of a list, in order to iterate over it again.

Finally, the list size is retrieved from the following method:

public TemplateModel listSize()
                       throws TemplateModelException;

If your implementation will never use the list.size functionality of the FreeMarker template syntax, this method can safely throw a TemplateModelException.

Note:
FreeMarker does not use the listSize() method when iterating over a list. There may be situations where the list size may be unknown until the last item in the list has been reached, for instance, when iterating over the result set of some database query. For iteration, only the hasNext() method is used to determine the end of a list.

Previous: Scalar Models

Next: Hash Models