1 /** 2 * 3 * Copyright 2003-2004 The Apache Software Foundation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 // 19 // This source code implements specifications defined by the Java 20 // Community Process. In order to remain compliant with the specification 21 // DO NOT add / change / or delete method signatures! 22 // 23 24 package javax.servlet.jsp.tagext; 25 26 import javax.servlet.jsp.JspContext; 27 28 /** 29 * Interface for defining Simple Tag Handlers. 30 * 31 * <p>Simple Tag Handlers differ from Classic Tag Handlers in that instead 32 * of supporting <code>doStartTag()</code> and <code>doEndTag()</code>, 33 * the <code>SimpleTag</code> interface provides a simple 34 * <code>doTag()</code> method, which is called once and only once for any 35 * given tag invocation. All tag logic, iteration, body evaluations, etc. 36 * are to be performed in this single method. Thus, simple tag handlers 37 * have the equivalent power of <code>BodyTag</code>, but with a much 38 * simpler lifecycle and interface.</p> 39 * 40 * <p>To support body _content, the <code>setJspBody()</code> 41 * method is provided. The container invokes the <code>setJspBody()</code> 42 * method with a <code>JspFragment</code> object encapsulating the body of 43 * the tag. The tag handler implementation can call 44 * <code>invoke()</code> on that fragment to evaluate the body as 45 * many times as it needs.</p> 46 * 47 * <p>A SimpleTag handler must have a public no-args constructor. Most 48 * SimpleTag handlers should extend SimpleTagSupport.</p> 49 * 50 * <p><b>Lifecycle</b></p> 51 * 52 * <p>The following is a non-normative, brief overview of the 53 * SimpleTag lifecycle. Refer to the JSP Specification for details.</p> 54 * 55 * <ol> 56 * <li>A new tag handler instance is created each time by the container 57 * by calling the provided zero-args constructor. Unlike classic 58 * tag handlers, simple tag handlers are never cached and reused by 59 * the JSP container.</li> 60 * <li>The <code>setJspContext()</code> and <code>setParent()</code> 61 * methods are called by the container. The <code>setParent()</code> 62 * method is only called if the element is nested within another tag 63 * invocation.</li> 64 * <li>The setters for each attribute defined for this tag are called 65 * by the container.</li> 66 * <li>If a body exists, the <code>setJspBody()</code> method is called 67 * by the container to set the body of this tag, as a 68 * <code>JspFragment</code>. If the action element is empty in 69 * the page, this method is not called at all.</li> 70 * <li>The <code>doTag()</code> method is called by the container. All 71 * tag logic, iteration, body evaluations, etc. occur in this 72 * method.</li> 73 * <li>The <code>doTag()</code> method returns and all variables are 74 * synchronized.</li> 75 * </ol> 76 * 77 * @see SimpleTagSupport 78 * @since 2.0 79 */ 80 public interface SimpleTag extends JspTag { 81 82 /** 83 * Called by the container to invoke this tag. 84 * The implementation of this method is provided by the tag library 85 * developer, and handles all tag processing, body iteration, etc. 86 * 87 * <p> 88 * The JSP container will resynchronize any AT_BEGIN and AT_END 89 * variables (defined by the associated tag file, TagExtraInfo, or TLD) 90 * after the invocation of doTag(). 91 * 92 * @throws javax.servlet.jsp.JspException If an error occurred 93 * while processing this tag. 94 * @throws javax.servlet.jsp.SkipPageException If the page that 95 * (either directly or indirectly) invoked this tag is to 96 * cease evaluation. A Simple Tag EventHandler generated from a 97 * tag file must throw this exception if an invoked Classic 98 * Tag EventHandler returned SKIP_PAGE or if an invoked Simple 99 * Tag EventHandler threw SkipPageException or if an invoked Jsp Fragment 100 * threw a SkipPageException. 101 * @throws java.io.IOException If there was an error writing to the 102 * output stream. 103 */ 104 public void doTag() 105 throws javax.servlet.jsp.JspException, java.io.IOException; 106 107 /** 108 * Sets the parent of this tag, for collaboration purposes. 109 * <p> 110 * The container invokes this method only if this tag invocation is 111 * nested within another tag invocation. 112 * 113 * @param parent the tag that encloses this tag 114 */ 115 public void setParent( JspTag parent ); 116 117 /** 118 * Returns the parent of this tag, for collaboration purposes. 119 * 120 * @return the parent of this tag 121 */ 122 public JspTag getParent(); 123 124 /** 125 * Called by the container to provide this tag handler with 126 * the <code>JspContext</code> for this invocation. 127 * An implementation should save this value. 128 * 129 * @param pc the page context for this invocation 130 * @see Tag#setPageContext 131 */ 132 public void setJspContext( JspContext pc ); 133 134 /** 135 * Provides the body of this tag as a JspFragment object, able to be 136 * invoked zero or more times by the tag handler. 137 * <p> 138 * This method is invoked by the JSP page implementation 139 * object prior to <code>doTag()</code>. If the action element is 140 * empty in the page, this method is not called at all. 141 * 142 * @param jspBody The fragment encapsulating the body of this tag. 143 */ 144 public void setJspBody( JspFragment jspBody ); 145 146 147 }