javax.servlet.jsp.jstl.core

Class LoopTagSupport

Implemented Interfaces:
IterationTag, LoopTag, 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:

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

Field Summary

protected int
begin
Starting index ('begin' attribute)
protected boolean
beginSpecified
Boolean flag indicating whether 'begin' was specified.
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.

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()
LoopTagStatus
getLoopStatus()
protected boolean
hasNext()
Returns information concerning the availability of more items over which to iterate.
protected Object
next()
Returns the next object over which the tag should iterate.
protected 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

Field Details

begin

protected int begin
Starting index ('begin' attribute)


beginSpecified

protected boolean beginSpecified
Boolean flag indicating whether 'begin' was specified.


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.


endSpecified

protected boolean endSpecified
Boolean flag indicating whether 'end' was specified.


itemId

protected String itemId
Attribute-exposing control


statusId

protected String statusId
Attribute-exposing control


step

protected int step
Iteration step ('step' attribute)


stepSpecified

protected boolean stepSpecified
Boolean flag indicating whether 'step' was specified.

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

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').


doCatch

public void doCatch(Throwable t)
            throws Throwable
Rethrows the given Throwable.


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.


doStartTag

public int doStartTag()
            throws JspException
Begins iterating by processing the first item.


getCurrent

public Object getCurrent()
Specified by:
getCurrent in interface LoopTag


getLoopStatus

public LoopTagStatus getLoopStatus()
Specified by:
getLoopStatus in interface LoopTag


hasNext

protected boolean hasNext()
            throws JspTagException

Returns:
true if there is at least one more item to iterate over, false otherwise

See Also:
next()


next

protected 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


prepare

protected 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.


release

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


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


validateEnd

protected void validateEnd()
            throws JspTagException
Ensures the "end" property is sensible, throwing an exception expected to propagate up if it isn't


validateStep

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


Copyright 2003 Sun Microsystems, Inc. All Rights Reserved.