001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.servlet.jsp.tagext;
019:
020: import javax.servlet.jsp.*;
021:
022: /**
023: * The IterationTag interface extends Tag by defining one additional
024: * method that controls the reevaluation of its body.
025: *
026: * <p> A tag handler that implements IterationTag is treated as one that
027: * implements Tag regarding the doStartTag() and doEndTag() methods.
028: * IterationTag provides a new method: <code>doAfterBody()</code>.
029: *
030: * <p> The doAfterBody() method is invoked after every body evaluation
031: * to control whether the body will be reevaluated or not. If doAfterBody()
032: * returns IterationTag.EVAL_BODY_AGAIN, then the body will be reevaluated.
033: * If doAfterBody() returns Tag.SKIP_BODY, then the body will be skipped
034: * and doEndTag() will be evaluated instead.
035: *
036: * <p><B>Properties</B>
037: * There are no new properties in addition to those in Tag.
038: *
039: * <p><B>Methods</B>
040: * There is one new methods: doAfterBody().
041: *
042: * <p><B>Lifecycle</B>
043: *
044: * <p> Lifecycle details are described by the transition diagram
045: * below. Exceptions that are thrown during the computation of
046: * doStartTag(), BODY and doAfterBody() interrupt the execution
047: * sequence and are propagated up the stack, unless the tag handler
048: * implements the TryCatchFinally interface; see that interface for
049: * details.
050: *
051: * <p>
052: * <IMG src="doc-files/IterationTagProtocol.gif"
053: * alt="Lifecycle Details Transition Diagram for IterationTag"/>
054: *
055: * <p><B>Empty and Non-Empty Action</B>
056: * <p> If the TagLibraryDescriptor file indicates that the action must
057: * always have an empty element body, by a <body-content> entry of
058: * "empty", then the doStartTag() method must return SKIP_BODY.
059: *
060: * <p>Note that which methods are invoked after the doStartTag() depends on
061: * both the return value and on if the custom action element is empty
062: * or not in the JSP page, not on how it's declared in the TLD.
063: *
064: * <p>
065: * If SKIP_BODY is returned the body is not evaluated, and then doEndTag()
066: * is invoked.
067: *
068: * <p>
069: * If EVAL_BODY_INCLUDE is returned, and the custom action element is not
070: * empty, the body is evaluated and "passed through" to the current out,
071: * then doAfterBody() is invoked and, after zero or more iterations,
072: * doEndTag() is invoked.
073: */
074:
075: public interface IterationTag extends Tag {
076:
077: /**
078: * Request the reevaluation of some body.
079: * Returned from doAfterBody.
080: *
081: * For compatibility with JSP 1.1, the value is carefully selected
082: * to be the same as the, now deprecated, BodyTag.EVAL_BODY_TAG,
083: *
084: */
085:
086: public final static int EVAL_BODY_AGAIN = 2;
087:
088: /**
089: * Process body (re)evaluation. This method is invoked by the
090: * JSP Page implementation object after every evaluation of
091: * the body into the BodyEvaluation object. The method is
092: * not invoked if there is no body evaluation.
093: *
094: * <p>
095: * If doAfterBody returns EVAL_BODY_AGAIN, a new evaluation of the
096: * body will happen (followed by another invocation of doAfterBody).
097: * If doAfterBody returns SKIP_BODY, no more body evaluations will occur,
098: * and the doEndTag method will be invoked.
099: *
100: * <p>
101: * If this tag handler implements BodyTag and doAfterBody returns
102: * SKIP_BODY, the value of out will be restored using the popBody
103: * method in pageContext prior to invoking doEndTag.
104: *
105: * <p>
106: * The method re-invocations may be lead to different actions because
107: * there might have been some changes to shared state, or because
108: * of external computation.
109: *
110: * <p>
111: * The JSP container will resynchronize the values of any AT_BEGIN and
112: * NESTED variables (defined by the associated TagExtraInfo or TLD) after
113: * the invocation of doAfterBody().
114: *
115: * @return whether additional evaluations of the body are desired
116: * @throws JspException if an error occurred while processing this tag
117: */
118:
119: int doAfterBody() throws JspException;
120: }
|