org.apache.cocoon.taglib.core
Class LoopTagSupport

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.cocoon.taglib.TagSupport
          org.apache.cocoon.taglib.VarTagSupport
              org.apache.cocoon.taglib.core.LoopTagSupport

All Implemented Interfaces:

Poolable, Recyclable, Component, LogEnabled, Serviceable, LoopTag, IterationTag, Tag

Direct Known Subclasses:

ForEachSupport

public abstract class LoopTagSupport
extends VarTagSupport
implements LoopTag, IterationTag

Cocoon taglib allows developers to write custom iteration tags by implementing the LoopTag interface. (This is not to be confused with org.apache.cocoon.taglib.IterationTag) 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, Cocoon taglib 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 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, 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.

Migration from JSTL1.0

Version:

CVS $Id: LoopTagSupport.html 1304258 2012-03-23 10:09:27Z ilgrosso $

Author:

Volker Schmitt

See Also:

LoopTagSupport

Field Summary

protected int	begin Starting index ('begin' attribute)
protected boolean	beginSpecified Boolean flag indicating whether 'begin' was specified.
protected int	count
protected int	end Ending index ('end' attribute)
protected boolean	endSpecified Boolean flag indicating whether 'end' was specified.
protected int	index
protected boolean	last
protected 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 org.apache.cocoon.taglib.VarTagSupport

manager, var

Fields inherited from class org.apache.cocoon.taglib.TagSupport

objectModel, parameters, parent, resolver

Fields inherited from interface org.apache.cocoon.taglib.IterationTag

EVAL_BODY_AGAIN

Fields inherited from interface org.apache.cocoon.taglib.Tag

EVAL_BODY, EVAL_PAGE, ROLE, SKIP_BODY

Constructor Summary

LoopTagSupport()
Constructs a new LoopTagSupport.

Method Summary

int	doAfterBody() Process body (re)evaluation.
void	doCatch(Throwable t)
void	doFinally()
int	doStartTag(String namespaceURI, String localName, String qName, Attributes atts) Process the start tag for this instance.
Object	getCurrent() Retrieves the current item in the iteration.
LoopTagStatus	getIteratorStatus() 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	recycle()
void	setVarStatus(String statusId)
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 org.apache.cocoon.taglib.VarTagSupport

getRequest, getVar, getVariable, removeVariable, service, setVar, setVariable

Methods inherited from class org.apache.cocoon.taglib.TagSupport

doEndTag, findAncestorWithClass, findAttribute, getParent, setParent, setup

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.cocoon.taglib.Tag

doEndTag, getParent, setParent, setup

Field Detail

begin

protected int begin

Starting index ('begin' attribute)

end

protected int end

Ending index ('end' attribute). -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.

statusId

protected String statusId

Attribute-exposing control

index

protected int index

count

protected int count

last

protected boolean last

Constructor Detail

LoopTagSupport

public LoopTagSupport()

Constructs a new LoopTagSupport. As with TagSupport, subclasses should not provide other constructors and are expected to call the superclass constructor

Method Detail

next

protected abstract Object next()
                        throws SAXException

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 container as a SAXException; 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:

SAXException - for other, unexpected exceptions

hasNext

protected abstract boolean hasNext()
                            throws SAXException

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:

SAXException

See Also:

next()

prepare

protected abstract void prepare()
                         throws SAXException

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:

SAXException

recycle

public void recycle()

Specified by:

recycle in interface Recyclable

Overrides:

recycle in class VarTagSupport

doStartTag

public int doStartTag(String namespaceURI,
                      String localName,
                      String qName,
                      Attributes atts)
               throws SAXException

Description copied from class: TagSupport

Process the start tag for this instance.

The doStartTag method assumes that pageContext and parent have been set. It also assumes that any properties exposed as attributes have been set too. When this method is invoked, the body has not yet been evaluated.

Specified by:

doStartTag in interface Tag

Overrides:

doStartTag in class TagSupport

Returns:

EVAL_BODY or SKIP_BODY.

Throws:

SAXException

doAfterBody

public int doAfterBody()
                throws SAXException

Description copied from interface: IterationTag

Process body (re)evaluation. This method is invoked by the Taglib implementation object after every evaluation of the body into the BodyEvaluation object. The method is not invoked if there is no body evaluation.

If doAfterBody returns EVAL_BODY_AGAIN, a new evaluation of the body will happen (followed by another invocation of doAfterBody). If doAfterBody returns SKIP_BODY no more body evaluations will occur and then doEndTag will be invoked.

The method re-invocations may be lead to different actions because there might have been some changes to shared state, or because of external computation.

Specified by:

doAfterBody in interface IterationTag

Returns:

whether additional evaluations of the body are desired

Throws:

SAXException

doFinally

public void doFinally()

doCatch

public void doCatch(Throwable t)
             throws Throwable

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

getIteratorStatus

public LoopTagStatus getIteratorStatus()

Description copied from interface: LoopTag

Retrieves a 'status' object to provide information about the current round of the iteration.

Specified by:

getIteratorStatus in interface LoopTag

Returns:

the LoopTagStatus for the current LoopTag

setVarStatus

public void setVarStatus(String statusId)

validateBegin

protected void validateBegin()
                      throws SAXException

Ensures the "begin" property is sensible, throwing an exception expected to propagate up if it isn't

Throws:

SAXException

validateEnd

protected void validateEnd()
                    throws SAXException

Ensures the "end" property is sensible, throwing an exception expected to propagate up if it isn't

Throws:

SAXException

validateStep

protected void validateStep()
                     throws SAXException

Ensures the "step" property is sensible, throwing an exception expected to propagate up if it isn't

Throws:

SAXException