1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. 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 package javax.servlet.jsp.tagext;
18
19 import javax.servlet.jsp.JspContext;
20
21 /**
22 * Interface for defining Simple Tag Handlers.
23 *
24 * <p>Simple Tag Handlers differ from Classic Tag Handlers in that instead
25 * of supporting <code>doStartTag()</code> and <code>doEndTag()</code>,
26 * the <code>SimpleTag</code> interface provides a simple
27 * <code>doTag()</code> method, which is called once and only once for any
28 * given tag invocation. All tag logic, iteration, body evaluations, etc.
29 * are to be performed in this single method. Thus, simple tag handlers
30 * have the equivalent power of <code>BodyTag</code>, but with a much
31 * simpler lifecycle and interface.</p>
32 *
33 * <p>To support body content, the <code>setJspBody()</code>
34 * method is provided. The container invokes the <code>setJspBody()</code>
35 * method with a <code>JspFragment</code> object encapsulating the body of
36 * the tag. The tag handler implementation can call
37 * <code>invoke()</code> on that fragment to evaluate the body as
38 * many times as it needs.</p>
39 *
40 * <p>A SimpleTag handler must have a public no-args constructor. Most
41 * SimpleTag handlers should extend SimpleTagSupport.</p>
42 *
43 * <p><b>Lifecycle</b></p>
44 *
45 * <p>The following is a non-normative, brief overview of the
46 * SimpleTag lifecycle. Refer to the JSP Specification for details.</p>
47 *
48 * <ol>
49 * <li>A new tag handler instance is created each time by the container
50 * by calling the provided zero-args constructor. Unlike classic
51 * tag handlers, simple tag handlers are never cached and reused by
52 * the JSP container.</li>
53 * <li>The <code>setJspContext()</code> and <code>setParent()</code>
54 * methods are called by the container. The <code>setParent()</code>
55 * method is only called if the element is nested within another tag
56 * invocation.</li>
57 * <li>The setters for each attribute defined for this tag are called
58 * by the container.</li>
59 * <li>If a body exists, the <code>setJspBody()</code> method is called
60 * by the container to set the body of this tag, as a
61 * <code>JspFragment</code>. If the action element is empty in
62 * the page, this method is not called at all.</li>
63 * <li>The <code>doTag()</code> method is called by the container. All
64 * tag logic, iteration, body evaluations, etc. occur in this
65 * method.</li>
66 * <li>The <code>doTag()</code> method returns and all variables are
67 * synchronized.</li>
68 * </ol>
69 *
70 * @see SimpleTagSupport
71 * @since 2.0
72 */
73 public interface SimpleTag extends JspTag {
74
75 /**
76 * Called by the container to invoke this tag.
77 * The implementation of this method is provided by the tag library
78 * developer, and handles all tag processing, body iteration, etc.
79 *
80 * <p>
81 * The JSP container will resynchronize any AT_BEGIN and AT_END
82 * variables (defined by the associated tag file, TagExtraInfo, or TLD)
83 * after the invocation of doTag().
84 *
85 * @throws javax.servlet.jsp.JspException If an error occurred
86 * while processing this tag.
87 * @throws javax.servlet.jsp.SkipPageException If the page that
88 * (either directly or indirectly) invoked this tag is to
89 * cease evaluation. A Simple Tag Handler generated from a
90 * tag file must throw this exception if an invoked Classic
91 * Tag Handler returned SKIP_PAGE or if an invoked Simple
92 * Tag Handler threw SkipPageException or if an invoked Jsp Fragment
93 * threw a SkipPageException.
94 * @throws java.io.IOException If there was an error writing to the
95 * output stream.
96 */
97 public void doTag()
98 throws javax.servlet.jsp.JspException, java.io.IOException;
99
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 }