KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > servlet > jsp > tagext > SimpleTag


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 JavaDoc;
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 JavaDoc {
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 JavaDoc, java.io.IOException JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc jspBody );
138
139     
140 }
141
Popular Tags