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 }