Copyright© 2008-2022 Sitevision AB, all rights reserved.
@Requireable(value="ListWrapper") public interface ListWrapper extends Iterable, Wrapper<List>
java.util.List
wrapper that delegates method calls to the wrapped list.
This is a convenience wrapper that bypasses potential problems with the add
method of a java.util.List
.
The List.add
method accepts null
values and returns a boolean
.
When working with Velocity, this boolean gets part of the output if not suppressed via a #set
, #if
,
#elseif
or via ScriptUtil.swallow(Object)
)
An example with the add problem of a java.util.List:
This Velocity code:
#set ($myList = $instanceCreatorUtil.list)
$myList.add("Magnus Lövgren") ## Returns true
$myList.add("Mikael Wikblom") ## Returns true
$someObject.someMethod($myList)
will result in the following Velocity output
(the add
method of List
returns a boolean
):
true true
If a non-void method is invoked and the return value isn't handled, it will be part of the Velocity output.
Using an ListWrapper
will prevent that:
#set ($myList = $instanceCreatorUtil.listWrapper)
myList.add("Magnus Lövgren") ## Silent
myList.add("Mikael Wikblom") ## Silent
$someObject.someMethod($myList.unwrap()) ## Get wrapped List
Important Velocity #foreach note!
Iterating a ListWrapper
via the Velocity #foreach
loop is not possible in all Velocity versions
(proper Iterable
support not present). To ensure proper #foreach
iteration in all Velocity versions,
you should use one of the following alternative ways:
#set ($myList = $instanceCreatorUtil.listWrapper)
...
## ALTERNATIVE A - unwrap, i.e. do actual iteration on the wrapped list itself
#foreach ($item in $myList.unwrap())
...
#end
## ALTERNATIVE B - explicitly hand over the Iterator
#foreach ($item in $myList.iterator())
...
#end
## ALTERNATIVE C - extract as array
#foreach ($item in $myList.toArray())
...
#end
For best performance, you should choose alternative A or B over C.
An instance of the Sitevision class implementing this interface can be obtained via InstanceCreatorUtil.getListWrapper()
.
See InstanceCreatorUtil
for how to obtain an instance of the InstanceCreatorUtil
interface.
Modifier and Type | Method and Description |
---|---|
void |
add(Object anObject)
Appends the specified element (if non-null) to the end of the wrapped list.
|
void |
clear()
Removes all of the elements from the wrapped list.
|
boolean |
contains(Object anObject)
Checks if the wrapped list contains a specified object.
|
Object |
get(int anIndex)
Returns the element at the specified position in the wrapped list.
|
boolean |
isEmpty()
Whether or not the wrapped list is empty (contains no elements).
|
Iterator |
iterator()
Returns an iterator for the wrapped list.
|
int |
size()
The size (number of elements) of the wrapped list.
|
void |
sort(Comparator aComparator)
Sorts the wrapped list.
|
Object[] |
toArray()
Returns an array containing all of the elements in the wrapped list.
|
List |
unwrap()
Returns the wrapped List.
|
forEach, spliterator
void add(Object anObject)
Important! Null values in lists are inherently bad. This method will not
delegate any null
to the wrapped list.
If you must add a null
value, you can explicitly do it to the wrapped list, i.e:
#set ($myList = $instanceCreatorUtil.listWrapper)
...
$myList.add($anObject.aMethod()) ## Will only delegate non-nulls to the wrapped list
$myList.unwrap().add($anObject.aMethod()) ## Will add any value directly to the wrapped list
anObject
- the element to be appended to the wrapped list, null
will be ignored.void clear()
boolean contains(Object anObject)
anObject
- an element to check for in the wrapped list.true
if the wrapped list contains the specified elementObject get(int anIndex)
anIndex
- index of the element in the wrapped list to returnIndexOutOfBoundsException
- if the index is out of range (index < 0 || index >= size()
)boolean isEmpty()
true
if the wrapped list contains no elementsIterator iterator()
int size()
Object[] toArray()
void sort(Comparator aComparator)
aComparator
- the comparator to use when sortingSitevision - Portal and Content Management Made Easy
Sitevision is an advanced Java enterprise portal product and a portlet container (JSR 286) that implements Java Content Repository (JSR 283).
Copyright© 2008-2022 Sitevision AB, all rights reserved.