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 }