org.apache.velocity.tools
Class Camwood

java.lang.Object
  |
  +--org.apache.velocity.tools.Camwood

All Implemented Interfaces:

java.util.Iterator

Direct Known Subclasses:

FisherMill

public class Camwood

extends java.lang.Object

implements java.util.Iterator

A convenience tool for use in #foreach loops. It wraps a list to let the designer specify a condition to terminate the loop, and reuse the same list in different loops.

Important note: The method stop() doesn't stop the #foreach immediately, instead it makes the loop terminate after the end of the current iteration. See also the FisherMill class for an alternate way to terminate the current iteration.

Example of use:

  
  Java
  ----
  context.put("cam", new Camwood());

  
  VTL
  ---
  
  #set ($list = [1, 2, 3, 5, 8, 13])
  #set ($numbers = $cam.wrap($list))
  
  #foreach ($item in $numbers)
   $item##
  #if ($item < 8)$numbers.stop()#end
  #end
  
  $numbers.next()
  
  
  Output
  ------
  
   1 2 3 5
  8
 

Warning: It is not recommended to call hasNext() directly as this method is used to control the #foreach. Use hasMore() instead.

Changes:

• 13 Sep 02 Original version
• 13 Sep 02 Added isTool(), cont()

Constructor Summary

Camwood()
Create a Camwood instance to use as tool.

Camwood(java.lang.Object list)
Create a Camwood instance to use in #foreach.

Method Summary

void	cont() Puts a condition to continue the loop.
boolean	hasMore() Returns true if there are more elements in the wrapped list.
boolean	hasNext() Returns true if there are more elements in the list and stop() was not called.
boolean	isTool() Returns true if this object is used as a tool.
java.lang.Object	next() Gets the next element in the list.
void	remove() Removes the current element from the list.
void	reset() Resets the wrapper so that it starts over at the beginning of the list.
void	stop() Puts a condition to break out of the loop.
java.lang.String	toString() Returns this object as a String.
Camwood	wrap(java.lang.Object list) Wraps a list with the tool.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Camwood

public Camwood()

Create a Camwood instance to use as tool. When it is created this way, the tool returns a new instance each time wrap() is called. This is useful when you want to allow the designers to create instances.

Camwood

public Camwood(java.lang.Object list)

Create a Camwood instance to use in #foreach.

Parameters:

wrapped - The list to wrap.

Method Detail

isTool

public boolean isTool()

Returns true if this object is used as a tool.

Returns:

true if this object is used as a tool, i.e. it doesn't wrap a list.

See Also:

wrap(java.lang.Object)

wrap

public Camwood wrap(java.lang.Object list)

Wraps a list with the tool. The list can be an array, a Collection, a Map, an Iterator or an Enumeration.
If the list is a Map, the wrapper iterates over the values.
If the list is an Iterator or an Enumeration, the wrapper can be used only once.

Parameters:

list - The list to wrap.

Returns:

A new wrapper if this object is used as a tool, or itself if it is a wrapper.

reset

public void reset()

Resets the wrapper so that it starts over at the beginning of the list.

Note to programmers: This method has no effect if the wrapped object is an enumeration or an iterator.

next

public java.lang.Object next()

Gets the next element in the list. This method is called by #foreach to define $item in:

 #foreach( $item in $list )

Specified by:

next in interface java.util.Iterator

Returns:

The next element in the list.

Throws:

NoSuchElementException - if there are no more elements in the list.

See Also:

hasMore()

hasNext

public boolean hasNext()

Returns true if there are more elements in the list and stop() was not called.

Specified by:

hasNext in interface java.util.Iterator

Returns:

true if there are more elements, and stop() was not called since last call.

See Also:

hasMore()

remove

public void remove()
            throws java.lang.UnsupportedOperationException

Removes the current element from the list.

Specified by:

remove in interface java.util.Iterator

Throws:

java.lang.UnsupportedOperationException - if the wrapped list iterator doesn't support this operation.

toString

public java.lang.String toString()

Returns this object as a String.
If this object is used as a tool, it just gives the class name.
Otherwise it appends the wrapped list to the class name.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this object.

hasMore

public boolean hasMore()

Returns true if there are more elements in the wrapped list.
If this object doesn't wrap a list, the method always returns false.

Returns:

true if there are more elements in the list.

See Also:

next()

stop

public void stop()

Puts a condition to break out of the loop. The #foreach loop will terminate after this iteration.

See Also:

cont(), hasMore()

cont

public void cont()

Puts a condition to continue the loop. The #foreach loop will continue after this iteration (if there are more elements).

See Also:

stop()