freemarker.ext.misc
Class ExtendedList

java.lang.Object
  freemarker.template.SimpleList
      freemarker.ext.misc.ExtendedList

All Implemented Interfaces:

TemplateHashModel, TemplateIndexedModel, TemplateListModel2, TemplateModel, TemplateObjectModel, java.io.Serializable

public class ExtendedList
extends SimpleList
implements TemplateHashModel, java.io.Serializable

Simple extension to the SimpleList implementation. This class implements a number of convenience facilities in the form of template hash keys. The hash keys are:

• _size - retrieves the size of the list
• _first - retrieves the first item in the list (always), or null if the list is empty
• _last - retrieves the last item in the list (always), or null if the list is empty

Note: the _isLast key has now been moved to the ExtendedIterator class.

An ExtendedList can also be given a shelf life; it then keeps track of the time elapsed since the last time it copied another TemplateListModel, TemplateModel array, or the last time its shelf life was set. Its owner can check whether it has become stale, and refresh it if necessary by copying data into it again.

When this model is serialized and deserialized, the newly deserialized object has its timeCreated member variable reset to the current time. In other words, the time until expiry will be reset to the current shelf life following deserialization.

Since:

1.7

Version:

$Id: ExtendedList.java 1101 2013-04-01 04:17:32Z run2000 $

See Also:

ExtendedHash, Serialized Form

Field Summary

protected boolean	isPermanent
protected static int	MS_PER_MINUTE
protected long	shelfLife
protected long	timeCreated The creation time to be used for determining staleness.

Fields inherited from class freemarker.template.SimpleList

list

Constructor Summary

ExtendedList()
Creates new ExtendedList.

ExtendedList(java.util.List<? extends TemplateModel> list)
Creates new ExtendedList given a List of values.

ExtendedList(TemplateListModel listToCopy)
Creates new ExtendedList populated by copying the given TemplateListModel.

ExtendedList(TemplateListModel2 listToCopy)
Creates new ExtendedList populated by copying the given TemplateListModel2.

ExtendedList(TemplateModel[] arr)
Creates new ExtendedList populated by the TemplateModel array.

Method Summary

void	copy(TemplateListModel listToCopy) Delegates to the underlying SimpleList copy method.
void	copy(TemplateListModel2 listToCopy) Delegates to the underlying SimpleList copy method.
void	copy(TemplateModel[] arr) Delegates to the underlying SimpleList copy method.
boolean	equals(java.lang.Object o) Attempt to compare ExtendedList objects for equality.
TemplateModel	get(java.lang.String key) Gets one of the special keys that the ExtendedList implementation provides.
int	getShelfLife()
int	hashCode() Generate a hash code for this object based on the hash code for the SimpleList.
boolean	isPermanent()
boolean	isStale()
void	releaseIterator(TemplateIteratorModel iterator) Returns the used iterator to the list model.
void	setPermanent() Gives this ExtendedList an indefinite shelf life.
void	setShelfLife(int minutes) Sets the amount of time before this ExtendedList will become stale.
TemplateIteratorModel	templateIterator() Retrieves an iterator to iterate over this list.

Methods inherited from class freemarker.template.SimpleList

add, add, add, add, add, clear, getAsObject, getAtIndex, isEmpty, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface freemarker.template.TemplateModel

isEmpty

Field Detail

MS_PER_MINUTE

protected static final int MS_PER_MINUTE

See Also:

Constant Field Values

timeCreated

protected transient long timeCreated

The creation time to be used for determining staleness.

shelfLife

protected long shelfLife

isPermanent

protected boolean isPermanent

Constructor Detail

ExtendedList

public ExtendedList()

Creates new ExtendedList.

ExtendedList

public ExtendedList(java.util.List<? extends TemplateModel> list)

Creates new ExtendedList given a List of values. A defensive copy of the list is made.

Parameters:

list - the list of values to be copied into this ExtendedList

Throws:

java.lang.NullPointerException - the list value is null

ExtendedList

public ExtendedList(TemplateModel[] arr)

Creates new ExtendedList populated by the TemplateModel array.

Parameters:

arr - the array to be copied into the underlying List.

ExtendedList

public ExtendedList(TemplateListModel listToCopy)
             throws TemplateModelException

Creates new ExtendedList populated by copying the given TemplateListModel.

Parameters:

listToCopy - the list to be copied into this one.

Throws:

TemplateModelException - something went wrong while copying the given list into the ExtendedList.

ExtendedList

public ExtendedList(TemplateListModel2 listToCopy)
             throws TemplateModelException

Creates new ExtendedList populated by copying the given TemplateListModel2.

Parameters:

listToCopy - the list to be copied into this one.

Throws:

TemplateModelException - something went wrong while copying the given list into the ExtendedList.

Method Detail

get

public TemplateModel get(java.lang.String key)
                  throws TemplateModelException

Gets one of the special keys that the ExtendedList implementation provides.

Specified by:

get in interface TemplateHashModel

Parameters:

key - the name of the special value to be retrieved.

Returns:

the TemplateModel referred to by the key, or null if not found.

Throws:

TemplateModelException - there was a problem getting the value for the given key

copy

public void copy(TemplateListModel listToCopy)
          throws TemplateModelException

Delegates to the underlying SimpleList copy method. This variation sets the time that this list was created.

Overrides:

copy in class SimpleList

Parameters:

listToCopy - the list to be copied into this one.

Throws:

TemplateModelException - something went wrong while copying the given list into the SimpleList.

copy

public void copy(TemplateListModel2 listToCopy)
          throws TemplateModelException

Delegates to the underlying SimpleList copy method. This variation sets the time that this list was created.

Overrides:

copy in class SimpleList

Parameters:

listToCopy - the list to be copied into this one.

Throws:

TemplateModelException - something went wrong while copying the given list into the SimpleList.

copy

public void copy(TemplateModel[] arr)

Delegates to the underlying SimpleList copy method. This variation sets the time that this list was created.

Overrides:

copy in class SimpleList

Parameters:

arr - the array to be copied into the underlying list.

setShelfLife

public void setShelfLife(int minutes)

Sets the amount of time before this ExtendedList will become stale.

Parameters:

minutes - the number of minutes before this ExtendedList will become stale.

getShelfLife

public int getShelfLife()

Returns:

this ExtendedList's shelf life in minutes.

setPermanent

public void setPermanent()

Gives this ExtendedList an indefinite shelf life.

isPermanent

public boolean isPermanent()

Returns:

true if this ExtendedList has an indefinite shelf life.

isStale

public boolean isStale()

Returns:

true if this ExtendedList has become stale.

templateIterator

public TemplateIteratorModel templateIterator()
                                       throws TemplateModelException

Retrieves an iterator to iterate over this list.

Specified by:

templateIterator in interface TemplateListModel2

Overrides:

templateIterator in class SimpleList

Returns:

an iterator to iterate over the current list.

Throws:

TemplateModelException - the next item in the list can't be retrieved, or no next item exists.

releaseIterator

public void releaseIterator(TemplateIteratorModel iterator)

Returns the used iterator to the list model.

Specified by:

releaseIterator in interface TemplateListModel2

Overrides:

releaseIterator in class SimpleList

Parameters:

iterator - the iterator to be returned to the object pool, if any

equals

public boolean equals(java.lang.Object o)

Attempt to compare ExtendedList objects for equality.

Overrides:

equals in class SimpleList

Parameters:

o - the object to compare against

Returns:

true if the objects are equal, otherwise false

hashCode

public int hashCode()

Generate a hash code for this object based on the hash code for the SimpleList.

Overrides:

hashCode in class SimpleList

Returns:

a hash code corresponding to the value of this object