1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * Portions Copyright Apache Software Foundation.
7 *
8 * The contents of this file are subject to the terms of either the GNU
9 * General Public License Version 2 only ("GPL") or the Common Development
10 * and Distribution License("CDDL") (collectively, the "License"). You
11 * may not use this file except in compliance with the License. You can obtain
12 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
13 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
14 * language governing permissions and limitations under the License.
15 *
16 * When distributing the software, include this License Header Notice in each
17 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
18 * Sun designates this particular file as subject to the "Classpath" exception
19 * as provided by Sun in the GPL Version 2 section of the License file that
20 * accompanied this code. If applicable, add the following below the License
21 * Header, with the fields enclosed by brackets [] replaced by your own
22 * identifying information: "Portions Copyrighted [year]
23 * [name of copyright owner]"
24 *
25 * Contributor(s):
26 *
27 * If you wish your version of this file to be governed by only the CDDL or
28 * only the GPL Version 2, indicate your decision by adding "[Contributor]
29 * elects to include this software in this distribution under the [CDDL or GPL
30 * Version 2] license." If you don't indicate a single choice of license, a
31 * recipient has the option to distribute your version of this file under
32 * either the CDDL, the GPL Version 2 or to extend the choice of license to
33 * its licensees as provided above. However, if you add GPL Version 2 code
34 * and therefore, elected the GPL Version 2 license, then the option applies
35 * only if the new code is made subject to such option by the copyright
36 * holder.
37 */
38 package javax.servlet.jsp.tagext;
39
40 import javax.servlet.jsp.JspContext;
41
42 /**
43 * Interface for defining Simple Tag Handlers.
44 *
45 * <p>Simple Tag Handlers differ from Classic Tag Handlers in that instead
46 * of supporting <code>doStartTag()</code> and <code>doEndTag()</code>,
47 * the <code>SimpleTag</code> interface provides a simple
48 * <code>doTag()</code> method, which is called once and only once for any
49 * given tag invocation. All tag logic, iteration, body evaluations, etc.
50 * are to be performed in this single method. Thus, simple tag handlers
51 * have the equivalent power of <code>BodyTag</code>, but with a much
52 * simpler lifecycle and interface.</p>
53 *
54 * <p>To support body content, the <code>setJspBody()</code>
55 * method is provided. The container invokes the <code>setJspBody()</code>
56 * method with a <code>JspFragment</code> object encapsulating the body of
57 * the tag. The tag handler implementation can call
58 * <code>invoke()</code> on that fragment to evaluate the body as
59 * many times as it needs.</p>
60 *
61 * <p>A SimpleTag handler must have a public no-args constructor. Most
62 * SimpleTag handlers should extend SimpleTagSupport.</p>
63 *
64 * <p><b>Lifecycle</b></p>
65 *
66 * <p>The following is a non-normative, brief overview of the
67 * SimpleTag lifecycle. Refer to the JSP Specification for details.</p>
68 *
69 * <ol>
70 * <li>A new tag handler instance is created each time by the container
71 * by calling the provided zero-args constructor. Unlike classic
72 * tag handlers, simple tag handlers are never cached and reused by
73 * the JSP container.</li>
74 * <li>The <code>setJspContext()</code> and <code>setParent()</code>
75 * methods are called by the container. The <code>setParent()</code>
76 * method is only called if the element is nested within another tag
77 * invocation.</li>
78 * <li>The setters for each attribute defined for this tag are called
79 * by the container.</li>
80 * <li>If a body exists, the <code>setJspBody()</code> method is called
81 * by the container to set the body of this tag, as a
82 * <code>JspFragment</code>. If the action element is empty in
83 * the page, this method is not called at all.</li>
84 * <li>The <code>doTag()</code> method is called by the container. All
85 * tag logic, iteration, body evaluations, etc. occur in this
86 * method.</li>
87 * <li>The <code>doTag()</code> method returns and all variables are
88 * synchronized.</li>
89 * </ol>
90 *
91 * @see SimpleTagSupport
92 * @since 2.0
93 */
94 public interface SimpleTag extends JspTag {
95
96 /**
97 * Called by the container to invoke this tag.
98 * The implementation of this method is provided by the tag library
99 * developer, and handles all tag processing, body iteration, etc.
100 *
101 * <p>
102 * The JSP container will resynchronize any AT_BEGIN and AT_END
103 * variables (defined by the associated tag file, TagExtraInfo, or TLD)
104 * after the invocation of doTag().
105 *
106 * @throws javax.servlet.jsp.JspException If an error occurred
107 * while processing this tag.
108 * @throws javax.servlet.jsp.SkipPageException If the page that
109 * (either directly or indirectly) invoked this tag is to
110 * cease evaluation. A Simple Tag Handler generated from a
111 * tag file must throw this exception if an invoked Classic
112 * Tag Handler returned SKIP_PAGE or if an invoked Simple
113 * Tag Handler threw SkipPageException or if an invoked Jsp Fragment
114 * threw a SkipPageException.
115 * @throws java.io.IOException If there was an error writing to the
116 * output stream.
117 */
118 public void doTag()
119 throws javax.servlet.jsp.JspException, java.io.IOException;
120
121 /**
122 * Sets the parent of this tag, for collaboration purposes.
123 * <p>
124 * The container invokes this method only if this tag invocation is
125 * nested within another tag invocation.
126 *
127 * @param parent the tag that encloses this tag
128 */
129 public void setParent( JspTag parent );
130
131 /**
132 * Returns the parent of this tag, for collaboration purposes.
133 *
134 * @return the parent of this tag
135 */
136 public JspTag getParent();
137
138 /**
139 * Called by the container to provide this tag handler with
140 * the <code>JspContext</code> for this invocation.
141 * An implementation should save this value.
142 *
143 * @param pc the page context for this invocation
144 * @see Tag#setPageContext
145 */
146 public void setJspContext( JspContext pc );
147
148 /**
149 * Provides the body of this tag as a JspFragment object, able to be
150 * invoked zero or more times by the tag handler.
151 * <p>
152 * This method is invoked by the JSP page implementation
153 * object prior to <code>doTag()</code>. If the action element is
154 * empty in the page, this method is not called at all.
155 *
156 * @param jspBody The fragment encapsulating the body of this tag.
157 */
158 public void setJspBody( JspFragment jspBody );
159
160
161 }
Save This Page