Class LoopTagSupport

java.lang.Object
javax.servlet.jsp.tagext.TagSupport
javax.servlet.jsp.jstl.core.LoopTagSupport
All Implemented Interfaces:
Serializable, LoopTag, javax.servlet.jsp.tagext.IterationTag, javax.servlet.jsp.tagext.JspTag, javax.servlet.jsp.tagext.Tag, javax.servlet.jsp.tagext.TryCatchFinally

public abstract class LoopTagSupport extends javax.servlet.jsp.tagext.TagSupport implements LoopTag, javax.servlet.jsp.tagext.IterationTag, javax.servlet.jsp.tagext.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:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected int
    Starting index ('begin' attribute)
    protected boolean
    Boolean flag indicating whether 'begin' was specified.
    protected int
    Ending index of the iteration ('end' attribute).
    protected boolean
    Boolean flag indicating whether 'end' was specified.
    protected String
    Attribute-exposing control
    protected String
    Attribute-exposing control
    protected int
    Iteration step ('step' attribute)
    protected boolean
    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
    Description
    Constructs a new LoopTagSupport.
  • Method Summary

    Modifier and Type
    Method
    Description
    int
    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
    Rethrows the given Throwable.
    void
    Removes any attributes that this LoopTagSupport set.
    int
    Begins iterating by processing the first item.
    Retrieves the current item in the iteration.
    Retrieves a 'status' object to provide information about the current round of the iteration.
    protected abstract boolean
    Returns information concerning the availability of more items over which to iterate.
    protected abstract Object
    Returns the next object over which the tag should iterate.
    protected abstract void
    Prepares for a single tag invocation.
    void
    Releases any resources this LoopTagSupport may have (or inherit).
    void
    Sets the 'var' attribute.
    void
    setVarStatus(String statusId)
    Sets the 'varStatus' attribute.
    protected void
    Ensures the "begin" property is sensible, throwing an exception expected to propagate up if it isn't
    protected void
    Ensures the "end" property is sensible, throwing an exception expected to propagate up if it isn't
    protected void
    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 Details

    • 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
  • Constructor Details

    • 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 Details

    • next

      protected abstract Object next() throws javax.servlet.jsp.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
      javax.servlet.jsp.JspTagException - for other, unexpected exceptions
    • hasNext

      protected abstract boolean hasNext() throws javax.servlet.jsp.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:
      javax.servlet.jsp.JspTagException
      See Also:
    • prepare

      protected abstract void prepare() throws javax.servlet.jsp.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:
      javax.servlet.jsp.JspTagException
    • release

      public void release()
      Releases any resources this LoopTagSupport may have (or inherit).
      Specified by:
      release in interface javax.servlet.jsp.tagext.Tag
      Overrides:
      release in class javax.servlet.jsp.tagext.TagSupport
    • doStartTag

      public int doStartTag() throws javax.servlet.jsp.JspException
      Begins iterating by processing the first item.
      Specified by:
      doStartTag in interface javax.servlet.jsp.tagext.Tag
      Overrides:
      doStartTag in class javax.servlet.jsp.tagext.TagSupport
      Throws:
      javax.servlet.jsp.JspException
    • doAfterBody

      public int doAfterBody() throws javax.servlet.jsp.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 javax.servlet.jsp.tagext.IterationTag
      Overrides:
      doAfterBody in class javax.servlet.jsp.tagext.TagSupport
      Throws:
      javax.servlet.jsp.JspException
    • 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 javax.servlet.jsp.tagext.TryCatchFinally
    • doCatch

      public void doCatch(Throwable t) throws Throwable
      Rethrows the given Throwable.
      Specified by:
      doCatch in interface javax.servlet.jsp.tagext.TryCatchFinally
      Throws:
      Throwable
    • 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.
    • 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 javax.servlet.jsp.JspTagException
      Ensures the "begin" property is sensible, throwing an exception expected to propagate up if it isn't
      Throws:
      javax.servlet.jsp.JspTagException
    • validateEnd

      protected void validateEnd() throws javax.servlet.jsp.JspTagException
      Ensures the "end" property is sensible, throwing an exception expected to propagate up if it isn't
      Throws:
      javax.servlet.jsp.JspTagException
    • validateStep

      protected void validateStep() throws javax.servlet.jsp.JspTagException
      Ensures the "step" property is sensible, throwing an exception expected to propagate up if it isn't
      Throws:
      javax.servlet.jsp.JspTagException