## javax.servlet.jsp.jstl.core
Class LoopTagSupport

    java.lang.Object
      javax.servlet.jsp.tagext.TagSupport
          javax.servlet.jsp.jstl.core.LoopTagSupport

All Implemented Interfaces:
  Serializable, LoopTag, IterationTag, JspTag, Tag, TryCatchFinally

Direct Known Subclasses:
  ForEachSupport, ForEachTag, ForTokensSupport

    public abstract class LoopTagSupport

extends TagSupport
implements LoopTag, IterationTag, TryCatchFinally

Base support class to facilitate implementation of iteration tags.

Since most iteration tags will behave identically with respect to actual iterative behavior, JSTL provides this base support class to facilitate implementation. Many iteration tags will extend this and merely implement the `hasNext()` and `next()` methods to provide contents for the handler to iterate over.

In particular, this base class provides support for:

- Iteration control, based on protected `prepare()`, `next()`, and `hasNext()` methods
- Subsetting (`begin`, `end`, `step>`functionality, including validation of subset parameters for sensibility)
- item retrieval (`getCurrent()`)
- status retrieval (`LoopTagStatus`)
- exposing attributes (set by `var` and `varStatus` attributes)

In providing support for these tasks, `LoopTagSupport` contains certain control variables that act to modify the iteration. Accessors are provided for these control variables when the variables represent information needed or wanted at translation time (e.g., `var`, `varStatus`). For other variables, accessors cannot be provided here since subclasses may differ on their implementations of how those accessors are received. For instance, one subclass might accept a `String` and convert it into an object of a specific type by using an expression evaluator; others might accept objects directly. Still others might not want to expose such information to outside control.

Author:
  Shawn Bayern
See Also:
  Serialized Form

Field Summary
`protected int` `begin` Starting index ('begin' attribute)
`protected boolean` `beginSpecified` Boolean flag indicating whether 'begin' was specified.
`protected ValueExpression` `deferredExpression` The deferred expression if any
`protected int` `end` Ending index of the iteration ('end' attribute).
`protected boolean` `endSpecified` Boolean flag indicating whether 'end' was specified.
`protected String` `itemId` Attribute-exposing control
`protected String` `statusId` Attribute-exposing control
`protected int` `step` Iteration step ('step' attribute)
`protected boolean` `stepSpecified` Boolean flag indicating whether 'step' was specified.

Fields inherited from class javax.servlet.jsp.tagext.TagSupport
`id, pageContext`

Fields inherited from interface javax.servlet.jsp.tagext.Tag
`EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE`

Fields inherited from interface javax.servlet.jsp.tagext.IterationTag
`EVAL_BODY_AGAIN`

Fields inherited from interface javax.servlet.jsp.tagext.Tag
`EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE`

Constructor Summary
`LoopTagSupport()` Constructs a new LoopTagSupport.

Method Summary
`int` `doAfterBody()` Continues the iteration when appropriate -- that is, if we (a) have more items and (b) don't run over our 'end' (given our 'step').
`void` `doCatch(Throwable t)` Rethrows the given Throwable.
`void` `doFinally()` Removes any attributes that this LoopTagSupport set.
`int` `doStartTag()` Begins iterating by processing the first item.
`Object` `getCurrent()` Retrieves the current item in the iteration.
`protected String` `getDelims()`
`LoopTagStatus` `getLoopStatus()` Retrieves a 'status' object to provide information about the current round of the iteration.
`protected abstract boolean` `hasNext()` Returns information concerning the availability of more items over which to iterate.
`protected abstract Object` `next()` Returns the next object over which the tag should iterate.
`protected abstract void` `prepare()` Prepares for a single tag invocation.
`void` `release()` Releases any resources this LoopTagSupport may have (or inherit).
`void` `setVar(String id)` Sets the 'var' attribute.
`void` `setVarStatus(String statusId)` Sets the 'varStatus' attribute.
`protected void` `validateBegin()` Ensures the "begin" property is sensible, throwing an exception expected to propagate up if it isn't
`protected void` `validateEnd()` Ensures the "end" property is sensible, throwing an exception expected to propagate up if it isn't
`protected void` `validateStep()` Ensures the "step" property is sensible, throwing an exception expected to propagate up if it isn't

Methods inherited from class javax.servlet.jsp.tagext.TagSupport
`doEndTag, findAncestorWithClass, getId, getParent, getValue, getValues, removeValue, setId, setPageContext, setParent, setValue`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Methods inherited from interface javax.servlet.jsp.tagext.Tag
`doEndTag, getParent, setPageContext, setParent`

Methods inherited from interface javax.servlet.jsp.tagext.Tag
`doEndTag, getParent, setPageContext, setParent`

Field Detail

### begin

    protected int begin

  Starting index ('begin' attribute)

### end

    protected int end

  Ending index of the iteration ('end' attribute). A value of -1 internally indicates 'no end specified', although accessors for the core JSTL tags do not allow this value to be supplied directly by the user.

### step

    protected int step

  Iteration step ('step' attribute)

### beginSpecified

    protected boolean beginSpecified

  Boolean flag indicating whether 'begin' was specified.

### endSpecified

    protected boolean endSpecified

  Boolean flag indicating whether 'end' was specified.

### stepSpecified

    protected boolean stepSpecified

  Boolean flag indicating whether 'step' was specified.

### itemId

    protected String itemId

  Attribute-exposing control

### statusId

    protected String statusId

  Attribute-exposing control

### deferredExpression

    protected ValueExpression deferredExpression

  The deferred expression if any

Constructor Detail

### LoopTagSupport

    public LoopTagSupport()

  Constructs a new LoopTagSupport. As with TagSupport, subclasses should not implement constructors with arguments, and no-arguments constructors implemented by subclasses must call the superclass constructor.

Method Detail

### next

    protected abstract Object next()
                            throws JspTagException

  Returns the next object over which the tag should iterate. This method must be provided by concrete subclasses of LoopTagSupport to inform the base logic about what objects it should iterate over.

  It is expected that this method will generally be backed by an Iterator, but this will not always be the case. In particular, if retrieving the next object raises the possibility of an exception being thrown, this method allows that exception to propagate back to the JSP container as a JspTagException; a standalone Iterator would not be able to do this. (This explains why LoopTagSupport does not simply call for an Iterator from its subtags.)

  Returns:
    the java.lang.Object to use in the next round of iteration
  Throws:
    `NoSuchElementException` - if next() is called but no new elements are available
    `JspTagException` - for other, unexpected exceptions

### hasNext

    protected abstract boolean hasNext()
                                throws JspTagException

  Returns information concerning the availability of more items over which to iterate. This method must be provided by concrete subclasses of LoopTagSupport to assist the iterative logic provided by the supporting base class.

  See next for more information about the purpose and expectations behind this tag.

  Returns:
    `true` if there is at least one more item to iterate over, `false` otherwise
  Throws:
    `JspTagException`
  See Also:
    `next()`

### prepare

    protected abstract void prepare()
                             throws JspTagException

  Prepares for a single tag invocation. Specifically, allows subclasses to prepare for calls to hasNext() and next(). Subclasses can assume that prepare() will be called once for each invocation of doStartTag() in the superclass.

  Throws:
    `JspTagException`

### release

    public void release()

  Releases any resources this LoopTagSupport may have (or inherit).

  Specified by:
    `release` in interface `Tag`
  Overrides:
    `release` in class `TagSupport`
  See Also:
    `Tag.release()`

### doStartTag

    public int doStartTag()
                   throws JspException

  Begins iterating by processing the first item.

  Specified by:
    `doStartTag` in interface `Tag`
  Overrides:
    `doStartTag` in class `TagSupport`
  Returns:
    SKIP_BODY
  Throws:
    `JspException` - if an error occurs while processing this tag
  See Also:
    `Tag.doStartTag()`

### doAfterBody

    public int doAfterBody()
                    throws JspException

  Continues the iteration when appropriate -- that is, if we (a) have more items and (b) don't run over our 'end' (given our 'step').

  Specified by:
    `doAfterBody` in interface `IterationTag`
  Overrides:
    `doAfterBody` in class `TagSupport`
  Returns:
    SKIP_BODY
  Throws:
    `JspException` - if an error occurs while processing this tag
  See Also:
    `IterationTag.doAfterBody()`

### doFinally

    public void doFinally()

  Removes any attributes that this LoopTagSupport set.

  These attributes are intended to support scripting variables with NESTED scope, so we don't want to pollute attribute space by leaving them lying around.

  Specified by:
    `doFinally` in interface `TryCatchFinally`

### doCatch

    public void doCatch(Throwable t)
                 throws Throwable

  Rethrows the given Throwable.

  Specified by:
    `doCatch` in interface `TryCatchFinally`
  Parameters:
    `t` - The throwable exception navigating through this tag.
  Throws:
    `Throwable` - if the exception is to be rethrown further up the nest chain.

### getCurrent

    public Object getCurrent()

  Description copied from interface: `LoopTag`
  Retrieves the current item in the iteration. Behaves idempotently; calling getCurrent() repeatedly should return the same Object until the iteration is advanced. (Specifically, calling getCurrent() does not advance the iteration.)

  Specified by:
    `getCurrent` in interface `LoopTag`
  Returns:
    the current item as an object

### getLoopStatus

    public LoopTagStatus getLoopStatus()

  Description copied from interface: `LoopTag`
  Retrieves a 'status' object to provide information about the current round of the iteration.

  Specified by:
    `getLoopStatus` in interface `LoopTag`
  Returns:
    The LoopTagStatus for the current `LoopTag`.

### getDelims

    protected String getDelims()

### setVar

    public void setVar(String id)

  Sets the 'var' attribute.

  Parameters:
    `id` - Name of the exported scoped variable storing the current item of the iteration.

### setVarStatus

    public void setVarStatus(String statusId)

  Sets the 'varStatus' attribute.

  Parameters:
    `statusId` - Name of the exported scoped variable storing the status of the iteration.

### validateBegin

    protected void validateBegin()
                          throws JspTagException

  Ensures the "begin" property is sensible, throwing an exception expected to propagate up if it isn't

  Throws:
    `JspTagException`

### validateEnd

    protected void validateEnd()
                        throws JspTagException

  Ensures the "end" property is sensible, throwing an exception expected to propagate up if it isn't

  Throws:
    `JspTagException`

### validateStep

    protected void validateStep()
                         throws JspTagException

  Ensures the "step" property is sensible, throwing an exception expected to propagate up if it isn't

  Throws:
    `JspTagException`

Copyright © 2007 Mort Bay Consulting. All Rights Reserved.