|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.servlet.jsp.tagext.TagSupport | +--javax.servlet.jsp.jstl.core.LoopTagSupport
JSTL 1.0 allows developers to write custom iteration tags by implementing the LoopTag interface. (This is not to be confused with javax.servlet.jsp.tagext.IterationTag as defined in JSP 1.2.) LoopTag establishes a mechanism for iteration tags to be recognized and for type-safe communication with custom subtags.
Since most iteration tags will behave identically with respect to actual iterative behavior, however, JSTL 1.0 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, status). 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.
Field Summary | |
protected int |
begin
Starting index ('begin' attribute) |
protected boolean |
beginSpecified
Boolean flag indicating whether 'begin' was specified. |
protected int |
end
Ending index ('end' attribute). |
protected boolean |
endSpecified
Boolean flag indicating whether 'end' was specified. |
protected java.lang.String |
itemId
Attribute-exposing control |
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.Tag |
EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE |
Fields inherited from interface javax.servlet.jsp.tagext.IterationTag |
EVAL_BODY_AGAIN |
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(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. |
java.lang.Object |
getCurrent()
Retrieves the current item in the iteration. |
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 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. |
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 |
protected int begin
protected int end
protected int step
protected boolean beginSpecified
protected boolean endSpecified
protected boolean stepSpecified
protected java.lang.String itemId
protected java.lang.String statusId
Constructor Detail |
public LoopTagSupport()
Method Detail |
protected abstract java.lang.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.)
NoSuchElementException
- if next() is called but no new elements are availableJspTagException
- for other, unexpected exceptionsprotected 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.
javax.servlet.JspTagException
- next()
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.
javax.servlet.JspTagException
- public void release()
release
in interface Tag
release
in class TagSupport
javax.servlet.jsp.tagext.TagSupport
Tag.release()
public int doStartTag() throws JspException
doStartTag
in interface Tag
doStartTag
in class TagSupport
javax.servlet.jsp.tagext.Tag
JspException.
- BodyTag
public int doAfterBody() throws JspException
doAfterBody
in interface IterationTag
doAfterBody
in class TagSupport
javax.servlet.jsp.tagext.IterationTag
JspException
- public void doFinally()
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.
doFinally
in interface TryCatchFinally
public void doCatch(java.lang.Throwable t) throws java.lang.Throwable
doCatch
in interface TryCatchFinally
javax.servlet.jsp.tagext.TryCatchFinally
t
- The throwable exception navigating through this tag.public java.lang.Object getCurrent()
LoopTag
getCurrent
in interface LoopTag
javax.servlet.jsp.jstl.core.LoopTag
public LoopTagStatus getLoopStatus()
LoopTag
getLoopStatus
in interface LoopTag
javax.servlet.jsp.jstl.core.LoopTag
public void setVar(java.lang.String id)
id
- Name of the exported scoped variable storing the current item
of the iteration.public void setVarStatus(java.lang.String statusId)
statusId
- Name of the exported scoped variable storing the status
of the iteration.protected void validateBegin() throws JspTagException
protected void validateEnd() throws JspTagException
protected void validateStep() throws JspTagException
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |