Class LoopTagSupport
- All Implemented Interfaces:
LoopTag
,jakarta.servlet.jsp.tagext.IterationTag
,jakarta.servlet.jsp.tagext.JspTag
,jakarta.servlet.jsp.tagext.Tag
,jakarta.servlet.jsp.tagext.TryCatchFinally
,Serializable
public abstract class LoopTagSupport extends jakarta.servlet.jsp.tagext.TagSupport implements LoopTag, jakarta.servlet.jsp.tagext.IterationTag, jakarta.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, the Jakarta Standard Tag Library 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 Description protected int
begin
Starting index ('begin' attribute)protected boolean
beginSpecified
Boolean flag indicating whether 'begin' was specified.protected jakarta.el.ValueExpression
deferredExpression
The deferred expression if anyprotected int
end
Ending index of the iteration ('end' attribute).protected boolean
endSpecified
Boolean flag indicating whether 'end' was specified.protected String
itemId
Attribute-exposing controlprotected String
statusId
Attribute-exposing controlprotected int
step
Iteration step ('step' attribute)protected boolean
stepSpecified
Boolean flag indicating whether 'step' was specified.Fields inherited from class jakarta.servlet.jsp.tagext.TagSupport
id, pageContext
Fields inherited from interface jakarta.servlet.jsp.tagext.IterationTag
EVAL_BODY_AGAIN
Fields inherited from interface jakarta.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
Modifier and Type Method 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'tprotected void
validateEnd()
Ensures the "end" property is sensible, throwing an exception expected to propagate up if it isn'tprotected void
validateStep()
Ensures the "step" property is sensible, throwing an exception expected to propagate up if it isn'tMethods inherited from class jakarta.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 jakarta.servlet.jsp.tagext.Tag
doEndTag, getParent, setPageContext, setParent
-
Field Details
-
begin
protected int beginStarting index ('begin' attribute) -
end
protected int endEnding index of the iteration ('end' attribute). A value of -1 internally indicates 'no end specified', although accessors for the core Jakarta Standard Tag Library tags do not allow this value to be supplied directly by the user. -
step
protected int stepIteration step ('step' attribute) -
beginSpecified
protected boolean beginSpecifiedBoolean flag indicating whether 'begin' was specified. -
endSpecified
protected boolean endSpecifiedBoolean flag indicating whether 'end' was specified. -
stepSpecified
protected boolean stepSpecifiedBoolean flag indicating whether 'step' was specified. -
itemId
Attribute-exposing control -
statusId
Attribute-exposing control -
deferredExpression
protected jakarta.el.ValueExpression deferredExpressionThe deferred expression if any
-
-
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
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 availablejakarta.servlet.jsp.JspTagException
- for other, unexpected exceptions
-
hasNext
protected abstract boolean hasNext() throws jakarta.servlet.jsp.JspTagExceptionReturns 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:
jakarta.servlet.jsp.JspTagException
- See Also:
next()
-
prepare
protected abstract void prepare() throws jakarta.servlet.jsp.JspTagExceptionPrepares 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:
jakarta.servlet.jsp.JspTagException
-
release
public void release()Releases any resources this LoopTagSupport may have (or inherit).- Specified by:
release
in interfacejakarta.servlet.jsp.tagext.Tag
- Overrides:
release
in classjakarta.servlet.jsp.tagext.TagSupport
-
doStartTag
public int doStartTag() throws jakarta.servlet.jsp.JspExceptionBegins iterating by processing the first item.- Specified by:
doStartTag
in interfacejakarta.servlet.jsp.tagext.Tag
- Overrides:
doStartTag
in classjakarta.servlet.jsp.tagext.TagSupport
- Throws:
jakarta.servlet.jsp.JspException
-
doAfterBody
public int doAfterBody() throws jakarta.servlet.jsp.JspExceptionContinues 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 interfacejakarta.servlet.jsp.tagext.IterationTag
- Overrides:
doAfterBody
in classjakarta.servlet.jsp.tagext.TagSupport
- Throws:
jakarta.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 interfacejakarta.servlet.jsp.tagext.TryCatchFinally
-
doCatch
Rethrows the given Throwable.- Specified by:
doCatch
in interfacejakarta.servlet.jsp.tagext.TryCatchFinally
- Throws:
Throwable
-
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 interfaceLoopTag
- Returns:
- the current item as an object
-
getLoopStatus
Description copied from interface:LoopTag
Retrieves a 'status' object to provide information about the current round of the iteration.- Specified by:
getLoopStatus
in interfaceLoopTag
- Returns:
- The LoopTagStatus for the current LoopTag.
-
getDelims
-
setVar
Sets the 'var' attribute.- Parameters:
id
- Name of the exported scoped variable storing the current item of the iteration.
-
setVarStatus
Sets the 'varStatus' attribute.- Parameters:
statusId
- Name of the exported scoped variable storing the status of the iteration.
-
validateBegin
protected void validateBegin() throws jakarta.servlet.jsp.JspTagExceptionEnsures the "begin" property is sensible, throwing an exception expected to propagate up if it isn't- Throws:
jakarta.servlet.jsp.JspTagException
-
validateEnd
protected void validateEnd() throws jakarta.servlet.jsp.JspTagExceptionEnsures the "end" property is sensible, throwing an exception expected to propagate up if it isn't- Throws:
jakarta.servlet.jsp.JspTagException
-
validateStep
protected void validateStep() throws jakarta.servlet.jsp.JspTagExceptionEnsures the "step" property is sensible, throwing an exception expected to propagate up if it isn't- Throws:
jakarta.servlet.jsp.JspTagException
-