: Class Camwood

Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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()`

Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD