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