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.JspContext; 029 030 /** 031 * Interface for defining Simple Tag Handlers. 032 * 033 * <p>Simple Tag Handlers differ from Classic Tag Handlers in that instead 034 * of supporting <code>doStartTag()</code> and <code>doEndTag()</code>, 035 * the <code>SimpleTag</code> interface provides a simple 036 * <code>doTag()</code> method, which is called once and only once for any 037 * given tag invocation. All tag logic, iteration, body evaluations, etc. 038 * are to be performed in this single method. Thus, simple tag handlers 039 * have the equivalent power of <code>BodyTag</code>, but with a much 040 * simpler lifecycle and interface.</p> 041 * 042 * <p>To support body content, the <code>setJspBody()</code> 043 * method is provided. The container invokes the <code>setJspBody()</code> 044 * method with a <code>JspFragment</code> object encapsulating the body of 045 * the tag. The tag handler implementation can call 046 * <code>invoke()</code> on that fragment to evaluate the body as 047 * many times as it needs.</p> 048 * 049 * <p>A SimpleTag handler must have a public no-args constructor. Most 050 * SimpleTag handlers should extend SimpleTagSupport.</p> 051 * 052 * <p><b>Lifecycle</b></p> 053 * 054 * <p>The following is a non-normative, brief overview of the 055 * SimpleTag lifecycle. Refer to the JSP Specification for details.</p> 056 * 057 * <ol> 058 * <li>A new tag handler instance is created each time by the container 059 * by calling the provided zero-args constructor. Unlike classic 060 * tag handlers, simple tag handlers are never cached and reused by 061 * the JSP container.</li> 062 * <li>The <code>setJspContext()</code> and <code>setParent()</code> 063 * methods are called by the container. The <code>setParent()</code> 064 * method is only called if the element is nested within another tag 065 * invocation.</li> 066 * <li>The setters for each attribute defined for this tag are called 067 * by the container.</li> 068 * <li>If a body exists, the <code>setJspBody()</code> method is called 069 * by the container to set the body of this tag, as a 070 * <code>JspFragment</code>. If the action element is empty in 071 * the page, this method is not called at all.</li> 072 * <li>The <code>doTag()</code> method is called by the container. All 073 * tag logic, iteration, body evaluations, etc. occur in this 074 * method.</li> 075 * <li>The <code>doTag()</code> method returns and all variables are 076 * synchronized.</li> 077 * </ol> 078 * 079 * @see SimpleTagSupport 080 * @since 2.0 081 */ 082 public interface SimpleTag extends JspTag { 083 084 /** 085 * Called by the container to invoke this tag. 086 * The implementation of this method is provided by the tag library 087 * developer, and handles all tag processing, body iteration, etc. 088 * 089 * <p> 090 * The JSP container will resynchronize any AT_BEGIN and AT_END 091 * variables (defined by the associated tag file, TagExtraInfo, or TLD) 092 * after the invocation of doTag(). 093 * 094 * @throws javax.servlet.jsp.JspException If an error occurred 095 * while processing this tag. 096 * @throws javax.servlet.jsp.SkipPageException If the page that 097 * (either directly or indirectly) invoked this tag is to 098 * cease evaluation. A Simple Tag Handler generated from a 099 * tag file must throw this exception if an invoked Classic 100 * Tag Handler returned SKIP_PAGE or if an invoked Simple 101 * Tag Handler threw SkipPageException or if an invoked Jsp Fragment 102 * threw a SkipPageException. 103 * @throws java.io.IOException If there was an error writing to the 104 * output stream. 105 */ 106 public void doTag() 107 throws javax.servlet.jsp.JspException, java.io.IOException; 108 109 /** 110 * Sets the parent of this tag, for collaboration purposes. 111 * <p> 112 * The container invokes this method only if this tag invocation is 113 * nested within another tag invocation. 114 * 115 * @param parent the tag that encloses this tag 116 */ 117 public void setParent( JspTag parent ); 118 119 /** 120 * Returns the parent of this tag, for collaboration purposes. 121 * 122 * @return the parent of this tag 123 */ 124 public JspTag getParent(); 125 126 /** 127 * Called by the container to provide this tag handler with 128 * the <code>JspContext</code> for this invocation. 129 * An implementation should save this value. 130 * 131 * @param pc the page context for this invocation 132 * @see Tag#setPageContext 133 */ 134 public void setJspContext( JspContext pc ); 135 136 /** 137 * Provides the body of this tag as a JspFragment object, able to be 138 * invoked zero or more times by the tag handler. 139 * <p> 140 * This method is invoked by the JSP page implementation 141 * object prior to <code>doTag()</code>. If the action element is 142 * empty in the page, this method is not called at all. 143 * 144 * @param jspBody The fragment encapsulating the body of this tag. 145 */ 146 public void setJspBody( JspFragment jspBody ); 147 148 149 }