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