Package javax.servlet.jsp.jstl.core

Class LoopTagSupport

  • All Implemented Interfaces:
    java.io.Serializable, LoopTag, javax.servlet.jsp.tagext.IterationTag, javax.servlet.jsp.tagext.JspTag, javax.servlet.jsp.tagext.Tag, javax.servlet.jsp.tagext.TryCatchFinally
    Direct Known Subclasses:
    ForEachSupport, ForEachTag, ForTokensSupport
    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.

    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected int begin
      Starting index ('begin' attribute)
      protected boolean beginSpecified
      Boolean flag indicating whether 'begin' was specified.
      private int count  
      protected javax.el.ValueExpression deferredExpression  
      protected int end
      Ending index of the iteration ('end' attribute).
      protected boolean endSpecified
      Boolean flag indicating whether 'end' was specified.
      private int index  
      private java.lang.Object item  
      protected java.lang.String itemId
      Attribute-exposing control
      private boolean last  
      private LoopTagStatus status  
      protected java.lang.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 Description
      LoopTagSupport()
      Constructs a new LoopTagSupport.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      private boolean atEnd()
      Returns true if the iteration has past the 'end' index (with respect to subsetting), false otherwise.
      private void calibrateLast()
      Sets 'last' appropriately.
      private void discard​(int n)
      Cycles through and discards up to 'n' items from the iteration.
      private void discardIgnoreSubset​(int n)
      Discards items ignoring subsetting rules.
      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​(java.lang.Throwable t)
      Rethrows the given Throwable.
      void doFinally()
      Removes any attributes that this LoopTagSupport set.
      int doStartTag()
      Begins iterating by processing the first item.
      private void exposeVariables()
      Exposes attributes (formerly scripting variables, but no longer!) if appropriate.
      java.lang.Object getCurrent()
      Retrieves the current item in the iteration.
      protected java.lang.String getDelims()
      Get the delimiter for string tokens.
      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.
      private void init()
      (Re)initializes state (during release() or construction)
      protected abstract java.lang.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​(java.lang.String id)
      Sets the 'var' attribute.
      void setVarStatus​(java.lang.String statusId)
      Sets the 'varStatus' attribute.
      private void unExposeVariables()
      Removes page attributes that we have exposed and, if applicable, restores them to their prior values (and scopes).
      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 java.lang.String itemId
        Attribute-exposing control

      • statusId

        protected java.lang.String statusId
        Attribute-exposing control

      • deferredExpression

        protected javax.el.ValueExpression deferredExpression

      • item

        private java.lang.Object item

      • index

        private int index

      • count

        private int count

      • last

        private boolean last

    • 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 java.lang.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:
        java.util.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:
        next()

      • 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​(java.lang.Throwable t)
             throws java.lang.Throwable
        Rethrows the given Throwable.
        Specified by:
        doCatch in interface javax.servlet.jsp.tagext.TryCatchFinally
        Throws:
        java.lang.Throwable

      • getCurrent

        public java.lang.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​(java.lang.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​(java.lang.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

      • init

        private void init()
        (Re)initializes state (during release() or construction)

      • calibrateLast

        private void calibrateLast()
                    throws javax.servlet.jsp.JspTagException
        Sets 'last' appropriately.
        Throws:
        javax.servlet.jsp.JspTagException

      • exposeVariables

        private void exposeVariables()
                      throws javax.servlet.jsp.JspTagException
        Exposes attributes (formerly scripting variables, but no longer!) if appropriate. Note that we don't really care, here, whether they're scripting variables or not.
        Throws:
        javax.servlet.jsp.JspTagException

      • unExposeVariables

        private void unExposeVariables()
        Removes page attributes that we have exposed and, if applicable, restores them to their prior values (and scopes).

      • discard

        private void discard​(int n)
              throws javax.servlet.jsp.JspTagException
        Cycles through and discards up to 'n' items from the iteration. We only know "up to 'n'", not "exactly n," since we stop cycling if hasNext() returns false or if we hit the 'end' of the iteration. Note: this does not update the iteration index, since this method is intended as a behind-the-scenes operation. The index must be updated separately. (I don't really like this, but it's the simplest way to support isLast() without storing two separate inconsistent indices. We need to (a) make sure hasNext() refers to the next item we actually *want* and (b) make sure the index refers to the item associated with the *current* round, not the next one. C'est la vie.)
        Throws:
        javax.servlet.jsp.JspTagException

      • discardIgnoreSubset

        private void discardIgnoreSubset​(int n)
                          throws javax.servlet.jsp.JspTagException
        Discards items ignoring subsetting rules. Useful for discarding items from the beginning (i.e., to implement 'begin') where we don't want factor in the 'begin' value already.
        Throws:
        javax.servlet.jsp.JspTagException

      • atEnd

        private boolean atEnd()
        Returns true if the iteration has past the 'end' index (with respect to subsetting), false otherwise. ('end' must be set for atEnd() to return true; if 'end' is not set, atEnd() always returns false.)

      • getDelims

        protected java.lang.String getDelims()
        Get the delimiter for string tokens. Used only for constructing the deferred expression for it.