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