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

      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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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.IterationTag

      `EVAL_BODY_AGAIN`

    - ### Fields inherited from interface javax.servlet.jsp.tagext.Tag

      `EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LoopTagSupport()` Constructs a new LoopTagSupport.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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`

- - ### 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 © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.